README.md
1# Moodbar
2
3Moodbar is a music visualization method that assigns colors to different parts of a track and presents them as a timeline.
4Applied to a music player, the main goal is to help the user navigate within a particular track.
5For example, if the user wants to skip to the first chorus of a song, a good moodbar implementation should be able to provide a hint of where this might occur in the timeline.
6
7
8
9The particular moodbar implementation in this repository is based on the Bandwise Spectral Magnitude method presented in [*On Techniques for Content-Based Visual Annotation to Aid Intra-Track Music Navigation*](https://ismir2005.ismir.net/proceedings/1023.pdf) (Gavin Wood & Simon O'Keefe, 2005).
10It divides the track into small chunks and assigns a color to each chunk: the red channel represents audio levels in the low frequencies, green for mid frequencies, and blue for high frequencies.
11
12The code is mostly taken from [Clementine](https://www.clementine-player.org/), with the addition of a command-line interface that is a drop-in alternative to [the original Moodbar program](https://userbase.kde.org/Amarok/Manual/Various/Moodbar).
13Clementine's moodbar implementation used to be based on the original project's, but they have since diverged greatly.
14Both implement the same idea and the outputs should be roughly similar.
15
16Files in the `gst` and `src` directories are directly taken from Clementine's repository with slight modifications to remove some extra dependencies.
17The initial commit is taken from Clementine revision 3886f3d1e4b29d028c1bacf474bc40d1c45c2ea9 (2014-12-22), last sync is at revision 55edcf5321051e44281f067a7e3ee44871982c12 (2019-03-11).
18
19
20## Requirements
21
22* FFTW 3
23* GStreamer 1
24 * GStreamer Base Plugins
25
26For building:
27
28* Development files for the above. A "Native dependency ... not found" error means you missed something.
29* C++ compiler
30* Meson. If your OS doesn't have a package for this, you can install it through pip (requires Python 3).
31* pkgconf or pkg-config
32* Ninja
33
34At runtime you may also need other GStreamer plugin packages to read your audio files.
35For example, to process MP3 files you may have to install GStreamer Ugly Plugins.
36
37
38## Building & installing
39
40```sh
41meson --buildtype=release build/
42cd build/
43ninja
44sudo ninja install
45```
46
47You can add `-Db_lto=true` to the `meson` call to produce slightly more efficient code.
48
49
50### For packagers
51
52Building with custom flags and prefix, and staging to destdir:
53
54```sh
55env CXXFLAGS=... LDFLAGS=... meson --buildtype=plain --prefix=... builddir
56ninja -C builddir
57env DESTDIR=... ninja -C builddir install
58```
59
60See the [Meson documentation](http://mesonbuild.com/Quick-guide.html#using-meson-as-a-distro-packager) for more info.
61
62
63## Usage
64
65```sh
66moodbar -o OUTPUT INPUT
67```
68
69This creates an output file containing pixel values in `R1 G1 B1 R2 G2 B2 ...` format.
70
71
72## Testing
73
74You can run `meson test -v` inside the build directory to run some unit tests.
75The tests require the following:
76
77* Python 3
78* NumPy
79* `gst-launch-1.0`. If this is named differently in your system or is not in PATH, point the GST_LAUNCH environment variable to it.
80
81
82## Contributing
83
84When you contribute to a file in this project, you agree to release your contribution under the same license specified in the file's license header.
85If there is no license header in the file, or if it's a new file, you agree to release your contribution under the GNU General Public License version 3 or later (GPL-3.0+), or you may specify another license that is compatible with GPL-3.0+.
86
87Code in the `gst` and `src` directories must be kept as close as possible to their original versions in the Clementine repository.
88The only permitted changes are to remove additional dependencies, to fix build errors/warnings, and to fix serious (e.g. security) issues.
89
90Other C or C++ code must be formatted with clang-format using the default settings.
91
){kind=link}