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

# 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(
        url="https://music.youtube.com/watch?v=y55fzyXZDSE",
        codec="mp3",
        kbps=320,
        path="./music",
        metadata=True,
        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. 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, 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.

🎵 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

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="mp3",
    kbps=320,
    quality="best",
    jobs=4,
    quiet=False,
    metadata=True,
    keep=False,
    save=False,
    use_config=False,
    path="./downloads",
    only_video=False,
    cookies="chrome",
    remote="ejs:github",
    color=True,
)

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.

import asyncio
from fm_dlp_core import run_downloader

asyncio.run(
    run_downloader(
        url="https://youtube.com/watch?v=VIDEO_ID",
        codec="mp3",
        kbps=192,
        path="./downloads",
    )
)

from fm_dlp_core.commands.downloader import Download, DownloadParams


async def download_video():
    params = DownloadParams(
        url="https://youtube.com/watch?v=VIDEO_ID",
        codec="mp4",
        quality="1080p",
        jobs=4,
        path="./videos",
        metadata=True,
        only_video=True,
        remote="ejs:github",
        color=True,
    )

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

from fm_dlp_core.commands.downloader import Download, DownloadParams

# Multiple URLs (comma or space separated)
params = DownloadParams(
    url="url1,url2,url3",  # or "url1 url2 url3"
    codec="flac",
    kbps=0,  # Lossless
    jobs=3,
)

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

# URLs from a text file (one per line, comma/space separated supported)
params = DownloadParams(
    url="urls.txt",
    codec="m4a",
    kbps=256,
)

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

🔍 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,
):
    print(result)

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

# 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(url=" ".join(urls), codec="mp3", kbps=320))

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

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"},
}
toml_string = TOMLSerializer.dumps(data)
print(toml_string)
# Output:
# path = "/downloads"
#
# [parameters]
# codec = "mp3"
# kbps = 320
# quality = "best"
#

Supported types:

ParametersManager Class

Manages the [parameters] section — codec, bitrate, quality, jobs, boolean flags, cookies, and remote URL.

from fm_dlp_core.utils.config import ParametersManager

manager = ParametersManager(color=True)

# Save parameters
manager.set_parameters(
    codec="mp3",
    kbps=320,
    quality="best",
    jobs=4,
    quiet=False,
    metadata=True,
    keep=False,
    only_video=False,
    cookies="firefox",
    remote="ejs:github",
)

# Retrieve parameters
params = manager.get_parameters()
print(params["codec"])  # 'mp3'

Key behaviors:

• PARAM_KEY = "parameters" — the TOML section name
• The remote value is validated via validate_remote() before being stored
• cookies and remote are only written if truthy (omitted from the config otherwise)
• Success/error messages are suppressed when quiet=True

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,
    },
}
success = manager.update_config(new_config)
if success:
    print("Configuration updated successfully")
    # Cache is automatically cleared

from fm_dlp_core.utils.config import ParametersManager

# Save different profiles (keyed by the color flag)
ParametersManager(color=True).set_parameters(
    codec="flac", kbps=0, quality="best", jobs=8,
    quiet=False, metadata=True, keep=False, only_video=False,
)

ParametersManager(color=False).set_parameters(
    codec="aac", kbps=128, quality="720p", jobs=2,
    quiet=True, metadata=True, keep=False, only_video=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 = "ejs:github"

[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 = "ejs:github"

Using Configuration in Downloads

import asyncio
from fm_dlp_core import run_downloader

# This will automatically load saved config if use_config=True
asyncio.run(
    run_downloader(
        url="https://youtube.com/watch?v=...",
        codec="mp3",  # Will be overridden by saved config if use_config=True
        use_config=True,
        color=True,  # Determines which profile to load
    )
)

# Save current parameters for future use
asyncio.run(
    run_downloader(
        url="https://youtube.com/watch?v=...",
        codec="flac",
        kbps=0,
        save=True,  # Save these parameters
        color=True,
    )
)

📚 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