View on GitHub


A command-line tool for generating XSPF playlists from audio file metadata.

download .ZIPdownload .TGZ


Spfy is a command-line tool for generating XSPF playlists from metadata stored in several popular audio formats and is developed entirely in Ruby. It takes one or more local directory paths as input, extracts metadata tags from any audio files that it encounters, and generates a valid XSPF playlist.


A working Ruby installation (version 1.9 or greater) is required for Spfy to work, but this is outside the scope of this guide. For more information refer to the official installation procedure.

TagLib is also required. Follow the steps below (taken from the taglib-ruby installation guide) to install the necessary files for your respective system type:

System: Command:
Debian/Ubuntu sudo apt-get install libtag1-dev
Fedora/RHEL sudo yum install taglib-devel
Brew brew install taglib
MacPorts sudo port install taglib


With the prerequisites above taken care of Spfy can be installed with the following command:

$ gem install spfy

Using Spfy

By default, Spfy will output a formatted XSPF playlist to the standard output stream that will include location, title, creator, album, and trackNum elements for each audio file where available.

The general syntax for Spfy is spfy [options] dir1 ... dirN, where dir1 ... dirN is one or more paths to directories containing audio files.

For example:

$ spfy ~/music

..will produce the following output (where ~/music contains one audio file with valid metadata):

<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="">
            <title>A Stitch In Time</title>
            <creator>The Smashing Pumpkins</creator>
            <album>Teargarden by Kaleidyscope</album>

Spfy supports multiple directory paths (e.g. spfy /dir1 /dir2) and traverses each directory recursively by default. Unsupported files and empty directories in a directory tree are silently ignored and will not impact Spfy's output.

Command-line arguments allow you to control which elements Spfy outputs:

-f, --no-location                Suppress file location output
-t, --no-title                   Suppress track title in output
-a, --no-artist                  Suppress artist name in output
-l, --no-album                   Suppress album name in output
-n, --no-tracknum                Suppress track number in output

For additional options use spfy --help.


Spfy is free software, and you are welcome to redistribute it under certain conditions. See the GNU General Public License for more details.


Spfy uses the following third party software components:

Comments or suggestions?

Email me at with bug reports, feature requests or general comments and follow @marcransome for updates.