1. How to get to your mods folder
Your mod's folder is located atWindows -
%appdata%\Sonic3AIR\mods\
Linux(If you can get the game working with wine) -
~/.wine/drive_c/users/(username)/Application Data/Sonic3AIR/mods/
You can get there in 2 ways
- Go to the folder
- Right click the game while its loading, playing or anything but erroring and click "Open Save Data Folder"
All the screenshots you will see are from Linux although it should be the same on Linux and Windows (Not sure if Sonic3AIR works on Mac via Wine)
2. Prerequsites
- Some music
- And a text editor (I will be using Sublime Text but Notepad++, VSCode or normal notepad will also work)
- The ability to see filetypes(On Windows, Open explorer, click View then toggle "Show filetypes")
3. Terms used
OGG - The OGG File format. Commonly used in Video Games because it's free, open sourced and lightweight(Also used in Sonic 3 AIR for mods and such)MP3 - The MPEG-3 file format. Commonly used in albums or CD's
JSON - A popular data format used commonly for Config's and storing data for things like Games and applications
4. Step 1 - Getting the files and folders we need
After heading to your mods folder you're going to want to make a new folder named what you want to name your mod, Then inside that folder you're going to want a folder named "audio" and a file named "mod.json", Your mods folder should be laid out like the below
Open up the mod.json file with your text editor and input this
{ "Metadata": { "Name": "My Music Mod", "Author": "Me!", "Description": "A pack that add's music I like!", "URL": "", "ModVersion": "1.0", "GameVersion": "Game version" } }Change everything to what you want. You can get the game version from the top right of the title screen.
Now you will need to grab the "audio_replacements.json" file from the folder for sonic3AIR you downloaded, go to the folder that you extracted Sonic 3 AIR to, then go to docs > modding > audio then you should see a file named "audio_replacements.json" or "audio_replacements".(depending on if you have file extensions on)
Copy that to the audio folder we created earlier.
You'll also need to copy some OGG files over with the audio_replacements file.
They have to be OGG files. I would recommend using Audacity's "export" feature to export as an OGG file if its a MP3, WAV or most other types of music files. MIDI is not supported though
If you need to do a bunch of files then I'd recommend Fre:ac, which is on Windows, Mac and Linux
5. Step 2 - Editing the file
So we have finally stopped messing around with file locations and its time to get serious.I am guessing you want to instantly edit the file but if you are not used to json files then you probably won't understand them
Here is some example code:
{Do you understand how this is laid out? No? Don't feel bad,
//AIZ 1
"01": { "File": "my_music.ogg", "Type": "Music" }
}
This is what you would put in to edit the music for angel island zone.
The 01 in quotes stands for the song you want to replace in its megadrive value
the
{ "File": "my_music.ogg", "Type": "Music" }Tells the game that you want to use "my_music.ogg" and tells the game that it's type is "Music" so to edit hydrocity zone act one I would do
{Don't forget to replace the "music_file.ogg" with your song name, so for example I would use "sonic-mania-hydrocity-zone.ogg" if I had a file named "sonic-mania-hydrocity-zone.ogg" in the audio folder.
"03": { "File": "music_file.ogg", "Type": "Music" }
}
Getting lost yet?
From 01 to 17 are all of the zone's but it is not done as you may think instead of 8-9-10-11 it is 08-09-0A-0B-0C-0D-0E-0F-10 Instead so for flying battery zone you would use
"0A": { "File": "my_music.ogg", "Type": "Music" }Not
"10": { "File": "my_music.ogg", "Type": "Music" }If you need any more help just look at the example audio-replacements.json file and that should help. For my audio mod that I made(It just replaces the invincibility and super theme) I used

Just for a recap, the word's/numbers in the first quotes are the ID of the song,
"File": "super.ogg"is the song file that we want to use so for example
"25_sonic3": { "File": "bgm_title.ogg", "Type": "Jingle" }
will change the sonic 3 title song the the file named "bgm_title.ogg" in the audio folder.
Whenever you have multiple songs always add a comma next to the last song like this
}It is important you add that comma as the game will error if you miss a comma, and lastly always add the "{" at the beginning and add the "}" at the end.
"2C": { "File": "invinc.ogg", "Type": "Music" },
"supertheme_sonic2": { "File": "super.ogg", "Type": "Music" }
}
Feel free to tell me if I did or got something wrong, also if you need a good JSON parser/JSON editor then use Duck Duck Go's JSON Beautifier, jsoneditoronline, or jsonformatter
6. Extra Step - Looping (Thanks to MaybeGreg for this part)
Looping your music can be difficult if you aren't sure what you're meant to do, but let's go through it.Bring your music track back into Audacity. What you want to do is find the point where the music jumps back to a previous point, or if it doesn't naturally a point where it can. Example. This point in the song is where the goes back. Delete everything from this point onwards. No point having extra.
Now that we've got the end of the loop, we need to go to the start. This is where everything extra you just deleted is played for the first time. In our example case, here. Select the exact point. At the bottom of Audacity, you see the current time. Click the selector, and choose samples. Keep note of this number.
Now, export the song as stated above.
Go into your json again, and do the exact same steps. However, this time, it should look more like this:
"0A": { "File": "my_music.ogg", "Type": "Music", "LoopStart": "X" }Remember that number you wrote down?
Replace X with that. Save it, restart your game, and you should be able to hear the loop work just fine. Here's my SMB1 example in practice:
"0A": { "File": "SMB1_Overworld.ogg", "Type": "Music", "LoopStart": "114688" }
7. Step 3 - Finalising
So now you have completed your mod and you want to play with it ingame, well that's easy just boot up the game and hope you did not mess up any of the code.
If you need help feel free to ask in the comments and me or someone else will probably help you, Have fun modding the game!