Skip to content
Music player - endlessly plays your music
Python Objective-C HTML C C++ Objective-C++ Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
_gui fix too much threads of concurrent async queue jobs Oct 9, 2014
app qmake: Qt5 support Nov 16, 2014
core @ d124f8b core Oct 11, 2018
debugger qmake Feb 4, 2014
faulthandler comment typo Feb 22, 2014
guiQt more on Qt ListWidget Dec 11, 2014
mac qmake: Qt5 support Nov 16, 2014
mach_override @ e2ca3c3 add mach_override Feb 18, 2014
python-embedded @ 24fd018 python Feb 24, 2014
src more Python 3 and code style fixes Oct 11, 2018
tools common init, small fix May 22, 2016
.gitignore gitignore Nov 15, 2014
.gitmodules add mach_override Feb 18, 2014 qmake Feb 9, 2014 qmake: Qt5 support Nov 16, 2014
.qmake.conf qmake: Qt5 support Nov 16, 2014 compare to mpd Mar 9, 2013 more Jan 29, 2014
License.txt added license: 2-clause BSD, simplified bsd license Nov 14, 2012 qmake: Qt5 support Nov 16, 2014 others: Groove Basin (why didn't I added this earlier?) Feb 7, 2014 plans: hog mode / exclusive access Nov 14, 2013 readme. download link Apr 27, 2013 some tests with rpython. wip Jun 15, 2013 Update May 22, 2019
attribs.txt some thoughts on attribs Sep 30, 2012 cleanup_qmake: cleanup Qmake 5 stuff, and mocs Nov 15, 2014 Python style Oct 3, 2018
defs defs Nov 13, 2011
icon.icns icon Sep 2, 2012
icon.png icon Sep 2, 2012
icon.svg icon Sep 2, 2012 compare to mpd Mar 9, 2013
screenshot.png screenshot Nov 12, 2012
song-thumbnail.png what is a music player Nov 12, 2012 test_rpython Jan 30, 2014

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.


You can’t perform that action at this time.