README.md
1libgroove
2=========
3
4This library provides decoding and encoding of audio on a playlist. It is
5intended to be used as a backend for music player applications. That said, it is
6also generic enough to be used as a backend for any streaming audio processing
7utility.
8
9Features
10--------
11
12* Uses [libav](http://www.libav.org/) for robust decoding and encoding. A list
13 of supported file formats and codecs [is
14 available](http://www.libav.org/general.html#Supported-File-Formats-and-Codecs).
15* Add and remove entries on a playlist for gapless playback.
16* Supports idempotent pause, play, and seek.
17* Per-playlist-item gain adjustment so you can implement loudness compensation
18 without audio glitches.
19* Read and write metadata tags.
20* Choose between smooth mode and exact mode during playback.
21 * **smooth mode** - open the audio device once and resample everything to
22 fit that sample rate and format.
23 * **exact mode** - open and close the audio device as necessary in effort
24 to open the audio device with parameters matching the incoming audio data.
25* Extensible sink-based interface. A sink provides resampling and keeps its
26 buffer full. Types of sinks:
27 * **raw sink** - Provides reference-counted raw audio buffers you can do
28 whatever you like with. For example a real-time audio visualization. All
29 other sink types are built on top of this one.
30 * **player sink** - Sends frames to a sound device.
31 * **encoder sink** - Provides encoded audio buffers. For example, you could
32 use this to create an HTTP audio stream.
33 * **loudness scanner sink** - Uses the [EBU R
34 128](http://tech.ebu.ch/loudness) standard to detect loudness. The values it
35 produces are compatible with the
36 [ReplayGain](http://wiki.hydrogenaudio.org/index.php?title=ReplayGain_1.0_specification)
37 specification.
38 * **fingerprint sink** - Uses [chromaprint](http://acoustid.org/chromaprint)
39 to generate unique song IDs that can be used with the acoustid service.
40* Thread-safe.
41* Example programs included:
42 * `playlist` - Play a series of songs with gapless playback.
43 * `metadata` - Read or update song metadata.
44 * `replaygain` - Report the suggested replaygain for a set of files.
45 * `transcode` - Transcode one or more files into one output file.
46 * `fingerprint` - Generate acoustid fingerprints for one or more files.
47
48Dependencies
49------------
50
51You will need these to compile libgroove.
52
53* [cmake](http://www.cmake.org/)
54* [libav](http://libav.org)
55 * suggested flags: `--enable-shared --disable-static --enable-libmp3lame --enable-libvorbis --enable-gpl`
56* [libebur128](https://github.com/jiixyj/libebur128)
57 * make sure it is compiled with the speex dependency so that true peak
58 functions are available.
59* [libsdl2-dev](http://www.libsdl.org/)
60* [libchromaprint-dev](http://acoustid.org/chromaprint)
61
62Installation
63------------
64
65Installing from a package is recommended, but instructions for installing from
66source are also provided at the end of this list.
67
68### [Ubuntu PPA](https://launchpad.net/~andrewrk/+archive/libgroove)
69
70Note: as of Ubuntu 14.10 Utopic Unicorn, libgroove is included in the default
71repository index so you don't need a PPA.
72
73```sh
74sudo apt-add-repository ppa:andrewrk/libgroove
75sudo apt-get update
76sudo apt-get install libgroove-dev libgrooveplayer-dev libgrooveloudness-dev \
77 libgroovefingerprinter-dev
78```
79
80### [FreeBSD Port](http://www.freshports.org/audio/libgroove/)
81
82```sh
83pkg install audio/libgroove
84```
85
86### [Debian](http://packages.qa.debian.org/libg/libgroove.html)
87
88libgroove ships with Debian Jessie.
89
90```sh
91sudo apt-get install libgroove-dev libgrooveplayer-dev \
92 libgrooveloudness-dev libgroovefingerprinter-dev
93```
94
95### [Arch Linux](https://aur.archlinux.org/packages/libgroove/)
96
97libgroove is available through the [AUR](https://aur.archlinux.org/).
98
99```sh
100wget https://aur.archlinux.org/packages/li/libgroove/libgroove.tar.gz
101tar xzf libgroove.tar.gz
102cd libgroove
103makepkg
104sudo pacman -U libgroove-*
105```
106
107Some notes:
108
109* libgroove depends upon several other packages. Dependencies available through
110 the official repositories can be installed with pacman (e.g. `pacman -S
111 --asdeps sdl2`), and dependencies available through the AUR can be installed
112 via the procedure shown above.
113* An [AUR helper](https://wiki.archlinux.org/index.php/AUR_helper) can ease the
114 process of installing packages from the AUR.
115* The [AUR User
116 Guidelines](https://wiki.archlinux.org/index.php/AUR_User_Guidelines) page on
117 the Arch Wiki contains gobs of useful information. Please see that page if you
118 have any further questions about using the AUR.
119
120### [Mac OS X Homebrew](http://brew.sh/)
121
122```sh
123brew install libgroove
124```
125
126### From Source
127
128```sh
129mkdir build && cd build && cmake ../
130# Verify that the configure output is to your liking.
131make
132sudo make install
133```
134
135Documentation
136-------------
137
138Check out the example programs in the example folder.
139
140Read header files for the relevant APIs:
141
142* groove/groove.h
143 * globals
144 * GrooveFile
145 * GroovePlaylist
146 * GrooveBuffer
147 * GrooveSink
148* groove/encoder.h
149 * GrooveEncoder
150* grooveplayer/player.h
151 * GroovePlayer
152* grooveloudness/loudness.h
153 * GrooveLoudnessDetector
154* groovefingerprinter/fingerprinter.h
155 * GrooveFingerprinter
156
157Join #libgroove on irc.freenode.org and ask questions.
158
159Projects Using libgroove
160------------------------
161
162Feel free to make a pull request adding yours to this list.
163
164* [waveform](https://github.com/andrewrk/waveform) generates PNG waveform
165 visualizations.
166* [node-groove](https://github.com/andrewrk/node-groove) provides
167 [Node.js](http://nodejs.org/) bindings to libgroove.
168* [Groove Basin](https://github.com/andrewrk/groovebasin) is a music player with
169 lazy multi-core replaygain scanning, a web interface inspired by Amarok 1.4,
170 http streaming, upload, download and a dynamic playlist mode.
171* [groove-rs](https://github.com/andrewrk/groove-rs) provides
172 [rust](http://rust-lang.org) bindings to libgroove.
173* [ruby-groove](https://github.com/johnmuhl/ruby-groove) provides Ruby FFI
174 bindings to libgroove.
175* [TrenchBowl](https://github.com/andrewrk/TrenchBowl) is a simple Qt GUI
176 on top of libgroove.
177