fm-dlp-core — Core Library for YouTube & 1000+ Sites

fm-dlp-core is a powerful Python library for searching and downloading content from YouTube, YouTube Music, and over 1000+ supported sites. Built on top of yt-dlp, it provides a clean, async-first API with rich features including concurrent downloads, metadata embedding, subtitle download/embedding, arbitrary yt-dlp args passthrough, and flexible output formatting.

📋 Table of Contents

• Quick Start
• Installation
• Requirements
• Core Concepts
• Downloading Content
  • Subtitles
  • Raw yt-dlp Arguments
• Searching Content
• Configuration
• API Reference
• 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("Sewerslvt", limit=3, yt_video=False, album=False):
    print(result)

# 2. Download a track
asyncio.run(
    run_downloader(
        DownloadParams(
            url="https://music.youtube.com/watch?v=y55fzyXZDSE",
            codec="mp3",
            kbps=320,
            quality="best",
            jobs=4,
            quiet=False,
            metadata=True,
            keep=False,
            save=False,
            use_config=False,
            path="./music",
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
        )
    )
)

📦 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

🧠 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, and download path can be saved to a TOML file and reused across sessions.

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)
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
• 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",
    only_video=True,
    cookies="chrome",
    remote="github",
    color=True,
    # --- Subtitles ---
    subtitles=True,
    subtitle_langs="en,ru",
    embed_subs=True,
    auto_subs=False,
    # --- Raw yt-dlp args ---
    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.

📝 Subtitles

Subtitles can be downloaded alongside video/audio, saved as separate files, or embedded 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=True.
• 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"].

from fm_dlp_core.commands.downloader import Download, DownloadParams

params = DownloadParams(
    url="https://youtube.com/watch?v=VIDEO_ID",
    codec="mkv",
    kbps=0,
    quality="1080p",
    jobs=1,
    quiet=False,
    metadata=True,
    keep=False,
    save=False,
    use_config=False,
    path="./videos",
    only_video=True,
    cookies=None,
    remote="github",
    color=True,
    subtitles=True,
    subtitle_langs="en,ru",
    embed_subs=True,
    auto_subs=False,
)

async with Download(params) as dl:
    await dl.download_all()

params = DownloadParams(
    url="https://youtube.com/watch?v=VIDEO_ID",
    codec="mp3",
    kbps=320,
    quality="best",
    jobs=2,
    quiet=False,
    metadata=True,
    keep=False,
    save=False,
    use_config=False,
    path="./audio",
    only_video=False,
    cookies=None,
    remote=None,
    color=True,
    subtitles=True,
    subtitle_langs="en",
    embed_subs=False,   # audio → embedding is skipped anyway
    auto_subs=True,     # include auto-generated
)

🧩 Raw yt-dlp Arguments

For anything not covered by the high-level API, you can pass arbitrary yt-dlp options via ytdlp_args.

Rules

• 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.

params = DownloadParams(
    # ... required fields ...
    ytdlp_args={
        "retries": 10,
        "fragment_retries": 10,
        "subtitlesformat": "srt/best",
    },
)

params = DownloadParams(
    # ... required fields ...
    ytdlp_args={
        "postprocessors": [
            {"key": "FFmpegMetadata"},
            {"key": "SponsorBlock", "categories": ["sponsor"]},
        ],
    },
)
# Built-in postprocessors (e.g. FFmpegExtractAudio / FFmpegVideoConvertor)
# are preserved and the custom ones are appended.

params = DownloadParams(
    # ... required fields ...
    ytdlp_args={
        "sleep_interval_requests": 1,
        "sleep_interval": 2,
        "max_sleep_interval": 5,
    },
)

🔍 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="Python tutorial",
    limit=5,
    yt_video=True,  # Use YouTube (videos)
    album=False,
).search():
    print(result)

from fm_dlp_core.commands.downloader import DownloadParams

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

# Chain search → download
urls = list(search("chill beats", limit=5, only_url=True))
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",
                only_video=False,
                cookies=None,
                remote=None,
                color=True,
            )
        )
    )

⚙️ Configuration

Overview

The configuration system provides:

• Persistent parameters — Save download settings across sessions
• Multiple config profiles — Each profile is keyed by the color parameter value
• Download path — Set default download directory (stored separately)
• TOML format — Human-readable config file
• Cookie support — Browser cookies for restricted content
• Subtitle preferences — Persist subtitle/auto-sub/embed settings and languages
• Raw yt-dlp args — Persist advanced overrides

Configuration File Location

Configuration Architecture

The configuration subsystem is composed of three collaborating modules:

ConfigManager Class

The ConfigManager class is the low-level engine responsible for loading and updating the TOML configuration file.

from fm_dlp_core.utils.config import ConfigManager

manager = ConfigManager(color=True)

# Load configuration (cached for performance via @lru_cache(maxsize=1))
config = manager.load_config()

# Update configuration (automatically invalidates the cache)
config["path"] = "/downloads"
manager.update_config(config)  # Returns True on success

TOMLSerializer Class

The TOMLSerializer class converts Python data structures into TOML string representation. It is used internally by ConfigManager.update_config().

from fm_dlp_core.utils.config import TOMLSerializer

data = {
    "path": "/downloads",
    "parameters": {
        "codec": "mp3",
        "kbps": 320,
        "quality": "best",
        "subtitles": True,
        "subtitle_langs": "en,ru",
        "embed_subs": True,
        "auto_subs": False,
    },
}
toml_string = TOMLSerializer.dumps(data)
print(toml_string)
# Output:
# path = "/downloads"
#
# [parameters]
# codec = "mp3"
# kbps = 320
# quality = "best"
# subtitles = true
# subtitle_langs = "en,ru"
# embed_subs = true
# auto_subs = false
#

Supported types:

ParametersManager Class

Manages the [parameters] section — codec, bitrate, quality, jobs, boolean flags, cookies, remote URL, subtitles, and raw yt-dlp args.

Note: set_parameters() now accepts a single DownloadParams instance.

from fm_dlp_core.commands.downloader import DownloadParams
from fm_dlp_core.utils.config import ParametersManager

manager = ParametersManager(color=True)

# Save parameters (pass a DownloadParams instance)
manager.set_parameters(
    DownloadParams(
        url="",  # URL is intentionally not persisted
        codec="mp4",
        kbps=0,
        quality="1080p",
        jobs=4,
        quiet=False,
        metadata=True,
        keep=False,
        save=True,
        use_config=False,
        path="./videos",
        only_video=True,
        cookies="firefox",
        remote="github",
        color=True,
        subtitles=True,
        subtitle_langs="en,ru",
        embed_subs=True,
        auto_subs=False,
        ytdlp_args={"retries": 10},
    )
)

# Retrieve parameters
params = manager.get_parameters()
print(params["codec"])           # 'mp4'
print(params["subtitles"])       # True
print(params["subtitle_langs"])  # 'en,ru'

PathManager Class

Manages the top-level path key — the download directory.

from fm_dlp_core.utils.config import PathManager

manager = PathManager(color=True)

# Save a path (tilde is expanded, existence is validated)
manager.set_path("~/Downloads")
# Returns: 'Configuration saved successfully'

# Retrieve the path
manager.get_path()
# Returns: '/home/user/Downloads'

Configuration Functions

Configuration Management Features

1. Cross-Platform Path Resolution

   • Windows: Uses LOCALAPPDATA or APPDATA environment variables
   • macOS: Uses ~/Library/Application Support
   • Linux: Uses XDG_CONFIG_HOME or ~/.config

2. Error Handling

   • Gracefully handles corrupted config files with colored error messages
   • Automatically creates new config file if corrupted or missing
   • Permission errors and OS errors are caught and reported

3. Atomic Operations

   • Configuration file operations create parent directories as needed
   • Writes are performed via Path.write_text() with UTF-8 encoding

Configuration Profiles

The configuration system supports multiple profiles using the color parameter as the key.

from fm_dlp_core.utils.config import ConfigManager

manager = ConfigManager(color=True)

config = manager.load_config()
print(config)  # {'path': '/downloads', 'parameters': {...}}

# Update configuration (clears cache automatically)
new_config = {
    "path": "/new/downloads",
    "parameters": {
        "codec": "flac",
        "kbps": 0,
        "quality": "best",
        "jobs": 4,
        "metadata": True,
        "subtitles": True,
        "subtitle_langs": "en,ru",
    },
}
success = manager.update_config(new_config)
if success:
    print("Configuration updated successfully")
    # Cache is automatically cleared

from fm_dlp_core.commands.downloader import DownloadParams
from fm_dlp_core.utils.config import ParametersManager

# Save different profiles (keyed by the color flag)
ParametersManager(color=True).set_parameters(
    DownloadParams(
        url="", codec="flac", kbps=0, quality="best", jobs=8,
        quiet=False, metadata=True, keep=False, save=True, use_config=False,
        path="./music", only_video=False, cookies=None, remote=None, color=True,
        subtitles=True, subtitle_langs="en,ru", embed_subs=True, auto_subs=False,
    )
)

ParametersManager(color=False).set_parameters(
    DownloadParams(
        url="", codec="aac", kbps=128, quality="720p", jobs=2,
        quiet=True, metadata=True, keep=False, save=True, use_config=False,
        path="./mobile", only_video=False, cookies=None, remote=None, color=False,
        subtitles=False, subtitle_langs="en", embed_subs=False, auto_subs=False,
    )
)

# Load specific profiles
print(f"High quality: {ParametersManager(color=True).get_parameters()}")
print(f"Mobile quality: {ParametersManager(color=False).get_parameters()}")

Configuration File Examples

# Main configuration file: config.toml
path = "/home/user/folder"

[parameters]  # Profile for color=True
codec = "opus"
kbps = 256
quality = "best"
jobs = 5
quiet = false
metadata = true
keep = false
only_video = false
cookies = "firefox"
remote = "github"
subtitles = true
subtitle_langs = "en,ru"
embed_subs = false
auto_subs = true

[parameters_0]  # Profile for color=False
codec = "mp3"
kbps = 192
quality = "1080"
jobs = 3
quiet = true
metadata = true
keep = false
only_video = false
cookies = "chrome"
remote = "github"
subtitles = false
subtitle_langs = "en"
embed_subs = false
auto_subs = false

Using Configuration in Downloads

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

# This will automatically load saved config if use_config=True
asyncio.run(
    run_downloader(
        DownloadParams(
            url="https://youtube.com/watch?v=...",
            codec="mp3",       # Will be overridden by saved config if use_config=True
            kbps=0,
            quality="best",
            jobs=1,
            quiet=False,
            metadata=True,
            keep=False,
            save=False,
            use_config=True,
            path="./downloads",
            only_video=False,
            cookies=None,
            remote=None,
            color=True,        # Determines which profile to load
        )
    )
)

# Save current parameters for future use
asyncio.run(
    run_downloader(
        DownloadParams(
            url="https://youtube.com/watch?v=...",
            codec="flac",
            kbps=0,
            quality="best",
            jobs=4,
            quiet=False,
            metadata=True,
            keep=False,
            save=True,         # Save these parameters
            use_config=False,
            path="./music",
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
            subtitles=True,
            subtitle_langs="en,ru",
            embed_subs=True,
            auto_subs=False,
            ytdlp_args={"retries": 10},
        )
    )
)

📚 API Reference

Core Package

Key Classes

Key Functions

🛠️ Output Formatting

Search Results Format

    1. Mr. Kill Myself
        ├─ Sewerslvt
        ├─ Draining Love Story
        ├─ 13,456,789 │ 7:52
        └─ https://music.youtube.com/watch?v=y55fzyXZDSE
           ──────────────────────────────────────────────────

Format Elements

📄 License & Acknowledgments

AGPLv3 License — Built with:

Author: Fkernel653

Project: GitHub • PyPI