This is my guide for generating playlists for your local music library using ListenBrainz and the troi recommendation engine. troi is still being developed and the official documentation isn't great so I figured documenting my process might help others who are interested. I've tried this both with local folders on my Debian server and with my Navidrome library from my Macbook so I will do my best to explain both.

There are a few requirements

1. Your music must be tagged with MusicBrainz. I use beets for this but you can also use the MusicBrainz desktop client.
2. You need a ListenBrainz account. Data can be imported from Last.fm or Libre.fm if you have it.

Install troi

Install troi and nmslib with pip

pip install troi
pip install nmslib-metabrainz

If you're on a managed python install use pipx and add the virtual environment to your PATH (don't forget to reload)

pipx install troi
pipx inject troi nmslib-metabrainz
export PATH="$PATH":"$HOME/.local/bin"
source ~/.zshrc

Configure troi

Create a folder for your troi configuration files. I used ~/.config/troi. Create a file config.py in your configuration folder using the example format below. Edit DATABASE_FILE and MUSIC_DIRECTORIES to match your setup.

If you're using a Subsonic library (like Navidrome) you can fill in SUBSONIC_HOST with your instance url, SUBSONIC_USER and SUBSONIC_PASSWORD with your login and SUBSONIC_PORT with 443 (this is the only port that I could get to work with my docker setup)

# Where to find the database file
# If path is passed with -d flag, this list is ignored.
DATABASE_FILE = "/users/sillyhatsonly/.config/troi/troi-db.db"

# To connect to a Subsonic API
SUBSONIC_HOST = "https://music.myserver.dev"  # include http:// or https://
SUBSONIC_USER = "admin"
SUBSONIC_PASSWORD = "thisisnotmypassword"
SUBSONIC_PORT = 443

# List of music directories to scan by default
# If paths are passed to scan command, this list is ignored.
# Invalid directories are skipped.
MUSIC_DIRECTORIES = [
    'My/Music/Directory 1',
    'My/Music/Directory 2',
]

Create your music database

Now create the database, scan the local directories specified in config.py and pull ListenBrainz tag/popularity metadata for all files. If you're using a Subsonic library run troi db subsonic instead of troi db scan

# create database
troi db create
# scan music directories
troi db scan
# pull music metadata
troi db metadata

Generate playlists

Generate playlists for your local library using ListenBrainz Radio Local. Specify a mode which sets how closely the resulting playlist will meet the prompt (easy/medium/hard from closest to furthest) and an entity reference either artist or tag. More details in the docs: LB Prompt Radio Reference

# tracks by Thou and similar artists
troi lb-radio easy 'artist:(thou)' -m <playlist-name>.m3u

# tracks tagged 'jazz' and tracks tagged 'hip-hop'
troi lb-radio medium 'tag:(jazz)::or tag:(hip-hop)'

# tracks tagged both 'indie rock' and 'experimental'
troi lb-radio medium 'tag:(indie rock, experimental)'

Another option is to generate weekly recommendations playlists for your ListenBrainz account

# -m flag saves to the specified m3u playlist
troi weekly-jams <username> -m <playlist-name>.m3u

# -u flag uploads the playlist via Subsonic API
troi weekly-jams <username> -u

Automate weekly playlists

You can automate weekly playlists with a script. I wrote a script that scans my music directory, removes missing files, generates a playlist, and saves it locally as an m3u

#!/bin/sh

# scan music directory and pull metadata using the database in our troi config folder
troi db scan 'My/Music/Directory 1' -q -d '/users/sillyhatsonly/.config/troi/troi-db.db'
troi db metadata 'My/Music/Directory 1' -q -d '/users/sillyhatsonly/.config/troi/troi-db.db'
# clean up the database and remove any missing files
troi db cleanup --remove -q -d '/users/sillyhatsonly/.config/troi/troi-db.db'
# generate weekly playlist and save locally to m3u
troi weekly-jams <username> -d '/users/sillyhatsonly/.config/troi/troi-db.db' -y -q -m /users/sillyhatsonly/music/playlists/weekly-$(date +%Y%m%d).m3u

Then set it up to run weekly as a cron job.

That's all I've done so far. Hopefully this makes sense. I welcome comments or questions. If anyone else has been using troi with their local music libraries I'd love to hear about your experience. Playlist generation was the one feature I really missed when I stopped using streaming platforms so I'm excited about this tool!