Djinn

Music library manager and Soulseek client using metadata from MusicBrainz, Last.fm, and Spotify.

Commands

Downloading Music

Downloading a Single Release

To download a specific release from MusicBrainz, use the download command with the --release-id option.

$ djinn download --release-id "c812852b-4e5c-441e-bdd3-62ec45a6c215"

Or the --release-title option.

$ djinn download --release-title "Wrong Way Up"

Downloading an Artist’s Discography

To download the complete discography of an artist use the download command with the --artist-id option.

$ djinn download --artist-id "ff95eb47-41c4-4f7f-a104-cdc30f02e872"

Or the --artist-name option.

$ djinn download --artist-name "Brian Eno"

Display Library Statistics

You can view statistics about your music library by running:

$ djinn stats

Check Your Library for Issues

Check that:

All album directories contain a .metadata.json file.
Album directories are named correctly based on the configured format
Track files are named correctly based on the configured format
All tracks referenced in the metadata file exist as audio files

$ djinn check

Automatically fix issues:

$ djinn check --fix

Download Missing Cover Art

$ djinn covers

Replace MP3 Files with FLAC Files

$ djinn upgrade

Configuration

Djinn loads its configuration from DJINN_CONFIG or, if that isn’t set, from ~/.config/djinn/config.json.

Music Library Organization

Djinn assumes that your music library follows a simple Artist/Album/Track structure.

You must set the ArtistFormat, AlbumFormat, and TrackFormat strings in your configuration file to correspond with the way you organize your music.

Given this configuration:

{
  "ArtistFormat": "%S",
  "AlbumFormat": "%Y %T",
  "TrackFormat": "%n %t"
}

Djinn would expect your music to be organized as:

Eno, Brian; Cale, John/1990 Wrong Way Up/01 Lay My Love.flac

Format Tokens

The configuration includes format tokens that define how artist, album, and track information should be displayed. The available tokens are as follows:

Artist Format Tokens

Token	Description	Example
`%A`	Artist Name(s)	Brian Eno, John Cale
`%S`	Artist Sort Name(s)	Eno, Brian; Cale, John
`%%`	Literal ‘%’ character	%

Album Format Tokens

All artist tokens, plus:

Token	Description	Example
`%T`	Album Title	Wrong Way Up
`%Y`	Album Year	1990

Track Format Tokens

All artist and album tokens, plus:

Token	Description	Example
`%t`	Track Title	Lay My Love
`%n`	Track Number (formatted as two digits)	01
`%N`	Total number of tracks in the album	10

Cover Display Style

Djinn will display album art in your terminal emulator. Available options are None (the default), Ansi, or Sixel.

Strip Existing Metadata

Whether to strip all existing metadata in downloaded files before setting metadata from MusicBrainz.

Configuration File Example

Here is an example of what the configuration file might look like:

{
  "LibraryPath": "/home/kyle/Music",
  "FfmpegPath": "/usr/bin/ffmpeg",
  "FfprobePath": "/usr/bin/ffprobe",
  "LastFmApiKey": "XXX",
  "LastFmApiSecret": "XXX",
  "SpotifyClientId": "XXX",
  "SpotifyClientSecret": "XXX",
  "SoulseekUsername": "XXX",
  "SoulseekPassword": "XXX",
  "ArtistFormat": "%S",
  "AlbumFormat": "%Y %T",
  "TrackFormat": "%n %t",
  "CoverDisplayStyle": "Ansi",
  "StripExistingMetadata": true
}

Viewing Configuration

You can view the path of the loaded config file and the parsed values by running:

$ djinn config
Configuration loaded from /home/kyle/.config/djinn/config.json
Library path:            /home/kyle/Music
Ffmpeg path:             /usr/bin/ffmpeg
Ffprobe path:            /usr/bin/ffprobe
Last.fm API key:         XXX
Last.fm API secret:      XXX
Spotify client ID:       XXX
Spotify secret:          XXX
Soulseek username:       XXX
Soulseek password:       XXX
Cover display style:     Ansi
Strip existing metadata: True

Source

The source for Djinn is available on GitHub.