How to edit audio_replacements.json

A Tutorial for Sonic 3 A.I.R


Brother we need some loops 1mo
  • - A section talking about loops
I added a section about loop's and how to use them (Thanks to MaybeGreg for the section)
I don't know what to name this 1mo Addition

This explains how to use the audio_replacements.json file

This tutorial shows you how you can make a custom soundtrack for Sonic 3 A.I.R

Your mod's folder is located at
Windows - %appdata%\Sonic3AIR\mods\data

Linux(If you can get the game working for wine) - ~/.wine/drive_c/users/(username)/Application Data/Sonic3AIR/mods/

You can get there in 2 ways
  1. Go to the folder
  2. Rightclick 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)

You will need 2 things
  • Some music
  • And a text editor (I will be using sublime text but Notepad++ will also work)

Step 1 - Getting the files and folders we need

If the data folder does not already exist make the data folder inside the mods folder,

Your mod's folder should now look like the above
Now double click on the 'data' folder and make a folder inside of it called "audio"

(The data folder on the right is not required)
Now we can finally doub- Oh wait if you did not have your folders then you will need 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 the doc's folder and modding then you should see a "audio_replacements.json" or "audio_replacements"(depending on if you have file extensions on) copy that to the audio folder we created earlier and while your at that copy some OGG files over  with the audio_replacements file, Yes they have to be OGG's, I would recommend using audacity's "export" feature to export as an OGG file if its an MP3, Wav or other type of music files, MIDI is not supported though

Step 2 - Editing the file

So we have finally stopped messing around with files 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 Or haven't messed with commands in minecraft then you probably won't understand this
Here is alittle example code
//AIZ 1
    "01": { "File": "my_music.ogg", "Type": "Music" }
Do you understand how this is laid out? No? Don't feel bad,
This is what you would put in to edit the music for angel island zone,
The 01 in qoutes stands for the song you want to replace in its megadrive value
{ "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
    "03": { "File": "music_file.ogg", "Type": "Music" }
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

Getting lost yet?

From 01 to 17 are all of the zone's but It is not done you 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" }
	"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
  "2C": { "File": "invinc.ogg", "Type": "Music" },
"supertheme_sonic2": { "File": "super.ogg", "Type": "Music" }
It is important you add that comma as the game may error if you miss a comma, And lastly always add the "{" at the beginning and add the "}" at the end, tell me if I did something wrong, also if you need a good json parser/JSON  then use or

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" }

Step 3 - Finalising

So now you have completed your mod and you want to play with it ingame, well thats 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, Have fun modding the game!


Share banner
Image URL
HTML embed code
BB embed code
Markdown embed code


Key Authors
Making the tutorial
8,322 points Ranked 704th
19 medals 1 legendary 3 rare
  • Submitted 100 Skins Medal icon
  • Returned 1000 times Medal icon
  • Achieved Game Manager clearance Medal icon
  • Submitted 50 Skins Medal icon
  • One month a member Medal icon
  • 6 months a member Medal icon
For helping with loop's
Special Thanks
For making Sonic 3 AIR & knuckles
Sega & knuckles
For Sonic 3 & Knuckles


Superpowers04 avatar
Superpowers04 Joined 1y ago
777 points Ranked 41976th
6 medals 1 rare
  • Returned 1000 times Medal icon
  • One month a member Medal icon
  • Returned 100 times Medal icon
  • 6 months a member Medal icon
  • Submission featured Medal icon
  • 1 year a member Medal icon
  • Donate by commenting
    Superpowers04's Donate by commenting
    Just comment suggestion's, I don't do any of this for money, just to make people happy and have fun :P
Sign up to access this!
Sign up to access this!
Sign up to access this!


Sign up to access this!



Difficulty Level



  • Share on Reddit
  • Share on Twitter
  • Share on Facebook
  • Today's Pick
    Featured on Apr 16 2019
  • 2
  • 1.0k
  • 16
  • 1mo
  • 19d
  • 1mo