Music player

First, if you wonder about what is supposed to be a music player or what makes a music player different from a simple media player, read this: What is a music player

Annoyed by all existing players because some subset of:

  • not open source
  • missing sound format (FLAC, Ogg, …)
  • bugs (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, …)
  • missing output possibility (RAOP, PulseAudio, …)
  • none or too limited intelligent automatic queue (iTunes calls this DJ mode, others call this PartyShuffle)
  • no library / database

Features of this player:

  • open source (simplified BSD license, see License.txt)
  • simple
  • support of most important sound formats
  • advanced intelligent automatic queue which is the main mode to play music
  • simple music database
  • ReplayGain / audio volume normalization
  • scrobbling
  • AcoustID fingerprint
  • Gapless playback
  • MPD backend

MusicPlayer screenshot

About the intelligent automatic queue, what I want (maybe some of these somewhat configurable):

  • continuously always add songs when queue becomes too empty
  • liked songs more often
  • context-based choices, e.g. related songs more likely
  • possibility to easily manually add songs to the list
  • easy way to restrict to a subset of songs (like a genre, a playlist, a filesystem directory, etc.)

About the database:

  • main function: search
  • should be fast and optional for playback, i.e. music can be played even when the database is currently not ready for some reason
  • should automatically be filled by a filesystem directory
  • import like-state from local players like iTunes and also online services like

TODO / possible additional missing features:

  • BPM determination and clever DJ-like fading
  • use tags given by (mostly more tags)
  • watch music directory for changes (e.g. new files added)
  • other GUI implementations

Comparison to other music players:


So far, there is a prebuild MacOSX app bundle in the download section which should just work. Otherwise, to get the source working, you need these requirements (e.g. install on MacOSX via Homebrew):

  • ffmpeg
  • portaudio
  • chromaprint

(Debian/Ubuntu: apt-get install python-dev libsnappy-dev libtool yasm libchromaprint-dev portaudio19-dev libboost-dev. FFmpeg in Debian/Ubuntu is too old (lacks libswresample), so either do add-apt-repository ppa:jon-severinsson/ffmpeg && apt-get update && apt-get install libavformat-dev libswresample-dev or install it from source. Chromaprint depends on FFmpeg, so if you have a custom FFmpeg install, you might also want to install that manually. ./configure && make && sudo make install should work for FFmpeg and PortAudio. You might also want to use --enable-shared for FFmpeg. cmake . && sudo make install for Chromaprint.)

Then call ./ to build the Python modules (it will build the Python modules and

To start the player, just call ./

The current GUI is Cocoa only. Additional Qt support is planned. The music player also works without any GUI.

You can also control the player via an interactive Python shell. You can get the shell directly by passing --shell to or you can use tools/ Via the shell, you can do just anything. By default, the shell exports already the two main objects state and queue. Here some useful actions:

  • import utils: common imports you might need for the other commands
  • state.curSong: returns the current song
  • state.player.playing = True: start playing. or start/stop via state.playPause()
  • state.nextSong(): skips to next song
  • state.queue.shuffle(): shuffles the queue
  • utils.formatTime(sum([s.get("duration", accuracy=0, fastOnly=True)[0] or 0 for s in queue.queue.list])): get the amount of time of all songs in the queue
  • import guiCocoa; reload(guiCocoa): reload Cocoa GUI. this might be useful if it crashed (which shouldn’t happen, though)

You can use dir to get a list of attributes of an object. E.g. dir(state) returns list of all state-attributes. This might be useful if you want to figure out what you can do. But it might be easier to just look at the source. And you can use tab-autocompletion, e.g. type state. and press tab.

Also, don’t hesitate to play around with the code. You might be interested in the automatic queue handling code.