How To Add MUSIC To RetroPie In 5 Commands!

RetroPie with music

UPDATED: 7th March 2020

So you finally have your RetroPie setup and working. That’s great! but then you realise that things are just a little.. too quiet?!

Let’s add some killer background music to this little rig.


This post assumes one thing.. that your RetroPie is running on a Raspberry Pi.


In this post I will take you over the steps that I performed to not only add background music with the ability to turn it on and off from the config menu, but I added some extra functionality too.


We can also select an option to: 

  • start playing the music automatically when the Pi boots up, or not
  • we can continue to play the music over the top of games
  • and we can also hide some of the more, shall we say less appropriate music for when the kids get a chance to experience this excellent little gaming box (GTA “Joyride” by Da Shootaz anyone? ;).

With all these settings available to us, we’re gonna need a way to see what’s been switched on or off! For this I created an “info” script, that when executed from Emulation Station front-end config menu, will display what our current state is with our music options.


This post takes you through the manual method and the automated method.

I would highly recommend taking the automated method but reading through this post will describe how the automated script is working.


Are you ready? ..Let’s do this!


RetroPie with music options
Custom config menu showing music options

Secure Shell In To The Pie

The easiest way to follow along with this guide would be to SSH in to your Raspberry Pi as you can simply copy the commands/text over from this post and paste them into the terminal. To paste text into the terminal, use CTRL + SHIFT + V

Fire up a linux terminal (or what ever system you are rocking) on your PC/laptop and run the command:

ssh pi@ip_address

where ip_address is your RetroPie’s IP Address. It will most likely start with 192.168. It can be found in the config menu of your Pi or by pressing F4 on a keyboard and running the command:


If you get the response “connection refused” then we may need to turn on the SSH service. To do this we need to get to a terminal on the Pi by pressing F4 on a keyboard. Now run the command:

sudo touch /boot/ssh

enter the password if prompted (default password is: raspberry)

then reboot the Pi with the command:

sudo reboot

When the RetroPie boot’s up again we can then try and SSH in to it again. You may need to check the IP address as it may have changed.

If you get a crazy warning that starts with the following:


then copy and paste the line that starts with “ssh-keygen -f ” but add the word sudo at the beginning, and run it.

Type the word “yes” if prompted and enter the RetroPie password if your asked to do so.

Hopefully you’re now greeted with the RetroPie ‘message of the day’ and I’m now assuming you have an SSH session!

retropie ssh login
SSH session to RetroPie


The menu items are all linux shell scripts. These are known as “non-interactive” scripts. That is, the user doesn’t interact with them. They execute, and that’s it.


This was my “quick and dirty” way of getting music options to work but with a little more time spent on the functionality, It would be possible to allow the user to go through a dialog box and select the options there by using the controller.

But maybe this will be improved by me in the future.


You may not want all of the options that I created, so I will take you though the basics first, on how you can get music to play, with the ability to turn it off and on.

We will also pause the music automatically whenever we start up a game.


When the game ends and we return back to Emulation Station, our music will un-pause and it will continue to play from where we had left off.


All of the other options that I will go over will build upon each other, and get more complex as each new function is added.


Flag Files

Flag files are simply text files that store a value in it. In my case I used a 1 and a 0 to represent on/off.

When ever a setting is changed by the user, this setting is stored in the flag file. For example, If the user selected an option to turn off the music then not only will the music stop, but a 0 will over-write anything that was in the flag file. 

This way we can use a script to check if the music is playing at that particular time or not.

2 Run Command Scripts



These two scripts are part of RetroPie. When ever we start playing a game, the script will run.

Similarly, when ever we quit out of our game and return to Emulation Station, the script will run.

We can use these scripts to make some of our music functionality work.


Startup Script


The script is also part of RetroPie. This script runs when we first boot up our RetroPie. This is what’s responsible for starting Emulation Station.

We can also use this start-up script to automatically play our music when we first turn on the Pi.

User Controlled Scripts


Here we will be creating our very own shell scripts. This is what is seen by the user in the RetroPie Config screen.

The scripts can be executed when ever the user selects them for turning the music on and off for example.

These are the scripts that will be changing the flag files.

Step 1:

Add music files

If you’re looking for some excellent background music then I can’t help you with that, but there might be some here.


There are two ways in which we can add our files to RetroPie and it’s all down to you in which you have yours setup. You will be either: 

A) MOUNTING a USB device which holds all of your ROM’s etc, or: 

B) you will be COPYING over your ROM’s and other files to the micro SD card FROM a USB device.


For this tutorial I will be covering option ‘A’ as this is how I have mine setup. Hopefully I can return to this post in the near future and update it once I’ve worked out the steps to get your music files on your SD card.

retropie mount directory

Plug your USB memory device into a PC/laptop. If you’re mounting all of your files in to your RetroPie linux file system then you should have/create a “retropie-mount” directory in the root of your USB drive.


move in to the “retropie-mount” directory and create a new directory called “music” and place all of your mp3 files in to this new “music” directory.


I believe that the music player that we are going to use in this post (mpg123) can only play mp3 music files but I haven’t tested other audio file types as of yet, so best stick with mp3 for the purpose of following along with me on this.


When you have your epic music collection ready for your pie, we need to remove the USB device from your PC/laptop and plug it back in to your Raspberry Pi and switch on the Pi.

Now we’re ready to move on to the next step!

Step 2:

Hide unwanted config options

Before we start to fill up our config menu with all of our new music options, it may be a good idea to hide all of those other default options when we’re finished with using them.

I’m using the Back2Basics theme here so yours could look very different to mine. However the steps are still the same. Navigate to your Config screen.

default retropie config
My config screen before hiding the options

When I was at the final stages of configuring my RetroPie, I removed my wifi settings.

That way no one can do any updates over the internet as updating any emulators or other software could potentially break what is a perfectly working system.


After I removed my wifi settings from the ‘WIFI’ menu option and disconnect my RetroPie from the internet, I could then go ahead and remove the ‘WIFI’ option from the config menu.


In fact, I removed all of the default options once I was finished with them, except for the bluetooth option. We may need this to configure any bluetooth controllers in the future.


However, DON’T remove your internet connection JUST yet, as we need to install our music program which I explain how to do this at Step 3.

How to remove/hide Config items

We firstly need to get to a linux terminal in our RetroPie.

his can be achieved by SSH’ing in, or by plugging in a USB keyboard in to our Raspberry Pi and pressing the F4 key.


Once we are presented with a terminal we now need to change to the directory we are going to be working in.
Enter the following command to change to the “retropiemenu” directory:
cd /home/pi/RetroPie/retropiemenu

By default, any file that ends in .sh or .pl will be shown in our RetroPie Config menu in the front-end (Emulation Station).


So what we need to do if we want to hide these options is to rename the files so they don’t end in .sh or .pl


For this, I renamed the files with a .1 extension. To achieve this we use the mv command. Move (mv) will rename a file in linux.


So for example then, if I want to remove the wifi option from the front-end, I now need to rename the file “” to

I did this using the following command:



Do this for every file/option that you don’t want to appear in your Config screen.

We can test this out by going back into Emulation Station by typing the following command in to the terminal:



Once Emulation Station has started and we go into the Config menu, our options don’t appear to have taken affect yet.


If we press the Start button on the controller and select the option to restart Emulation Station, wait for Emulation Station to restart then check our Config menu once again, we will see that we have successfully hidden some on the options by simply renaming the files with the .1 extension.

Step 3:

The basics: Getting music to play

First of all we will need our RetroPie connected to the internet.

Then we will need to get to a terminal.


This can be done either by using a keyboard connected to your Pie and pressing the F4 key, or by SSH’ing in to the Pie.

I won’t be covering any of the above in this post so I’m assuming you already know how to get this far.


We need to install a program called mpg123. To do this we need to enter the following command:

sudo apt-get -y install mpg123


After the installation of mpg123 has finished (and successfully), we can now test out our music player.


We need to stay in the terminal and we need to move our current working directory to where our music files are stored. Type the following command to do this:

cd ~/retropie/music


we can then type ls to list all of our music files. Now, type: mpg123 * (there’s a space between 3 and *)


Our music should now be playing.

We can type f on the keyboard and mpg123 will skip to the next song. Only when we have successfully tested our mp3 files and mpg123 music player can we then continue to add our music functionality to our system.

Step 4:

Stop & Start Music

To be able to stop and start music playing, we need to create the scripts. To create the ‘Start Playing Music’ script, enter the following command:

nano /home/pi/RetroPie/retropiemenu/Music\

and paste in the following:

pkill -CONT mpg123

echo “1” > /home/pi/music_settings/user_switch/onoff.flag


Now create the ‘Stop Playing Music’ script:

nano /home/pi/RetroPie/retropiemenu/Music\

and paste in the following:

 pkill -STOP mpg123

echo “0” > /home/pi/music_settings/user_switch/onoff.flag


 Create the flag directory with:

mkdir /home/pi/music_settings/user_switch

and create the flag file:

echo “0” > /home/pi/music_settings/user_switch/onoff.flag


You may be wondering why a flag file is used here. This is to make our other settings work correctly.


It should be possible now to start and stop our music from the config menu. 


Now we need to edit the run-command scripts. This will stop our music playing when we run a game, and start the music when we end a game. Don’t worry, if you want music to continue to play, I will cover that functionality later down this post.

Enter the following command:

 nano /opt/retropie/configs/all/

and paste in the following:

 pkill -STOP mpg123


Save the file and exit. Now enter the following command:

 nano /opt/retropie/configs/all/

and paste in the following lines:

 if [[ $(cat /home/pi/music_settings/user_switch/onoff.flag) == “1” && $(cat /home/pi/music_settings/onoff.flag) == “1” ]]


        pkill -CONT mpg123



Step 5:

Start up the system with music playing (on/off)

Once we have tested mpg123 and it plays our mp3 music files we can now configure the system to boot up with our music playing automatically.


To do this we need to create the ‘Startup with music on’ script:

nano /home/pi/RetroPie/retropiemenu/Startup\ With\ Music\

and paste the following lines into it:


echo “1” > /home/pi/music_settings/onoff.flag

exit 0

Save and exit with Ctrl + x, and select ‘y’ to save

Now make the script executable with the following command:

chmod +x /home/pi/RetroPie/retropiemenu/Startup\ With\ Music\


Next we need to make the ‘off’ script which is almost identical, except now we will echo a zero in to the flag file.

Create the ‘off’ script with the following command:

nano /home/pi/RetroPie/retropiemenu/Startup\ With\ Music\

and paste the following lines into it:


echo “0” > /home/pi/music_settings/onoff.flag

exit 0

Save and exit with Ctrl + x, and select ‘y’ to save

Now make the script executable with the following command:

chmod +x /home/pi/RetroPie/retropiemenu/Startup\ With\ Music\





Now we need to create the flag file. Create a directory for the flag file to live:

mkdir /home/pi/music_settings

Now create the flag file with the ‘off’ option set by simply entering a zero into the file:

echo “0” > /home/pi/music_settings/onoff.flag



 And Finally we need to modify the start-up script. 

 nano /opt/retropie/configs/all/

Paste the following lines in the script file, above the line “emulationstation #auto”

#init play music

while pgrep omxplayer > /dev/null; do sleep 1; done

sleep 2

mpg123 -Z /home/pi/RetroPie/music/*.mp3 > /dev/null 2>&1 &


#If music off at bootup is selected then disable it

if [ $(cat /home/pi/music_settings/onoff.flag) == “0” ]


pkill -STOP mpg123



The first part of the commands will start the music, then next part will immediately stop the music if you have chosen the option to NOT have music playing at boot-up.

The reason why we start the music even though we are going to be stopping it, is so that the process can be created. If we choose to play music later then that same process is used.

Now would be a great time to test this feature. Run the ‘on’ script from the Config Menu and reboot the system. Hopefully you should have music playing from the start.


Step 6:

Disable/Enable adult music

For this to work I needed to do two things.

I needed to create another music folder to move the adult music over to. Next to the music folder we created earlier, create another folder called “music-adult” (in the “retropie-mount” folder on the USB drive).


Next I needed to rename my mp3 files in which I wanted to hide from the kids. I renamed the chosen mp3 files so they were prefixed with “ADULT-“. For example: my_adult_song1.mp3 is now named ADULT-my_adult_song1.mp3


Once this is done we need to edit the startup script that will move these mp3 files over to the “music-adult” folder at boot-up.


Now these music files won’t be in our music playlist.

The reason why this needs to happen at startup is that if someone was currently listening to one of these adult songs, then moving the mp3 file to another directory wouldn’t work as the file is in use.


To overcome this, I decided to move the adult songs during boot-up of the RetroPie, right before any music would start to play. This is the reason why the system requires a reboot for the option to take affect.


When either the Enable Adult Music or the Disable Adult Music option is chosen, all that happens is a flag is set. This flag is checked for at boot up.



Create the ‘Adult Music On’ ‘script file with the following command:

nano /home/pi/RetroPie/retropiemenu/Adult\ Music\ On\ \(Requires\ Reboot\).sh

and paste the following lines into the file:


echo “1” > /home/pi/music_settings/adult_songs/onoff.flag

exit 0


Make the file executable with the following command:

chmod +x /home/pi/RetroPie/retropiemenu/Adult\ Music\ On\ \(Requires\ Reboot\).sh


Next we will create the ‘Adult Music Off’ script with the following command:

nano /home/pi/RetroPie/retropiemenu/Adult\ Music\ Off\ \(Requires\ Reboot\).sh

and paste the following lines into the file:


echo “0” > /home/pi/music_settings/adult_songs/onoff.flag

exit 0


Now create a directory for the flag file:

mkdir /home/pi/music_settings/adult_songs/

And now create the flag file:

echo “0” > /home/pi/music_settings/adult_songs/onoff.flag


The last thing we need to do here is modify the startup script. This will check your flag setting, and if you want adult music hidden then it will move over all the mp3 files that start with ‘ADULT-‘ at the beginning of the file name, to the music-adult directory.

However, if you want adult music ON, the script will move all mp3 files that exist in the ‘music-adult’ directory, over to the ‘music’ directory and will be available in the playlist.


 To open the startup script for editing, enter the following command:

nano /opt/retropie/configs/all/


and make it look like the following:


#disables/enables adult music

if [ $(cat /home/pi/music_settings/adult_songs/onoff.flag) == “0” ]


        mv /home/pi/RetroPie/music/ADULT-*.mp3 /home/pi/RetroPie/music-adult/ 2>/dev/null


mv /home/pi/RetroPie/music-adult/ADULT-*.mp3 /home/pi/RetroPie/music/ 2>/dev/null



#resets the switch where the user manually switched off the music in the last session


echo “1” > /home/pi/music_settings/user_switch/onoff.flag


#init play music

while pgrep omxplayer > /dev/null; do sleep 1; done

sleep 2

mpg123 -Z /home/pi/RetroPie/music/*.mp3 > /dev/null 2>&1 &


#If music off at bootup is selected then disable it

if [ $(cat /home/pi/music_settings/onoff.flag) == “0” ]


pkill -STOP mpg123



emulationstation #auto



Step 7:

Continue to play music over the games

Some of us will want to play our killer tunes over the top of our games. Please note that it may not be possible to turn off the in-game music, and so you will have the game music playing, as well as our custom music. This is not cool.

Feel free to experiment at will here.

Firstly we will create the flag file and it’s directory. Execute the following command:

mkdir /home/pi/music_settings/music_over_games

now create the flag file:

echo “0” > /home/pi/music_settings/music_over_games/onoff.flag

Now we need to edit the run-command scripts that will execute when the game starts and ends.

 nano /opt/retropie/configs/all/

and paste the following lines:

 if [ $(cat /home/pi/music_settings/music_over_games/onoff.flag) == “0” ]; then

        pkill -STOP mpg123


 Edit the ‘onend’ script with the following command:

nano /opt/retropie/configs/all/

and paste in the following:

 if [[ $(cat /home/pi/music_settings/user_switch/onoff.flag) == “1” && $(cat /home/pi/music_settings/onoff.flag) == “1” ]]


if [ $(cat /home/pi/music_settings/music_over_games/onoff.flag) == “0” ]; then

        pkill -CONT mpg123




Step 8: (Optional)

Add an "info" script

Yeah I guess this step is optional but I would highly recommend it as it’s very easy to forget what custom audio settings you may have active, and this would be the place to go and get that info.


Obviously if you can hear music then the music is playing and so this information doesn’t need to be placed in the ‘info’ script! However, the settings that I do want info on are: 

a) Is adult music option on or off? 

b) Is the music set to automatically start playing when I boot up my Pie? 

c) Will the music continue to play when I fire up a game ROM?


Because this is a non-interactive script, I added a nine second count-down. This gives you enough time to view the settings before the script returns back to Emulation Station.


Ideally, this script would be interactive and have some kind of Back or Return button for the user to press when they’re done, but the nine second count-down of a non-interactive script was a quick fix for me at the time. 


Why nine seconds you may ask? Why not ten?! ha, well this just seemed like the optimal time to view everything I needed to see. I didn’t want the screen to over-stay it’s welcome 😛

If you would like to use my ‘info’ script as a template for your own project then you can download it here:

Automated Method

Tested on Retropie version 4.5.1

This automated method should have music playing on your RetroPie in just a few minutes!

Make sure you have an internet connection and press the ‘F4’ key on your keyboard to bring up a bash terminal.

Command 1:

Now we need to download the file. Enter the following command into the terminal:


Command 2:

Next we need to uncompress the file with the following command:

tar -xvzf music_setup.tar.gz

Command 3:

Once the file is uncompressed, we need to move in to the “music_setup” directory with the next command:

cd music_setup

Command 4:

Now we need to make the setup script executable:

chmod +x

Command 5:

And finally, run the script:


When the script starts we can hit the “s” key and then ‘Enter’. Wait for the script to finish running and then reboot. That’s it!

If you want to show or hide some menu items that appear in the Retropie settings screen then just run the script once again and choose the “m” option.


If you’re comfortable with working in the shell then this small project shouldn’t be a problem for you.

However if you’re not that comfortable with working in a linux shell then this would make an excellent little project to carry out.


Not to mention that it’s fun! and you will have cool background music over that RetroPie when you’re done 🙂

If you would like some more tips on how you could improve your RetroPie setup then check out my other post “ULTIMATE RetroPie Guide: Tips For Beginner’s“.

New To Linux?

In 2020 I’ll be focused on creating linux tutorials for beginner’s!

These won’t be just some random posts though. I will be covering the Linux Professional Institute 1 (LPIC1) certification!

 A world wide recognised certification that covers all the basics of Linux Administration!

Ideal for retropie/raspberry pi users.

Please follow and like us:

3 thoughts on “How To Add MUSIC To RetroPie In 5 Commands!

  1. Hello, great tutorial.

    Is there a way to play the music but have it stop playing once you select an operating system (Arcade, MAME, NES, etc…) so we can hear the game snaps (video/audio preview). Then have it start playing again once we get out of the operating system.

    Or is there a way to add a music option (operating system) to Retropie like an operating system but rather than selecting games to play we can select music to listen too?

    Thanks again for your knowledge and time.



    1. Hi thanks for the comment.
      This project started to get very complex and so I stopped where I thought would be a good point for this first version.
      However, I might review this in the future. At the moment, there isn’t a music track selection feature but I would look into this at a later time.
      I’m not sure I fully understand your first question but there is an option to either play the music over the games or to pause the music while the game plays. Just select the setting “Continue Music Over Games” ON/OFF

      Hope this helps

  2. Thank You for this. As a complete novice there where a few things that were a challenge but this was exactly what I was looking for. Once I gained a little knowledge I was able to get it all work just fine. Now onto volume controls.

Leave a Reply

Your email address will not be published. Required fields are marked *