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 and and 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

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/ from in:


Unzip source code:

tar -zxvf bassplay-0.1.tar.gz

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

mkdir bassplay-0.1/bass
cp bassplay-0.1/bass/
cp bassplay-0.1/bass/
unzip bassplay-0.1/bass/
unzip bassplay-0.1/bass/

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 from project's intro page.

Upload file to the raspberry and unpack by command:


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

chmod 777 /etc/init.d/
chmod 777 /usr/bin/
chmod 777 /usr/bin/

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

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

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

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

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


During start of, 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/

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

Pocket Sized Contest

Participated in the
Pocket Sized Contest

A/V Contest

Participated in the
A/V Contest