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.


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.