Portable Native MOD Player Based on Raspberry PI (plays MOD,S3M,IT,XM Etc...). Uses BassPlay Library.




Introduction: Portable Native MOD Player Based on Raspberry PI (plays MOD,S3M,IT,XM Etc...). Uses BassPlay Library.


Raspberry-PI based native MOD player to play music modules MOD,S3M,IT,XM among others.
It uses command-line player based on bass-play libraries.

Short description of music modules:

Music modules originates from Amiga computers, later were transferred to another platforms.
The main principe is the file containing sound samples and patterns containing information of when and how particular sound should be played.
As there are players for Windows, Linux and other platforms nowadays, portable players can play just mp3 files which was my motivation to construct this player.

More resources regarding music modules:



As long-time enthusiast of music modules, I've dreamed about native portable player.
Raspberry PI has allowed this.
It uses command-line player (running on default Raspbian) to be started/stopped by script.

Principe of the operation:

Buttons shorts pull-up resistors to change GPIO pins's state from 1 to 0.
Scripts checks GPIO's pins and executes particular action (play/stop/next/previous).

Used parts:

Raspberry Pi with default Raspbian.
Suitable casing (an old walkman in my case).
Buttons, possibly PCB and wires/connectors (depends on your design)
Micro-usb connector to power raspberry as designed.
4 10KOhm resistors

Necessary files:

These libraries are being used:


Command-line player based on libraries above:


Default Raspbian from official website:


Control scripts to control player above via buttons trough GPIO are included in this project.

Construction notes:

The software part is most tricky step of the project (I've made it as verbose as possible).
Wiring of pull-up resistors and buttons is simple on its own, I'd suggest to try first on bread board before soldering if you have a little soldering experience.

Final notes:

I've tried to make steps below as easy  to understand as possible.
If you'll get puzzled and/or have any questions/tips please let me know and I'll update this project.


MANY THANKS to Aleksander Mosingiewicz  for creating command-line player based on the bass-play libraries and figuring out the way to compile it on Raspberry. I wouldn't be able to finish the project without him.
Other thanks goes to Raspberry team for great piece of hardware and Un4seen Development for bassplay libraries.
I'd like to thank the guys at www.brmlab.cz and www.bytefest.org and www.praseparty.cz for encouraging me to publish this.
Last but not at least I'd like to thank my parents for supporting me.

Step 1: Hardware Part - GPIO Control

Player is controlled through Raspberry's GPIO pins (pull-up 10K resistors connected between GPIO pins and 3.3V, grounded by the button).
Source of 3.3V and ground is available on GPIO.
This changes the state of particular pin in  /sys/class/gpio/gpio"$PIN"/value.
Script uses this change as a condition for particular action.

Notes about GPIO:

As Raspberry's GPIO pin-out differs around versions, I'm including just pin names as being used by the script.
Please check the documentation for your particular version to find out the location of pins.

Input (button control - mandatory):

GPIO11 - play
GPIO9 - stop

GPIO10 - next song
GPIO22 - previous song

Output (optional LEDs):

GPIO02 - player ready
GPIO03 - play led
GPIO04 - stop led
GPIO17 - unused

Step 2: Hardware Part - Power Supply

In the prototype, battery consists of 4 AAA Ni-MH cells as AA Ni-CD cells wouldn't fit.
I use universal charger intended mainly for RC models to charge Ni-MH cells but if you possess only charger for AA Ni-Cd cells then I'd suggest to stick to these.
Raspberry operates safely on 4.8V so 4 AA or AAA 1.2V calls may be used.
You need a micro-usb connector to power raspberry as designed.

Step 3: Software Part - OS Preparation

Download and run default Raspbian from http://www.raspberrypi.org/downloads

Gain root access by using command:

sudo passwd

Then you can log in as root by using your password.

Disable X11 as we don't need these. You can install/use utility rcconf to make it easier:

apt-get  install rcconf

Step 4: Software Part - Compiling of the Player for Raspberry PI

The most tricky part is to put correct libraries in the correct directory.
MANY THANKS to Aleksander Mosingiewicz (author of the player) for figuring out!

All commands are being executed as root.

Gain root access using command:

sudo passwd

Then you can log in as root by your password.

There are some packages to install before compiling:

aptitude update

aptitude install intltool

aptitude install libgtk2.0-dev

Preparation of source code and libs:

Put hardfp/libbass.so from bass24-linux-arm.zip in:


Unzip source code:

tar -zxvf bassplay-0.1.tar.gz

unzip bass24-linux.zip in subdirectory bass in the directory of source code bassplay-0.1/bass.
!Do the same with bass24-linux-arm.zip and overwrite files!.

mkdir bassplay-0.1/bass
cp bass24-linux.zip bassplay-0.1/bass/
cp bass24-linux-arm.zip bassplay-0.1/bass/
unzip bassplay-0.1/bass/bass24-linux.zip
unzip bassplay-0.1/bass/bass24-linux-arm.zip

Proceed with compilation:

cd bassplay-0.1

make install

Step 5: Software Part - Install Alsa Mixer

You can install the mixer by using command:

aptitude install alsa-utils

Step 6: Software Part - Test of the Player Itself

Please upload some modules to the Raspberry (scp is the easiest way) and try to play some:

bassplay somemusic.mod

You can use alsa and amixer to set up volume by and other sound adapter settings by your needs.
If you can play modules from command line now please proceed further.

!Please contact me in case of any difficulties with steps above and I'll try to figure out and/or update this how-to!

Step 7: Software Part - Installation of Control Scripts.

Please download file scripts.zip from project's intro page.

Upload file to the raspberry and unpack by command:

unzip scripts.zip

Put project included scripts in the directories and change privileges as shown:

chmod 777 /etc/init.d/player_control.sh
chmod 777 /usr/bin/gpout.sh
chmod 777 /usr/bin/gpin.sh

Add the following lines in /etc/rc.local for auto-start of the button-control script on boot:

# player control
/etc/init.d/player_control.sh > /dev/null &

Scripts gpin.sh and gpout.sh are used to set up pins and return values depending on button press (button pressed = 0 button released = 1).

Script player_control.sh is used to play/stop player and change songs.

Modules must be put by default in (can be changed in player_control.sh as wished) this path:


During start of player_control.sh, the playlist is created to select particular songs.

Step 8: Testing Part

Please put some mod,s3m,it,xm files in the directory /files/music

You can either reboot to test auto-start or run manually for testing purposes:


You should be able to use buttons next/previous to switch the songs.
Also you should be able to stop song and start again by start/stop buttons.

Troubleshooting tips:

If the bassplay itself can play modules, please check the functionality of GPIO wiring.

You can test state of pins by  /usr/bin/gpin.sh

This scripts returns value of pin defined by the parameter.
You can press particular button ant test whether 1 changes in 0 and vice versa.

Instructables Design Competition

Participated in the
Instructables Design Competition

A/V Contest

Participated in the
A/V Contest

Pocket Sized Contest

Participated in the
Pocket Sized Contest

Be the First to Share


    • Make It Modular: Student Design Challenge

      Make It Modular: Student Design Challenge
    • Trash to Treasure Contest

      Trash to Treasure Contest
    • Science Fair Challenge

      Science Fair Challenge



    Reply 7 years ago on Introduction

    It's nice to see that my project has been inspirative.

    Can OMXplayer play MOD,S3M,IT,XM too? I cannot find this infromation.

    It's good that it runs as service, too.

    Do you plan to publish the final onstruction when it's done?


    Reply 7 years ago on Introduction

    I don't have .mod files, test yourself with bshplyr-no-gpio my new smaller script (it seems I don't need gpio fo myself, just happy with automated play)

    To play .mod you can also install timidity++ and change playerbin to /usr/bin/timidity++

    If I have more time or someone else does we can make conditionals to change playerbin according to filetype (github allows changes, remembering history).

    My final construction is just a Raspberry Pi in a cardboard case, adapted for battery pack according to


    with headphones and no buttons as GPIO's don't work for me for some unknown reason (they are always "0" ).


    9 years ago on Introduction

    Good Job! :)
    Went to my Blog post:


    9 years ago on Introduction

    Could you add some information in the initial step explaining what MOD is and why a portable player is desireable?


    Reply 9 years ago on Introduction

    Thank you for sharing your point of view.
    I was driven by the logic that MOD enthusiast wouldn't need an explanation and people not knowing what MOD is wouldn't need MOD player.
    I'll add a brief description with links to further resources.
    Thanks again.