fm-dlp — Python CLI wrapper over yt-dlp

fm-dlp is a CLI tool for searching YouTube/YTMusic and downloading audio/video from 1000+ sites

Quick Start
Requirements
Color Output
Commands
Examples
- Search Examples
- Basic Download
Search Output Examples
- Format Elements
License & Acknowledgments

Quick Start

pip install fm-dlp      # Python 3.11+ & FFmpeg required
fm-dlp config ~/Music   # Set download directory
fm-dlp search "query"   # Search tracks
fm-dlp download "URL"   # Download audio/video

Requirements

Python 3.11+ - TOML support required
FFmpeg - Required for audio/video processing and subtitle embedding. Install via:
- macOS: brew install ffmpeg
- Linux:
  - Debian: sudo apt install ffmpeg
  - Fedora: sudo dnf install ffmpeg
  - Arch Linux: sudo pacman -S ffmpeg
- Windows: Download from ffmpeg.org and add to PATH

If ffmpeg is not on your PATH, you can point fm-dlp directly to it with --ffmpeg-path (see download).

Color Output

By default, fm-dlp uses colored output for better readability. To disable colors globally, use the --no-color flag before the command:

fm-dlp --no-color config ~/Music
fm-dlp --no-color search "query"
fm-dlp --no-color download "URL"

Commands

`config`

Configure the default download directory path.

fm-dlp config <path> [OPTIONS]

Option	Default	Description
`path`	Required	Default directory path where downloaded files will be saved. Use absolute path for best results (e.g., '/home/user/Music' or 'C:\Music').
`-q`, `--quiet`	`False`	Suppress output messages.
`-C`, `--config-file`	`None`	Path to a custom TOML config file. Overrides the platform-specific default.

Config Location:

Windows: %LOCALAPPDATA%/fm-dlp/config.toml
macOS: ~/Library/Application Support/fm-dlp/config.toml
Linux: ~/.config/fm-dlp/config.toml

To use a config file at a custom location, pass --config-file /path/to/config.toml to the download command.

`search`

Search for music tracks, albums, or videos on YouTube/YTMusic.

fm-dlp search <query> [OPTIONS]

Option	Default	Description
`query`	Required	Search query string
`-l`, `--limit`	`10`	Maximum number of results to return
`-v`, `--yt-video`	`False`	Search for YouTube videos instead of music tracks
`-a`, `--album`	`False`	Search for albums instead of individual tracks
`-r`, `--raw`	`False`	Output results in raw format (Python dict representation)
`-u`, `--only-url`	`False`	Output only the URLs without any formatting

`download`

Download audio or video content from supported platforms (YouTube, YTMusic, and 1000+ sites).

fm-dlp download <urls> [OPTIONS]

Option	Default	Description
`url`	Required	Single URL or comma/space-separated list of URLs. Can also be a path to a text file containing URLs (one per line).
`-c`, `--codec`	`opus`	Audio codec or video container. Default depends on platform. For audio: mp3, aac, flac, m4a, opus, vorbis, wav, alac. For video: mp4, mov, mkv, webm, avi, flv.
`-K`, `--kbps`	`256`	Audio bitrate in kbps (64–320). Higher bitrate = better quality but larger file size.
`-Q`, `--quality`	`best`	Video quality preset: best, worst, 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p, 144p, or custom height (e.g., 720).
`-j`, `--jobs`	`5`	Maximum number of concurrent downloads. Increase for faster batch downloads.
`-q`, `--quiet`	`False`	Suppress yt-dlp output messages. Errors will still be shown.
`--no-metadata`	`False`	Disable embedding metadata (title, artist, album) and thumbnail into audio files.
`-k`, `--keep`	`False`	Keep the original downloaded file after conversion/post-processing. Useful when you want to retain both the original and converted versions.
`-s`, `--save`	`False`	Saving settings (except URL)
`-u`, `--use-config`	`False`	Use saved parameters from config file as defaults.
`-p`, `--path`	Configured path	Custom download directory path. Uses configured default if not specified.
`-fp`, `--ffmpeg-path`	`None`	Path to ffmpeg binary or directory containing ffmpeg/ffprobe. Passed to yt-dlp as ffmpeg_location. If omitted, yt-dlp searches PATH.
`-C`, `--config-file`	`None`	Path to a custom TOML config file. Overrides the platform-specific default.
`-v`, `--only-video`	`False`	Download a video file without audio track (video-only). Useful for editing, re-encoding, or when audio is not needed.
`--cookies`	`None`	Path to cookies file (e.g., 'cookies.txt') for authenticated downloads, or browser name ('brave', 'chrome', 'chromium', 'edge', 'opera', 'vivaldi', 'whale', 'firefox', 'safari') to extract cookies from browser.
`-r`, `--remote`	`None`	Download external JavaScript components for bypassing anti-bot protections (e.g., JS challenges). 'github' - download from yt-dlp GitHub repository, 'npm' - download from NPM package registry.
`-S`, `--subtitles`	`False`	Download subtitles for the video. Use --subtitle-langs to specify languages.
`-Sl`, `--subtitle-langs`	`None`	Comma-separated subtitle language codes, e.g. 'en,ru,ja'.
`-eS`, `--embed-subs`	`False`	Embed subtitles into the video container (requires FFmpeg).
`-aS`, `--auto-subs`	`False`	Include auto-generated subtitles (in addition to manually uploaded ones).
`-y`, `--ytdlp-args`	`None`	Extra yt-dlp options as a dict object. Merged last; 'postprocessors' are extended, other keys override.

CPU Detection: When parsing the download command, fm-dlp automatically detects the number of CPU cores on your system. The --jobs option is capped at this value to prevent overloading your system. If detection fails, a fallback value is used instead.

Audio Codec Details:

Lossy: mp3 (universal), aac (Apple), m4a (Apple), opus (modern web) - smaller files
Lossless: flac (high quality), wav (uncompressed), alac (Apple lossless) - larger files
Recommended: opus for best quality/size ratio, flac for archival

Video Container Details:

mp4 - Most compatible, uses m4a audio
mkv - Open format, uses opus audio
webm - Web optimized, uses opus audio
mov - Apple format, uses m4a audio
avi - Legacy Windows, uses mp3 audio
flv - Flash video, uses aac audio

Examples

Search Examples

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

Basic Download

Download a track from YouTube Music:

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

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

Example Output

Starting: https://music.youtube.com/watch?v=DVDiOMoW0wU
[youtube] Extracting URL: https://music.youtube.com/watch?v=DVDiOMoW0wU
[youtube] DVDiOMoW0wU: Downloading webpage
[youtube] DVDiOMoW0wU: Downloading visionos player API JSON
[youtube] DVDiOMoW0wU: Downloading m3u8 information
[info] DVDiOMoW0wU: Downloading 1 format(s): 251
[info] There are no subtitles for the requested languages
[info] Downloading video thumbnail 41 ...
[info] Writing video thumbnail 41 to: /home/kernel/Music/A Dream.webp
[download] Destination: /home/kernel/Music/A Dream.webm
[download] 100% of    2.55MiB in 00:00:00 at 2.73MiB/s
[ExtractAudio] Destination: /home/kernel/Music/A Dream.opus
Deleting original file /home/kernel/Music/A Dream.webm (pass -k to keep)
[Metadata] Adding metadata to "/home/kernel/Music/A Dream.opus"
[ThumbnailsConvertor] Converting thumbnail "/home/kernel/Music/A Dream.webp" to png
[EmbedThumbnail] mutagen: Adding thumbnail to "/home/kernel/Music/A Dream.opus"

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

Search Output Examples

Examples of formatting search results from different sources. Click each example to expand.

YTMusic (Track)

    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
           ──────────────────────────────────────────────────

YTMusic (Album)

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

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

YouTube (Video)

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

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

Format Elements

Element	Description
`N.`	Sequential number of search result
`Title`	Track, album, or video title
`Artist`	Artist or channel name
`├─└─│`	Tree branch characters
`Views │ Duration`	View count and length (MM:SS or HH:MM:SS)
`URL`	Direct link to content
`───`	Visual separator line

License & Acknowledgments

AGPLv3 License — Built with:

Library	Purpose
fm-dlp-core	Main core

Author: Fkernel653

Project: GitHub • PyPI

Metadata

Release files for fm-dlp 4.7.8.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fm-dlp 4.7.8.4
File	Size	Uploaded
fm_dlp-4.7.8.4.tar.gz	12.1 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for fm-dlp 4.7.8.4
File	Interpreter	ABI	Platform	Reset
fm_dlp-4.7.8.4-py3-none-any.whl 13.8 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 25.9 kB

Release files / fm_dlp-4.7.8.4.tar.gz

Download URL	fm_dlp-4.7.8.4.tar.gz
Size	12.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`33fefd240dc04d6b8c7e495498c212c430eee78fe5e0173906a3cb7526103ce0`
BLAKE2b-256 checksum How to use checksums	`88daadc4e5d50115306a289a6083e7af3b5478eccfc35ee965984fec0e227f0c`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / fm_dlp-4.7.8.4-py3-none-any.whl

Download URL	fm_dlp-4.7.8.4-py3-none-any.whl
Size	13.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`31822c7f59a8d1ceb4477e3296b7dc8cb5dcabc6af78f43e7738f18c2f36a207`
BLAKE2b-256 checksum How to use checksums	`c013b32659e5fefa7f8ea2a8058d0977b105eb47d9da318ed2879f1b1121013f`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`