{"id":25039539,"url":"https://github.com/kkestell/djinn","last_synced_at":"2026-03-01T12:02:18.863Z","repository":{"id":218215239,"uuid":"745890697","full_name":"kkestell/djinn","owner":"kkestell","description":"Download music from Soulseek using metadata from MusicBrainz, Last.fm, and Spotify","archived":false,"fork":false,"pushed_at":"2025-05-17T01:59:38.000Z","size":3224,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-17T02:44:48.230Z","etag":null,"topics":["cli","downloader","music","musicbrainz","soulseek"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kkestell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-20T13:12:11.000Z","updated_at":"2025-05-17T01:59:42.000Z","dependencies_parsed_at":"2024-01-20T14:27:18.995Z","dependency_job_id":"d36d47fb-5469-4b86-9fd1-1fcf406ad373","html_url":"https://github.com/kkestell/djinn","commit_stats":null,"previous_names":["kkestell/djinn"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kkestell/djinn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkestell%2Fdjinn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkestell%2Fdjinn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkestell%2Fdjinn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkestell%2Fdjinn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kkestell","download_url":"https://codeload.github.com/kkestell/djinn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kkestell%2Fdjinn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T11:43:06.159Z","status":"ssl_error","status_checked_at":"2026-03-01T11:43:03.887Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","downloader","music","musicbrainz","soulseek"],"created_at":"2025-02-06T02:52:23.877Z","updated_at":"2026-03-01T12:02:18.858Z","avatar_url":"https://github.com/kkestell.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Djinn\n\nMusic library manager and Soulseek client using metadata from MusicBrainz, Last.fm, and Spotify.\n\n## Downloading Music with `djinn download`\n\n```sh\n$ djinn download --help\nDescription:\n    Download one or more releases\n\nUsage:\n    djinn download [options]\n\nOptions:\n    --release-id \u003crelease-id\u003e        Release ID\n    --release-title \u003crelease-title\u003e  Release title\n    --artist-id \u003cartist-id\u003e          Artist ID\n    --artist-name \u003cartist-name\u003e      Artist name\n    --replace                        Replace existing album(s)\n    --file-types \u003cfile-types\u003e        File types to download [default: .flac|.mp3]\n    --verbose                        Verbose output\n    --no-progress                    Disable realtime download progress\n    --year \u003cyear\u003e                    Release year\n    --strip-existing-metadata        Strip existing metadata from downloaded files [default: True]\n    -?, -h, --help                   Show help and usage information\n```\n\n### Downloading a Single Release\n\nTo download a specific release from MusicBrainz, use the `download` command with the `--release-id` option.\n\n```sh\n$ djinn download --release-id \"c812852b-4e5c-441e-bdd3-62ec45a6c215\"\n```\n\nOr the `--release-title` option.\n\n```sh\n$ djinn download --release-title \"Wrong Way Up\"\n```\n\n### Downloading an Artist's Discography\n\nTo download the complete discography of an artist use the `download` command with the `--artist-id` option.\n\n```sh\n$ djinn download --artist-id \"ff95eb47-41c4-4f7f-a104-cdc30f02e872\"\n```\n\nOr the `--artist-name` option.\n\n```sh\n$ djinn download --artist-name \"Brian Eno\"\n```\n\n## Display Library Statistics with `djinn stats`\n\nYou can view statistics about your music library by running:\n\n```sh\n$ djinn stats\nArtists: 427, Albums: 2013, Tracks: 22761\n```\n\n## Check Your Library for Issues with `djinn check`\n\nChecks that:\n\n* All album directories contain a `.metadata.json` file.\n* Album directories are named correctly based on the configured format\n* Track files are named correctly based on the configured format\n* All tracks referenced in the metadata file exist as audio files\n\n## Download Missing Cover Art with `djinn covers`\n\n```sh\n$ djinn covers\nDownloaded cover art for Velvet Teen, The - Elysium\nDownloaded cover art for Yo-Yo Ma - Japanese Melodies\n```\n\n## Replace MP3 Files with FLAC Files with `djinn upgrade`\n\n```sh\n$ djinn upgrade\n...\n```\n\n## Configuration\n\nDjinn loads its configuration from `DJINN_CONFIG` or, if that isn't set, from `~/.config/djinn/config.json`.\n\n### Music Library Organization\n\nDjinn assumes that your music library follows a simple Artist/Album/Track structure.\n\nYou must set the `ArtistFormat`, `AlbumFormat`, and `TrackFormat` strings in your configuration file to correspond with the way you organize your music.\n\nGiven this configuration:\n\n```\n\"ArtistFormat\": \"%S\",\n\"AlbumFormat\": \"%Y %T\",\n\"TrackFormat\": \"%n %t\"\n```\n\nDjinn would expect your music to be organized as:\n\n`Eno, Brian; Cale, John`/`1990 Wrong Way Up`/`01 Lay My Love.flac`\n\n### Format Tokens\n\nThe configuration includes format tokens that define how artist, album, and track information should be displayed. The available tokens are as follows:\n\n#### Artist Format Tokens\n\n| Token | Description           | Example                |\n|-------|-----------------------|------------------------|\n| `%A`  | Artist Name(s)        | Brian Eno, John Cale   |\n| `%S`  | Artist Sort Name(s)   | Eno, Brian; Cale, John |\n| `%%`  | Literal '%' character | %                      |\n\n#### Album Format Tokens\n\nAll artist tokens, plus:\n\n| Token | Description | Example      |\n|-------|-------------|--------------|\n| `%T`  | Album Title | Wrong Way Up |\n| `%Y`  | Album Year  | 1990         |\n\n#### Track Format Tokens\n\nAll artist and album tokens, plus:\n\n| Token | Description                            | Example     |\n|-------|----------------------------------------|-------------|\n| `%t`  | Track Title                            | Lay My Love |\n| `%n`  | Track Number (formatted as two digits) | 01          |\n| `%N`  | Total number of tracks in the album    | 10          |\n\n### Configuration File Example\n\nHere is an example of what the configuration file might look like:\n\n```json\n{\n    \"LibraryPath\": \"/home/kyle/Music\",\n    \"FfmpegPath\": \"/usr/bin/ffmpeg\",\n    \"FfprobePath\": \"/usr/bin/ffprobe\",\n    \"LastFmApiKey\": \"XXX\",\n    \"LastFmApiSecret\": \"XXX\",\n    \"SpotifyClientId\": \"XXX\",\n    \"SpotifyClientSecret\": \"XXX\",\n    \"SoulseekUsername\": \"XXX\",\n    \"SoulseekPassword\": \"XXX\",\n    \"ArtistFormat\": \"%S\",\n    \"AlbumFormat\": \"%Y %T\",\n    \"TrackFormat\": \"%n %t\"\n}\n```\n\n## Viewing Configuration with `djinn config`\n\nYou can view the path of the loaded config file and the parsed values by running:\n\n```sh\n$ djinn config\nConfiguration loaded from /home/kyle/.config/music/music.json\nLibrary path:       /home/kyle/Music\nFfmpeg path:        /usr/bin/ffmpeg\nFfprobe path:       /usr/bin/ffprobe\nLast.fm API key:    XXX\nLast.fm API secret: XXX\nSpotify client ID:  XXX\nSpotify secret:     XXX\nSoulseek username:  XXX\nSoulseek password:  XXX\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkestell%2Fdjinn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkkestell%2Fdjinn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkkestell%2Fdjinn/lists"}