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 files when anlysed.
* `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` 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.



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.

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 `--tags` 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 SQLite 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.



Credits
=======

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