Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status

This is mostly just a Rustified version of so a lot of this is the same info

Maintainer's Note: Even though there have been no new commits on this repo in over a year, it is not dead, it just isn't broken yet. I actively maintain this repo, and use this software daily. If you find any bugs, please open an issue.

Table of Contents:


ashuffle is a C re-implementation of my ashuffle python script, an application for automatically shuffling your mpd library in a similar way to a more standard music player's "shuffle library" feature.


ashuffle has two modes. The first one (and the simpler of the two) is to simply queue some number of songs randomly selected from your mpd library. To do this you simply run:

$ ashuffle --only 10   # ashuffle --only <number of songs to add>

which will add 10 random songs to your queue.

In the second (more interesting) mode, ashuffle will wait until the last song in the queue has finished playing, at which point it will add another song to the queue. In this creates a 'stream of music' where songs will be continuously played, at random, to infinity. Additionally, since ashuffle only adds one song at a time, and only adds that song once the last song in the playlist has finished playing, you still retain control over your queue. This way, you can add some song you want to hear to the queue, and the random songs will simply continue afterwards.

Additionally, ashuffle uses mpd's idle functionality so it won't drain cpu polling to check if the current song has advanced.

To use the second mode, run ashuffle without the --only argument.

$ ashuffle

running in a non-standard configuration

If you're running MPD on a non-standard port or on a different machine, ashuffle will respect the standard MPD_HOST and MPD_PORT environment variables to set the host and port mpd is listening on respectively.

Also following standard MPD tools, a password can be supplied in the MPD_HOST environment variable by putting an @ between the password and the hostname.

For example, one can run ashuffle as follows:

$ env MPD_HOST="<password>@<hostname>" MPD_PORT="<port>" ashuffle ...

Or without the password by just omitting the <password> and @ from the MPD_HOST variable.

shuffling from files and --nocheck

By supplying the -f option and a file containing a list of song URIs to shuffle, you can make ashuffle shuffle and arbitrary list of songs. For example, by passing -f - to ashuffle, you can have it shuffle over songs passed to it via standard in:

$ mpc search artist "Girl Talk" | ashuffle -f -

As explained in more detail below, if song URIs are passed to ashuffle using this mechanism, ashuffle will still try to apply exclusion rules to these songs. If the song URIs you want ashuffle to shuffle over do not exist in your MPD library (for example if you are trying to shuffle URIs with the file:// schema), ashuffle will exclude them by default. If you pass the --nocheck option to ashuffle, it will not apply the filtering rules, allowing you to shuffle over songs that are not in your library.

crossfade support and the --queue_buffer

By default, ashuffle will only enqueue another song once the current queue has ended. This gives the user a lot of control over what will be playing next. One unfortunate side-effect of this is that it breaks MPD's built-in crossfade support. If the next song is only added once the previous song has finished playing, MPD doesn't know how to crossfade between the two songs. As a tradeoff between queue control and cross-fade support, you can supply the --queue_buffer n flag. This flag will have ashuffle ensure that there are always n songs in the queue after the currently playing song. This way you still retain some queue control, while making sure that MPD can crossfade effectively.

help text

usage: ashuffle -h -n { ..opts.. } [-e PATTERN ...] [-o NUMBER] [-f FILENAME]

Optional Arguments:
   -e,--exclude   Specify things to remove from shuffle (think blacklist).
   -o,--only      Instead of continuously adding songs, just add 'NUMBER'
                  songs and then exit.
   -h,-?,--help   Display this help message.
   -f,--file      Use MPD URI's found in 'file' instead of using the entire MPD
                  library. You can supply `-` instead of a filename to retrive
                  URI's from standard in. This can be used to pipe song URI's
                  from another program into ashuffle.
   -n,--nocheck   When reading URIs from a file, don't check to ensure that
                  the URIs match the given exclude rules. This option is most
                  helpful when shuffling songs with -f, that aren't in the
                  MPD library.
   --queue_buffer Specify to keep a buffer of `n` songs queued after the
                  currently playing song. This is to support MPD features
                  like crossfade that don't work if there are no more
                  songs in the queue.
See included `` file for PATTERN syntax.


Patterns are a list of key-value pairs given to the --exclude flag. A pair is composed of a 'field' and a 'value'. A field is the name of an MPD tag (e.g. artist, title, album) to match on (case insensitive) and 'value' is a string to match against that field. So, if I wanted to exclude MGMT's album 'Congratulations' in the shuffle I could supply a command line like the following:

$ ashuffle --exclude artist MGMT album "Congratulations"

Since typing in an exact match for all songs could become quite cumbersome, the 'value' field will match on substrings, so you only have to specify part of the search string. For example, if we wanted to match Arctic Monkeys album 'Whatever People Say I Am, That's What I'm Not' we could shorten that to this:

$ ashuffle --exclude artist arctic album whatever

Multiple --exclude flags can be given, the AND result of all flags will be used to match a given song. For example, if we wanted to exclude songs by MGMT and songs by the Arctic Monkeys, we could write:

$ ashuffle --exclude artist MGMT --exclude artist arctic

Additionally, the -f flag can be used to shuffle over more complex matches. For example, if we wanted to listen to only songs by Girl Talk except the Secret Diary album, we could use mpc to generate a list of Girl Talk songs and then use a --exclude statement to filter out the Secret Diary album:

$ mpc search artist "Girl Talk" | ashuffle --exclude album "Secret Diary" --file -

shuffle algorithm

Currently ashuffle is using a fairly unique algorithm for shuffling songs. Most applications fall into two camps: true random shuffle, and 'random list' shuffle. With true random shuffle, no restrictions are placed on what songs can be selected for play. It's possible that a single song could be played two or even three times in a row because songs are just being draw out of a hat. With 'random list' shuffle, songs to be shuffled are organized into a list of songs behind the scenes. This list is then scrambled, and then played like a normal playlist. Using this method songs won't be played twice in a row, but the once the playlist has been played it will either loop (playing the same random set again), or be re-scrambled and played again, so it can still get repetitive. Also, since there's no chance that a song can be played again, it won't feel very random, especially when listening for a long time. I often start noticing song order once the random-list wraps around.

ashuffle's approach is an attempt at a happy medium between these two approaches. Essentially, it keeps two lists of songs, a 'pool' of the songs it's shuffling, and a 'window' which is a short, ordered, playlist of songs. When the program starts, ashuffle builds the window randomly by taking songs out of the pool, and adding them to the window. When a new random song is added to the MPD queue, the 'top' song of the window, is taken off, added to the queue, and then put back into the pool. Then another song is added to the window so that the next request can be fulfilled.


The only dependency is 'libmpdclient' which, you can probably install via your package manager. For example on debian based distributions:

sudo apt-get install libmpdclient-dev

or on OS X using brew:

brew install libmpdclient


Download the latest release, untar/unzip it and then cd into the directory and run:

cargo build

Then run

cargo install --path .

to install the binary.

Oh, and in the case you're wondering why it's called 'ashuffle' it's because it implements 'automatic shuffle' mode for mpd.