Only affects formats that require transcoding: mp3, ogg/vorbis, flac always; opus and m4a only when transcoded. Lower number = better quality and larger file size.

If unsure, leave at the default.

Directory to save downloaded songs to. Always use forward slashes /, even on Windows.

Example: C:/Users/you/Music

Use forward slashes to sort into subfolders. Examples:

• {album_artist}/{year} - {album}/{track_pos} - {song}
• {album_artist}/{album}/{artist} - {song}

Required placeholders:

Optional placeholders:

Number of parallel yt-dlp download workers. Too many concurrent downloads on large libraries may trigger rate limiting, IP blocks, or account bans when using cookies. For large downloads keep at 1-2. Is reduced to 1 when sleep timer is set.

Size of the queue holding prefetched metadata. Total songs visible in the downloader window = queue size + downloaders + 1. Setting this above the number of downloaders rarely improves speed.

Fast downloading of a large number of songs may lead to your IP being blocked by YouTube. To avoid that, set a sleep timer when downloading a large amount of songs at once. (the exact limit is unknown, it is recommended when downloading over 100 and highly recommended when downloading over 300 songs at once). Setting sleep to a number higher than 0 lowers the number of downloaders to 1. The sleep timer is randomized, e.g. for sleep = 5 the timer will be 5-9 seconds long. You can also set a temporary sleep timer with the --sleep flag. More info here.

Path to a Netscape-format cookies file. Needed for age-restricted content. It is recommended to use the --cookies-from-browser firefox flag instead of setting this permanently.

Pull cookies directly from a browser (e.g. firefox). Needed for age-restricted content. Logging into YouTube with an age-verified Firefox account works best.

When a URL contains both a song (v=) and playlist (list=) ID, download the full playlist instead of only the single video.

Always download the full album for each song. Equivalent to the --fetch-albums flag.

Skip songs already present in the output location (checked by artist name and song title). Set to false if you want duplicates (e.g. single & album versions). Re-downloaded files will be overwritten when false. Can be temporarily disabled with --skip-file-check.

Path to an archive file. Song IDs are added after download so they are never downloaded again. The filename and extension do not matter.

Full file paths to sync JSON files, comma-separated. Each filename must be unique even across different folders. Use forward slashes on all platforms.

Example: /path/to/playlist1_sync.json, /path/to/playlist2_sync.json

Enable or disable embedding lyrics as a metadata field. Changes apply to all songs downloaded after saving.

Embed copyright/music label info in metadata. Sourced from the Deezer API.

Embed the International Standard Recording Code (ISRC) in metadata. Sourced from the Deezer API.

Embed genre in metadata. Sourced from the MusicBrainz API.

Embed the album artist field. It is strongly recommended to keep this enabled.

Puts all involved artists/bands in the artist data field. The {artist} placeholder in the output template will still only contain the primary artist.

Separator used to join multiple artists in a single metadata field. Options: ; or / variants. Do not use +, &, or |.

Only applies to mp3 and m4a. Opus, ogg, and FLAC support multiple separate artist fields.

Keep the metadata set by ffmpeg (usually just encoding information, not used by most music players). Set to true only if you need this data.

Download a cover.jpg file in the same folder as the song. Only one cover is created per folder, separation by album is recommended if you want to use this setting.

Store synced lyrics in the metadata of the audio file in addition to any sidecar files.

Generate a .lrc file containing synced lyrics alongside each downloaded song.

Writes synced lyrics into the unsynced (USLT) lyrics field for mp3. Workaround to make synced lyrics work in some media players. Only affects mp3 files.

Source used if the primary lyrics source returns no results. Use none if you only want synced lyrics and don't want the extra lookup delay.

Do not use the same source as the primary source.

Disabling will result in missing metadata. Used for genre data and artist MBIDs.

Disabling will result in missing metadata. Used for album info for certain songs.

Improves album metadata accuracy by cross-checking YouTube's album info with Genius. YouTube sometimes marks songs as singles even when they belong to an album. When enabled, SomeDL queries Genius for the actual album name.

Disabling will result in missing metadata. Used for music label (copyright) and ISRC data.

Maximum number of retry attempts. Currently only affects MusicBrainz API retries.

Minimum number of songs in a session before a download report is generated. Set to 1 to always show a report (or use the -R flag). Set to a very large number (e.g. 1000000) to disable reports entirely. Only applies for downloads made with the CLI. When using the WebUI, the downloads of the current session can be seen in the Download Histroy tab.

127.0.0.1 lets you access the application only on your local machine. Set the host to 0.0.0.0 to access the application from other devices on the same network (you will need to allow access to this port in your firewall).