80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
# drift
|
||
|
||
Discovers similar artists via Last.fm and builds playlists from your local music library. Point it at a directory, pick a seed artist, and get a playlist of tracks weighted by artist similarity and popularity.
|
||
|
||
## Metadata requirements
|
||
|
||
Your music files need **MusicBrainz artist IDs** in their tags (`MUSICBRAINZ_ARTISTID`). Without these, tracks are skipped during indexing. Track titles help with popularity scoring — drift matches them against Last.fm's top tracks to bias toward well-known songs.
|
||
|
||
Most taggers (Picard, beets, etc.) can write MusicBrainz IDs automatically.
|
||
|
||
## Setup
|
||
|
||
You need a Last.fm API key. Create one at https://www.last.fm/api/account/create, then set it:
|
||
|
||
```
|
||
echo 'LASTFM_API_KEY=your_key_here' > .env
|
||
```
|
||
|
||
Or export it directly — drift loads `.env` automatically via dotenvy.
|
||
|
||
## Usage
|
||
|
||
### Index your library
|
||
|
||
```
|
||
drift index /path/to/music
|
||
```
|
||
|
||
Scans for tagged files, fetches similar artists and top tracks from Last.fm, and stores everything in a local SQLite database (`~/.local/share/drift/drift.db`).
|
||
|
||
Stale tracks (files previously indexed but no longer on disk) are automatically removed.
|
||
|
||
Flags:
|
||
- `-v` — print new artists indexed + summary
|
||
- `-vv` — also print each track added/removed
|
||
- `-vvv` — also print skipped artists
|
||
- `-f` — re-index artists that were already indexed
|
||
|
||
### Build a playlist
|
||
|
||
```
|
||
drift build
|
||
```
|
||
|
||
Opens an interactive picker to choose a seed artist. Or pass one or more artist names directly:
|
||
|
||
```
|
||
drift build "Radiohead"
|
||
drift build "Radiohead" "Portishead"
|
||
```
|
||
|
||
With multiple seeds, artists similar to several seeds rank higher — the playlist blends their neighborhoods naturally.
|
||
|
||
Flags:
|
||
- `-n 30` — number of tracks (default 20)
|
||
- `-p 8` — popularity bias, 0–10 (default 5, higher = prefer popular tracks)
|
||
- `-s` — interleave artists evenly instead of score order
|
||
- `-r` — fully randomize track order
|
||
- `-v` — print track scores to stderr
|
||
|
||
### Output
|
||
|
||
By default, drift prints file paths to stdout — pipe it wherever you want.
|
||
|
||
#### MPD
|
||
|
||
```
|
||
drift build -m
|
||
```
|
||
|
||
Queues tracks directly in MPD. Requires `MPD_HOST` and `MPD_MUSIC_DIR` environment variables.
|
||
|
||
#### Airsonic
|
||
|
||
```
|
||
drift build -a
|
||
```
|
||
|
||
Creates a playlist in Airsonic/Navidrome. Requires `AIRSONIC_URL`, `AIRSONIC_USER`, and `AIRSONIC_PASS` environment variables.
|