DOCSEARCHbyAlgolia
Submit Docs

OrpheusDL Documentation

repository·master·Indexed 21 days ago

https://github.com/orfiteam/orpheusdl

A modular Python-based music archival tool for downloading music from various streaming services. It supports high-quality metadata preservation, customizable file formatting, and advanced configuration for codecs, cover art, and lyrics. Users can archive music via URLs, searches, or specific IDs using the orpheus.py script.

Tokens
1.8K
Snippets
8
Records
8
Agent score
27%

What's inside OrpheusDL

  1. Install OrpheusDL

    master

    OrpheusDL is a modular music archival tool written in Python. Follow these steps to set up a local instance:

    1. Prerequisites: Ensure you have Python 3.7+ installed (Python 3.9 is highly recommended).
    2. Clone the repository:
      git clone https://github.com/OrfiTeam/OrpheusDL.git && cd OrpheusDL
    3. Install dependencies:
      pip install -r requirements.txt
    4. Initialize settings: Run the following command to generate the initial settings file:
      python3 orpheus.py settings refresh
    5. Configure credentials: Open config/settings.json and enter your service credentials.
    git clone https://github.com/OrfiTeam/OrpheusDL.git && cd OrpheusDL
pip install -r requirements.txt
python3 orpheus.py settings refresh

  2. Use OrpheusDL to archive music

    master

    You can interact with OrpheusDL via the orpheus.py script using links, searches, or specific IDs.

    Archive via URL

    Provide a direct link to an album or track (e.g., Qobuz):

    python3 orpheus.py https://open.qobuz.com/album/c9wsrrjh49ftb

    Archive via Search

    Perform a search. Using luckysearch will automatically select the first result:

    python3 orpheus.py search qobuz track darkside alan walker

    Archive via ID

    If you have the specific ID for a track or album:

    python3 orpheus.py download qobuz track 52151405
    # Example: Archive a Qobuz album via URL
python3 orpheus.py https://open.qobuz.com/album/c9wsrrjh49ftb

# Example: Search for a track
python3 orpheus.py search qobuz track darkside alan walker

# Example: Download via ID
python3 orpheus.py download qobuz track 52151405

  3. Configure Global Lyrics Settings

    master

    Manage how lyrics are handled in config/settings.json.

    OptionDescription
    embed_lyricsEmbed unsynced lyrics inside every track.
    embed_synced_lyricsEmbed synced lyrics inside every track (requires embed_lyrics to be true). Required for Roon compatibility.
    save_synced_lyricsSaves synced lyrics into a .lrc file in the same directory as the track.
    {
    "embed_lyrics": true,
    "embed_synced_lyrics": false,
    "save_synced_lyrics": true
}

  4. Configure Global Formatting and Path Variables

    master

    Customize how files and directories are named using album_format, playlist_format, track_filename_format, and single_full_path_format in config/settings.json.

    Formatting Options

    • enable_zfill: (boolean) Enables zero padding for track_number, total_tracks, disc_number, and total_discs if they exceed 2 digits.
    • force_album_format: (boolean) Forces album_format for tracks instead of single_full_path_format and applies it to playlists.

    Available Variables

    For track_filename_format: {name}, {album}, {album_artist}, {album_id}, {track_number}, {total_tracks}, {disc_number}, {total_discs}, {release_date}, {release_year}, {artist_id}, {isrc}, {upc}, {explicit}, {copyright}, {codec}, {sample_rate}, {bit_depth}.

    For album_format: {name}, {id}, {artist}, {artist_id}, {release_year}, {upc}, {explicit}, {quality}, {artist_initials}.

    For playlist_format: {name}, {creator}, {tracks}, {release_year}, {explicit}, {creator_id}.

    Special Variable Modifiers

    • {quality}: Adds [Dolby Atmos], [96kHz 24bit], or [M] to the path.
    • {explicit}: Adds [E] to the path.
    {
    "album_format": "{name}{explicit}",
    "playlist_format": "{name}{explicit}",
    "track_filename_format": "{track_number}. {name}",
    "single_full_path_format": "{name}",
    "enable_zfill": true,
    "force_album_format": false
}

  5. Configure Global General Settings

    master

    Global settings are located in config/settings.json. These settings apply to all loaded modules.

    KeyDescription
    download_pathAbsolute or relative output path (use / as delimiter).
    download_qualityThe target quality level. Options: hifi (FLAC > 44.1/16), lossless (FLAC 44.1/16), high (high bitrate lossy), medium (medium bitrate lossy), low (low bitrate lossy).
    search_limitNumber of search results to display.
    {
    "download_path": "./downloads/",
    "download_quality": "hifi",
    "search_limit": 10
}

  6. Configure Global Codecs

    master

    Enable or disable specific codec types in config/settings.json.

    • proprietary_codecs: Allows MQA, E-AC-3 JOC, or AC-4 IMS.
    • spatial_codecs: Allows MPEG-H 3D, E-AC-3 JOC, or AC-4 IMS.

    Note: spatial_codecs has priority over proprietary_codecs when deciding if a codec is enabled.

    {
    "proprietary_codecs": false,
    "spatial_codecs": true
}

  7. Configure Global Module Defaults

    master

    You can specify which module should be used to retrieve specific metadata by default. In config/settings.json, change the value from "default" to the specific module name found under /modules.

    Supported metadata types:

    • lyrics
    • covers
    • credits
    {
    "lyrics": "default",
    "covers": "default",
    "credits": "default"
}

  8. Configure Global Cover Art Settings

    master

    Control how album covers are handled in config/settings.json.

    OptionDescription
    embed_coverEnable embedding the album cover inside every track.
    main_compressionCompression level for the main cover.
    main_resolutionResolution (in pixels) for the module's cover.
    save_externalEnable saving covers from a third-party cover module.
    external_formatFormat for third-party covers: jpg, png, webp.
    external_compressionCompression for third-party covers: low, high.
    external_resolutionResolution (in pixels) for third-party covers.
    save_animated_coverEnable saving animated covers (e.g., MPEG-4) if supported.
    {
    "embed_cover": true,
    "main_compression": "high",
    "main_resolution": 1400,
    "save_external": false,
    "external_format": "png",
    "external_compression": "low",
    "external_resolution": 3000,
    "save_animated_cover": true
}