Introduction ============ `bliss-analyser` is a command-line application to scan your music collection and upload its database of music analysis to LMS. The `Bliss Mixer` LMS plugin can then use this information to provide music mixes for LMS's `Don't Stop the Music` feature. **NOTE:** You must run this application from a terminal window (e.g. cmd.com or PowerShell for Windows), as there is no graphical user interface. Variants -------- `bliss-analyser` can be built to support using either the `ffmpeg` libraries (`libavcodec`, etc.), `symphonia` library, or invoking the `ffmpeg` command itself. If the package used ended with `-libav` then `bliss-analyser` has been built with the `ffmpeg` libraries. This allows faster decoding of files, but will require the exact `ffmpeg` library versions to be on your system. (These libraries are usually provided with the Windows build). If the package used ended with `-static` then `bliss-analyser` has been built with the `ffmpeg` libraries - but these have been statically linked. This allows faster decoding of files, and a more portable binary - however, this _may_ reduce the number of supported file formats. If the package used ended with `-symphonia` then `bliss-analyser` has been built with the `symphonia` libraries. This allows a more portable binary, but at a slightly slower decoding speed (than `libav`) and produces analysis results that are not the same as those produced by `ffmpeg`/`libav`. If the package used ended with `-ffmpeg`, then `bliss-analyser` requires you also have the `ffmpeg` application installed and in your `$PATH`. These builds are roughly 50% slower at analysis, but are more portable as they can use (alomost) any `ffmpeg` version. Quick guide =========== 1. Install the `Bliss Mixer` LMS plugin. 2. Install `ffmpeg` if using Linux or macOS (and using `-libav` or `-ffmpeg` package (see `Varaints` (above))). 3. Edit the supplied `config.ini` in the current folder to set appropriate values for `music` and `lms` - e.g.: ``` [Bliss] music=/home/user/Music lms=127.0.0.1 ``` 4. Analyse your tracks: ``` ./bliss-analyser analyse ``` 5. Upload analysis database to LMS: ``` ./bliss-analyser upload ``` 6. Set LMS to use `Bliss` in `Don't Stop the Music` 7. Play some music! Installation ============ For Windows no extra installation steps are required, as all dependencies are bundled within its ZIP file. However, if using a `-libav` or `-ffmpeg` package (see `Varaints` (above)), both the Linux and macOS versions require that `ffmpeg` be installed - if using a `-static` or `-symphinia` package, then no additional dependencies are used. Linux ----- Debian based systems (e.g. Ubuntu): ``` sudo apt install ffmpeg ``` RedHat based systems (e.g. Fedora): ``` sudo yum install ffmpeg ``` macOS ----- First install `HomeBrew` High Sierra, Sierra, El Capitan, or earlier: ``` /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Otherwise: ``` /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` Then install `ffmpeg`: ``` brew install ffmpeg@5 brew link ffmpeg@5 ``` Configuration ============= `bliss-analyser` can (optionally) read its configuration from an INI-style file. By default `bliss-analyser` looks for a file named `config.ini` in its current folder, however the exact name and location can be specified as a command-line parameter. This file has the following syntax: ``` [Bliss] music=/home/user/Music db=bliss.db lms=127.0.0.1 ignore=ignore.txt tags=true ``` The following items are supported: * `music` specifies the location of your music collection - e.g. `c:\Users\user\Music` for windows. This default to `Music` within the user's home folder. Up to 4 other music folders may be specified via `music_1`, `music_2`, `music_3`, and `music_4` * `db` specifies the name and location of the database file used to store the analysis results. This will default to `bliss.db` in the current folder. * `lms` specifies the hostname, or IP address, of your LMS server. This is used when uploading the database file to LMS. This defaults to `127.0.0.1` If your LMS is password protected then use `user:pass@server` - e.g. `lms=pi:abc123@127.0.0.1` * `json` specifies the JSONRPC port number of your LMS server. This will default to 9000. * `ignore` specifies the name and location of a file containing items to ignore in mixes. See the `Ignore` section later on for more details. * `tags` specifies whether analysis results should be written to, and re-read from, files. Set to `true` or `false`. If enabled, then results are stored in a `COMMENT` tag that starts with `BLISS_ANALYSIS` * `preserve` specifies whether file modification time should be preserved when writing tags. Set to `true` or `false`. Command-line parameters ======================= `bliss-analyser` accepts the following optional parameters: * `-c` / `--config` Location of the INI config file detailed above. * `-m` / `--music` Location of your music collection, * `-d` / `--db` Name and location of the database file. * `-l` / `--logging` Logging level; `trace`, `debug`, `info`, `warn`, `error`. Default is `info`. * `-k` / `--keep-old` When analysing tracks, `bliss-analyser` will remove any tracks specified in its database that are no-longer on the file-system. This parameter is used to prevent this. * `-r` / `--dry-run` If this is supplied when analysing tracks, then no actual analysis will be performed, instead the logging will inform you how many new tracks are to be analysed and how many old tracks are left in the database. * `-i` / `--ignore` Name and location of the file containing items to ignore. * `-L` / `--lms` Hostname, or IP address, of your LMS server. * `-J` / `--json` JSONRPC port number of your LMS server. * `-n` / `--numtracks` Specify maximum number of tracks to analyse. * `-T` / `--tags` Write analysis results to file tags, and read from file tags. * `-p' / '--preserve` Attempt to preserve file modification time when writing tags. Equivalent items specified in the INI config file (detailed above) will override any specified on the commandline. `bliss-analyser` requires one extra parameter, which is used to determine the required task. This takes the following values: * `analyse` Performs analysis of tracks. * `upload` Uploads the database to LMS. * `stopmixer` Asks LMS plugin to stop it instance of `bliss-mixer` * `tags` Re-reads tags from your music collection, and updates the database for any changes. * `ignore` Reads the `ignore` file and updates the database to flag tracks as to be ignored for mixes. * `export` Exports tags from DB and stores within the audio files. Analysing tracks ================ Before you can create any mixes, your tracks need to be analysed. Assuming `config.ini` is in the current folder and contains valid entries, this is accomplished as follows: (Linux / macOS) ``` ./bliss-analyser analyse ``` (Windows) ``` .\bliss-analyser.exe analyse ``` This will first iterate all sub-folders of your music collection to build a list of filenames to analyse. New tracks that are not currently in the database are then analysed, and a progress bar showing the current percentage and time used is shown. As a rough guide, a 2015-era i7 8-core laptop with SSD analyses around 14000 tracks/hour. CUE files --------- If the analyser encounters an audio file with a matching CUE file (e.g. `album.flac` and `album.cue` in same folder) then it will attempt to analyse the individual tracks contained within. Exclude folders --------------- If you have audio books, or other audio items, within your music folder that you do not wish to have analysed, you can prevent `bliss-analyser` from analysing these be creating a file named `.notmusic` within the required folder. e.g. ``` /home/user/Music/Audiobooks/.notmusic ``` Uploading database ================== Once your tracks have been analysed, you need to `upload` your database to LMS so that its plugin can then use this information to create mixes. Assuming `config.ini` is in the current folder and contains valid entries, this is accomplished as follows: (Linux / macOS) ``` ./bliss-analyser upload ``` (Windows) ``` .\bliss-analyser.exe upload ``` If your LMS is running on the same machine as `bliss-analyser` and you have set the db path to be the location within your LMS's `Cache` folder which `bliss-mixer` will use to access `bliss.db`, then there is no need to 'upload' the database and all you need to do is stop any running `bliss-mixer`. This can be accomplished manually, or via the following: (Linux / macOS) ``` ./bliss-analyser stopmixer ``` (Windows) ``` .\bliss-analyser.exe stopmixer ``` *NOTE* You must already have the `Bliss Mixer` LMS plugin installed, or you will not be able to upload the database. Re-reading tags =============== If you have changed the tags in some files then the analysis database will have the old tags. To update this database with the changed tags, run `bliss-analyser` as follows (assuming `config.ini` is in the current folder and contains valid entries): (Linux / macOS) ``` ./bliss-analyser tags ``` (Windows) ``` .\bliss-analyser.exe tags ``` *NOTE* Tag re-reading is not implemented for CUE tracks. Therefore if you update your CUE files you will need to remove these from the database and re-analyse, or manually edit the meta-data in `bliss.db` using an SQLite GUI. Ignoring tracks in mixes ======================== Its possible that you have some tracks that you never want added to mixes, but as these are in your music collection they might be in your music queue and so could possibly be chosen as `seed` tracks for mixes. Therefore you'd want the analysis in the database, so that you can find mixable tracks for them, but would not want them be chosen as mixable tracks from other seeds. This is accomplished be setting the `Ignore` column to `1` for such tracks. To make this easier, `bliss-analyser` can read a text file containing items to ignore and will update the database as appropriate. This `ignore` file is a plain text file where each line contains either: 1. The unique path to be ignored. i.e. it could contain the complete path (relative to your music folder) of a track, an album name (to exclude a whole album), or an artist name (to exclude all tracks by the artist). 2. An SQL selector. If so, line must start "SQL:" followed by code that will be run after WHERE ``` ABBA/Gold - Greatest Hits/01 Dancing Queen.mp3 AC-DC/Power Up/ The Police/ SQL:Genre='Blues' SQL:Genre LIKE '%Dance%' SQL:Genre='Rock' SQL:Genre LIKE 'Rock;%' SQL:Genre LIKE '%;Rock' SQL:Genre LIKE '%;Rock;%' ``` This would exclude 'Dancing Queen' by ABBA, all of AC/DC's 'Power Up', all tracks by 'The Police', all tracks with 'Genre' set to 'Blues', and all tracks that have 'Dance' or 'Rock' as part of their 'Genre'. The SQL LIKE lines do sub-string matching. So '%Dance%' will match any genre string that contains 'Dance' - e.g. 'Classical Dance'. The 4 lines with 'Rock' show how you can explicitly look for an exact match. The 1st line means 'Rock' is the only genre, 2nd means 'Rock' is the first genre, 3rd means 'Rock' is the last genre, and 4th means 'Rock' is amongst other genres. Assuming `config.ini` is in the current folder and contains valid entries, this is accomplished as follows: (Linux / macOS) ``` ./bliss-analyser ignore ``` (Windows) ``` .\bliss-analyser.exe ignore ``` Exporting Analysis ================== If you have analysis results stored within the SQLite DB, and not within the files themselves, then you can use the `export` action to copy these analysis results from the DB and into the files. (Linux / macOS) ``` ./bliss-analyser export ``` (Windows) ``` .\bliss-analyser.exe export ``` *NOTE* Exporting of analysis results is not implemented for CUE tracks. Credits ======= The actual music analysis is performed by the `bliss-rs` library. See https://lelele.io/bliss.html for more information on this.