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
• 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).search():
    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",
            ffmpeg_path=None,
            config_file=None,
            only_video=False,
            cookies=None,
            remote=None,
            color=True,
            subtitles=False,
            subtitle_langs="en",
            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="Python tutorial",
    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("breakcore", limit=10, only_url=True).search())

# Chain search → download
urls = list(Search("chill beats", 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="en",
                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="https://youtube.com/watch?v=...",
            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="https://youtube.com/watch?v=...",
            # 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="en",
            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

🛠️ 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