Skip to content


Switch branches/tags

Latest commit


Git stats


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


This library provides decoding and encoding of audio on a playlist. It is intended to be used as a backend for music player applications. That said, it is also generic enough to be used as a backend for any streaming audio processing utility.


  • Uses ffmpeg for robust decoding and encoding. See supported file formats and codecs.
  • Add and remove entries on a playlist for gapless playback.
  • Supports idempotent pause, play, and seek.
  • Per-playlist-item gain adjustment so you can implement loudness compensation without audio glitches.
  • Read and write metadata tags.
  • Choose between smooth mode and exact mode during playback.
    • smooth mode - open the audio device once and resample everything to fit that sample rate and format.
    • exact mode - open and close the audio device as necessary in effort to open the audio device with parameters matching the incoming audio data.
  • Extensible sink-based interface. A sink provides resampling and keeps its buffer full. Types of sinks:
    • raw sink - Provides reference-counted raw audio buffers you can do whatever you like with. For example a real-time audio visualization. All other sink types are built on top of this one.
    • player sink - Sends frames to a sound device.
    • encoder sink - Provides encoded audio buffers. For example, you could use this to create an HTTP audio stream.
    • loudness scanner sink - Uses the EBU R 128 standard to detect loudness. The values it produces are compatible with the ReplayGain specification.
    • fingerprint sink - Uses chromaprint to generate unique song IDs that can be used with the acoustid service.
    • waveform sink - Generates a visual representation of a song.
  • Example programs included:
    • playlist - Play a series of songs with gapless playback.
    • metadata - Read or update song metadata.
    • replaygain - Report the suggested replaygain for a set of files.
    • transcode - Transcode one or more files into one output file.
    • fingerprint - Generate acoustid fingerprints for one or more files.
    • metadata_checksum - Read or update song metadata. This program scans the audio of the file before the metadata change, changes the metadata in a temporary file, scans the audio of the temporary file to make sure it matches the original, and then atomically renames the temporary file over the original file.

Building From Source


  • cmake >= 2.8.5
  • ffmpeg >= 3.0
    • suggested flags: --enable-shared --disable-static --enable-libmp3lame --enable-libvorbis --enable-gpl
  • libebur128
    • make sure it is compiled with the speex dependency so that true peak functions are available.
  • libsoundio
  • libchromaprint-dev
mkdir build
cd build
cmake ..
sudo make install


API Reference

Join #libgroove on and ask questions.

To build the documentation:

make doc

Projects Using libgroove

Feel free to make a pull request adding yours to this list.

  • Groove Basin is a music player with lazy multi-core replaygain scanning, a web interface inspired by Amarok 1.4, http streaming, upload, download and a dynamic playlist mode.
  • waveform generates PNG waveform visualizations.
  • node-groove provides Node.js bindings to libgroove.
  • playa OS X Audio Player that thinks in albums.
  • groove-rs provides rust bindings to libgroove.
  • ruby-groove provides Ruby FFI bindings to libgroove.
  • TrenchBowl is a simple Qt GUI on top of libgroove.