Download a track from YouTube Music:

fm-dlp download https://music.youtube.com/watch?v=0KNxOBerr_8

With custom settings:

# Download as high-quality MP3 with metadata
fm-dlp download "URL" --codec mp3 --kbps 320 --path ~/Music

# Download video in 1080p
fm-dlp download "URL" --quality 1080p --codec mp4

# Batch download from file
fm-dlp download urls.txt --jobs 3 --quiet

# Use saved config and cookies from browser
fm-dlp download "URL" --use-config --cookies chrome

# Download video-only and keep original file
fm-dlp download "URL" --only-video --keep

Starting: https://music.youtube.com/watch?v=0KNxOBerr_8
[youtube] Extracting URL: https://music.youtube.com/watch?v=0KNxOBerr_8
[youtube] 0KNxOBerr_8: Downloading webpage
[youtube] 0KNxOBerr_8: Downloading android vr player API JSON
[info] 0KNxOBerr_8: Downloading 1 format(s): 251
[info] Downloading video thumbnail 41 ...
[info] Writing video thumbnail 41 to: /home/user/Music/Lexapro Delirium.webp
[download] Destination: /home/user/Music/Lexapro Delirium.webm
[download] 100% of    6.53MiB in 00:00:01 at 5.74MiB/s
[ExtractAudio] Destination: /home/user/Music/Lexapro Delirium.opus
Deleting original file /home/user/Music/Lexapro Delirium.webm (pass -k to keep)
[Metadata] Adding metadata to "/home/user/Music/Lexapro Delirium.opus"
[ThumbnailsConvertor] Converting thumbnail "/home/user/Music/Lexapro Delirium.webp" to png
[EmbedThumbnail] mutagen: Adding thumbnail to "/home/user/Music/Lexapro Delirium.opus"

Success: https://music.youtube.com/watch?v=0KNxOBerr_8

Search for tracks, albums, and videos:

# Search for tracks on YouTube Music
fm-dlp search "Sewerslvt" --limit 5

# Search for albums
fm-dlp search "Skitzofrenia Simulation" --album --limit 1

# Search for videos on YouTube
fm-dlp search "Psychology" --yt-video --limit 1

# Get raw data for scripting
fm-dlp search "Willix" --raw

# Get only URLs for batch processing
fm-dlp search "ativansocial" --only-url > urls.txt

Download subtitles alongside the video, save them as separate files, or embed them directly into the video container.

How it works

⚠️ Embedding caveats

• Requires FFmpeg.
• Only makes sense for video codecs (mp4, mkv, webm, mov) or when --only-video is set.
• For audio-only codecs (mp3, flac, etc.) --embed-subs is silently skipped.

Language selection

--subtitle-langs is a comma-separated string, e.g. "en,ru,ja". Whitespace is stripped. If empty, defaults to ["en"].

Examples

Download video with English + Russian subtitles embedded into MKV

fm-dlp download "URL" \
  --codec mkv \
  --quality 1080p \
  --only-video \
  --subtitles \
  --subtitle-langs "en,ru" \
  --embed-subs

Download audio with subtitles saved as separate .srt files

fm-dlp download "URL" \
  --codec mp3 \
  --kbps 320 \
  --subtitles \
  --subtitle-langs "en" \
  --auto-subs

For anything not covered by the high-level CLI, you can pass arbitrary yt-dlp options via --ytdlp-args (short: -y).

Rules

• Value must be a dict (Python literal).
• Keys are snake_case yt-dlp option names (the same keys used by YoutubeDL(opts)).
• Options are merged last into the built options dict → they override existing values.
• Exception: postprocessors are extended (built-in postprocessors are preserved) rather than replaced.

Examples

Add retries and a custom subtitle format

fm-dlp download "URL" -y '{"retries": 10, "fragment_retries": 10, "subtitlesformat": "srt/best"}'

Extend postprocessors without losing built-ins

fm-dlp download "URL" -y '{"postprocessors": [{"key": "FFmpegMetadata"}, {"key": "SponsorBlock", "categories": ["sponsor"]}]}'

Rate-limit requests

fm-dlp download "URL" -y '{"sleep_interval_requests": 1, "sleep_interval": 2, "max_sleep_interval": 5}'

--ffmpeg-path, -fp

Point fm-dlp to a specific ffmpeg binary or to a directory containing ffmpeg/ffprobe. Passed to yt-dlp as ffmpeg_location. Useful when ffmpeg is not on your PATH.

# Directory containing ffmpeg/ffprobe
fm-dlp download "URL" --ffmpeg-path /usr/local/bin

# Specific ffmpeg binary
fm-dlp download "URL" --ffmpeg-path /opt/ffmpeg/bin/ffmpeg

--config-file

Use a TOML config file at a custom location. Overrides the platform-specific default path (see config).

fm-dlp download "URL" --config-file ~/my-fm-dlp.toml

--path, -p

Override the configured download directory for a single run.

fm-dlp download "URL" --path ~/Music/Downloads

Persist your download preferences (everything except the URL) into the config file, then reuse them later with --use-config.

# Save current settings
fm-dlp download "URL" --codec flac --kbps 320 --save

# Reuse them for the next download
fm-dlp download "URL" --use-config

    1. A Dream
        ├─ Flatsound
        ├─ Somewhere in the Distance, Somewhere Toward the Mountains
        ├─ 4M │ 2:51
        └─ https://music.youtube.com/watch?v=DVDiOMoW0wU
          ──────────────────────────────────────────────────

    N. Title
        ├─ Artist
        ├─ Album
        ├─ Views │ Duration
        └─ URL
           ──────────────────────────────────────────────────

    1. Skitzofrenia Simulation
        ├─ Sewerslvt
        ├─ 2021
        └─ https://music.youtube.com/playlist?list=OLAK5uy_kXLBb5YlVizbrgXAHwTgarL5HYC3usuYA
          ──────────────────────────────────────────────────

    N. Title
        ├─ Artist
        ├─ Year
        └─ URL
           ──────────────────────────────────────────────────

    1. Silence , I'm Dying.
        ├─ Willix
        ├─ 587,740 │ 2:05
        └─ https://youtu.be/oSOaz5yaBM8
          ──────────────────────────────────────────────────

    N. Title
        ├─ Artist
        ├─ Views │ Duration
        └─ URL
           ──────────────────────────────────────────────────