bliss-analyser/UserGuide.md

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.

Quick guide

1. Install the Bliss Mixer LMS plugin.

2. 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

3. Analyse your tracks:

./bliss-analyser analyse

4. Upload analysis database to LMS:

./bliss-analyser upload

5. Set LMS to use Bliss in Don't Stop the Music

6. Play some music!

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
readtags=true
writetags=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.
• readtags specifies whether analysis results should be read from files whe analysing.
• writetags specifies whether analysis results should be written to files when analysed.
• 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.
• -R / --readtags When using the analyse task, read analysis results from a files a BLISS_ANALYSIS tag (it present) in files.
• -W / --writetags When using the analyse task, write analysis results to files within a BLISS_ANALYSIS tag.
• -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 command-line.

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 its 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 database and stores within the audio files.
• clearfail If analysis fails for a track then the track path and its modification time is stored in the database, so that running analysis again ignores these files. This action clears this information, so that an analysis run will attempt to analyse these 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.

If analysis fails for a track, then the track's path and timestamp are stored within the database so that subsquent analysis calls will skip these tracks.

Tags

When analysing tracks, the analyser will first check for a BLISS_ANALYSIS tag within the file, and if found this will be used instead of re-analysing the file.

If --writetags is passed, the analysis results will be stored within a BLISS_ANALYSIS tag in the file itself. Note, however, that only tracks that are not currently in the database will be analysed - therefore any such tracks would not have the BLISS_ANALYSIS tag updated. To export analysis results from the database to files themselves use the export task.

NOTE Use of the BLISS_ANALYSIS tag is not supported for CUE files.

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 database, and not within the files themselves, then you can use the export action to copy these analysis results from the database 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.

Clearing Failed Tracks

Any tracks that could not be analysed are stored in the database so that subsequent analysis runs ignore such files - unless the files themselves have been updated.

You can remove this list of failed tracks, from database, via the following command:

(Linux / macOS)

./bliss-analyser clearfail

(Windows)

.\bliss-analyser.exe clearfail

Credits

The actual music analysis is performed by the bliss-rs library. See https://lelele.io/bliss.html for more information on this.