fm-dlp-core — Async Python wrapper over yt-dlp

fm-dlp-core is an async Python wrapper over yt-dlp for searching and downloading from YouTube, YTMusic, and 1000+ sites.

Table of Contents

• Quick Start
• Installation
• Requirements
• Core Concepts
  • Async-First Design
  • Configuration Persistence
  • Provider Pattern
  • Layered yt-dlp Options
• Downloading Content
  • Overview
  • DownloadParams Class
  • Download Parameters Reference
  • Supported Codecs
  • Executor Selection
• Searching Content
  • Overview
  • Search Parameters
  • Output Modes
• Configuration
  • Config file location
  • Custom config file
  • Usage
  • Low-level API
• API Reference
  • Core Package
  • Key Classes
  • Key Functions
• Download Output Examples
• Search Output Examples
  • Format Elements
• License & Acknowledgments

Quick Start

import asyncio
from fm_dlp_core import Search, run_downloader
from fm_dlp_core.commands.downloader import DownloadParams

# 1. Search for a track
for result in Search("query", limit=3, yt_video=False, album=False).search():
    print(result)

# 2. Download a track
asyncio.run(
    run_downloader(
        DownloadParams(
            url="URL",
            codec="mp3",
            kbps=320,
            quality="best",
            jobs=4,
            quiet=False,
            metadata=True,
            keep=False,
            save=False,
            use_config=False,
            path="./music",
            ffmpeg_path=None,
            config_file=None,
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
            subtitles=False,
            subtitle_langs=None,
            embed_subs=False,
            auto_subs=False,
            ytdlp_args=None,
        )
    )
)

Installation

pip install fm-dlp-core

For development:

git clone https://github.com/Fkernel653/fm-dlp-core
cd fm-dlp-core
pip install -e .

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 PATH, pass ffmpeg_path to DownloadParams.

Core Concepts

Async-First Design

All download operations are asynchronous, allowing you to run multiple downloads concurrently without blocking your application.

Configuration Persistence

Settings like codec, bitrate, quality, subtitle preferences, FFmpeg path, and download path can be saved to a TOML file and reused across sessions. A custom config file can be supplied via config_file.

Provider Pattern

Search functionality is built on a provider pattern, making it easy to add support for new platforms by subclassing BaseProvider.

Layered yt-dlp Options

The OptionsBuilder assembles options in priority order:

1. Base options (output template, concurrency, retries, ffmpeg_location)
2. Color / cookies / remote configuration
3. Codec-specific options (audio extraction, video conversion)
4. Subtitle options (if subtitles=True)
5. User-provided ytdlp_args — merged last, highest priority (postprocessors are extended, not replaced)

Downloading Content

Overview

The download system supports:

• Audio extraction in 8 formats (MP3, AAC, FLAC, M4A, Opus, Vorbis, WAV, ALAC)
• Video download in MP4, MKV, WebM, MOV, AVI, FLV with quality selection
• Batch downloads from multiple URLs or text files
• Concurrent downloads with configurable job limits
• Metadata embedding with thumbnails
• Subtitle download, including auto-generated subtitles, and embedding into the video container
• Custom FFmpeg location via ffmpeg_path
• Custom config file via config_file
• Arbitrary yt-dlp arguments passthrough for advanced use cases

DownloadParams Class

All download parameters are encapsulated in the DownloadParams dataclass:

from fm_dlp_core.commands.downloader import DownloadParams

params = DownloadParams(
    url="https://youtube.com/watch?v=...",
    codec="mp4",
    kbps=0,
    quality="1080p",
    jobs=4,
    quiet=False,
    metadata=True,
    keep=False,
    save=False,
    use_config=False,
    path="./downloads",
    ffmpeg_path=None,
    config_file=None,
    only_video=True,
    cookies="chrome",
    remote="github",
    color=True,
    subtitles=True,
    subtitle_langs="en,ru",
    embed_subs=True,
    auto_subs=False,
    ytdlp_args={
        "retries": 10,
        "fragment_retries": 10,
        "subtitlesformat": "srt/best",
        "postprocessors": [{"key": "FFmpegMetadata"}],
    },
)

Download Parameters Reference

Supported Codecs

Executor Selection

The downloader automatically selects the appropriate executor type:

• ProcessPoolExecutor — Used for video downloads and container formats (MP4, MKV, etc.) that benefit from CPU parallelism for transcoding
• ThreadPoolExecutor — Used for audio downloads (MP3, M4A, etc.) which are typically I/O-bound and work better with threading

This optimization is handled automatically based on the only_video flag and codec selection.

Searching Content

Overview

The search system supports:

• YouTube Music — Search for tracks and albums
• YouTube — Search for videos
• Formatted output with colors and structured display
• Raw data for programmatic use
• URL-only output for easy piping to downloads

Search Parameters

Output Modes

from fm_dlp_core import Search

for result in Search(
    query="Sewerslvt",
    limit=5,
    yt_video=False,  # Use YouTube Music
    album=False,  # Search for tracks
    color=True,
).search():
    print(result)

for result in Search(
    query="Psychology",
    limit=5,
    yt_video=True,  # Use YouTube (videos)
    album=False,
).search():
    print(result)

import asyncio
from fm_dlp_core import Search, run_downloader
from fm_dlp_core.commands.downloader import DownloadParams

# Get only URLs
urls = list(Search("Ambient", limit=10, only_url=True).search())

# Chain search → download
urls = list(Search("Synthwave", limit=5, only_url=True).search())
if urls:
    asyncio.run(
        run_downloader(
            DownloadParams(
                url=" ".join(urls),
                codec="mp3",
                kbps=320,
                quality="best",
                jobs=4,
                quiet=False,
                metadata=True,
                keep=False,
                save=False,
                use_config=False,
                path="./music",
                ffmpeg_path=None,
                config_file=None,
                only_video=False,
                cookies=None,
                remote=None,
                color=True,
                subtitles=False,
                subtitle_langs=None,
                embed_subs=False,
                auto_subs=False,
                ytdlp_args=None,
            )
        )
    )

Configuration

Download settings can be persisted to a TOML file and reused across sessions. This covers codec, bitrate, quality, jobs, metadata/keep flags, cookies, remote, subtitles, raw yt-dlp args, FFmpeg path, and the default download directory.

Config file location

Custom config file

Pass config_file to DownloadParams to use a custom TOML file instead of the platform-specific default:

DownloadParams(
    url="...",
    # ...
    config_file="/path/to/my-config.toml",
)

Rules:

• config_file must end with .toml. Otherwise, a warning is shown and the default config file is used.
• Both save=True and use_config=True respect config_file.
• Tilde (~) is expanded to the user's home directory.
• config_file is optional; when None, the platform-specific default is used.

Usage

Save parameters with save=True, load them back with use_config=True.

import asyncio
from fm_dlp_core import run_downloader
from fm_dlp_core.commands.downloader import DownloadParams

# Save current parameters (URL is not persisted)
asyncio.run(
    run_downloader(
        DownloadParams(
            url="URL",
            codec="flac",
            kbps=0,
            quality="best",
            jobs=4,
            quiet=False,
            metadata=True,
            keep=False,
            save=True,
            use_config=False,
            path="./music",
            ffmpeg_path=None,
            config_file=None,
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
            subtitles=True,
            subtitle_langs="en,ru",
            embed_subs=True,
            auto_subs=False,
            ytdlp_args=None,
        )
    )
)

# Load saved parameters on the next run
asyncio.run(
    run_downloader(
        DownloadParams(
            url="URL",
            # any values here are overridden by the saved config
            codec="mp3",
            kbps=0,
            quality="best",
            jobs=1,
            quiet=False,
            metadata=True,
            keep=False,
            save=False,
            use_config=True,
            path="./downloads",
            ffmpeg_path=None,
            config_file=None,
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
            subtitles=False,
            subtitle_langs=None,
            embed_subs=False,
            auto_subs=False,
            ytdlp_args=None,
        )
    )
)

Using a custom config file for both save and load:

# Save to a custom config file
DownloadParams(
    url="...",
    # ...
    save=True,
    config_file="~/.config/my-fm-dlp/music.toml",
)

# Load from the same custom config file
DownloadParams(
    url="...",
    # ...
    use_config=True,
    config_file="~/.config/my-fm-dlp/music.toml",
)

Low-level API

For direct file manipulation, use ConfigManager, ParametersManager, and PathManager from fm_dlp_core.utils.config. All three accept a ConfigParams instance that carries quiet, color, and config_file.

from fm_dlp_core.utils.config import ConfigManager, ConfigParams

params = ConfigParams(color=True, config_file=None)
manager = ConfigManager(params)
config = manager.load_config()
manager.update_config(config)

API Reference

Core Package

Key Classes

Key Functions

Download Output Examples

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

asyncio.run(
    run_downloader(
        DownloadParams(
            url="https://music.youtube.com/watch?v=DVDiOMoW0wU",
            codec="opus",
            kbps=256,
            quality="best",
            jobs=1,
            quiet=False,
            metadata=True,
            keep=False,
            save=False,
            use_config=False,
            path="/home/kernel/Music",
            ffmpeg_path=None,
            config_file=None,
            only_video=False,
            cookies=None,
            remote=None,
            subtitles=False,
            subtitle_langs=None,
            embed_subs=False,
            auto_subs=False,
            color=False,
            ytdlp_args=None,
        )
    )
)

Search Output Examples

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

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

Format Elements

License & Acknowledgments

AGPLv3 License — Built with:

Author: Fkernel653

Project: GitHub • PyPI