Basic Usage with run_downloader

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

Advanced Usage with Download Class

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()

Batch Downloads

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()

Manual Configuration Management

from fm_dlp_core.commands.downloader import DownloadConfig, DownloadParams

params = DownloadParams(
    url="https://youtube.com/watch?v=...",
    codec="mp3",
    kbps=320,
    quality="best",
    jobs=4,
    quiet=False,
    metadata=True,
    keep=False,
    save=True,  # Save to config
    use_config=True,  # Load from config
    path="./downloads",
    only_video=False,
    cookies="chrome",
    remote="ejs:github",
    color=True,
)

# Config will automatically handle save/load based on params
config = DownloadConfig(params)
applied_params = config.apply_config()  # Returns dict with merged params
config.save_config()  # Saves if save=True

YouTube Music Search (Tracks)

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)

YouTube Music Search (Albums)

for result in search(
    query="Draining Love Story",
    limit=3,
    yt_video=False,
    album=True,  # Search for albums
):
    print(result)

YouTube Video Search

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

URL-Only Output

# 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))

Raw Data Output

for data in search("Goreshit", limit=2, raw=True):
    print(data["title"], data["url"])

Loading Configuration with Caching

from fm_dlp_core.utils.config import ConfigManager

manager = ConfigManager(color=True)

# Load configuration (cached for performance)
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

Manual Configuration File Management

from fm_dlp_core.utils.config import (
    CONFIG_DIR,
    CONFIG_FILE,
    ENCODING,
    TOMLSerializer,
)

# Get configuration directory
print(f"Config directory: {CONFIG_DIR}")
# Output: /home/user/.config/fm-dlp (Linux)
# Output: /Users/user/Library/Application Support/fm-dlp (macOS)
# Output: C:\Users\user\AppData\Local\fm-dlp (Windows)

# Check if config file exists
if CONFIG_FILE.exists():
    print("Config file found!")
    content = CONFIG_FILE.read_text(encoding=ENCODING)
    print(content)

# Create custom TOML data
data = {
    "path": "/custom/path",
    "parameters": {
        "codec": "opus",
        "kbps": 192,
        "quality": "720p",
        "quiet": True,
        "metadata": True,
        "keep": False,
        "only_video": False,
        "cookies": "firefox",
        "remote": "ejs:github",
    },
}

# Serialize and save manually
toml_content = TOMLSerializer.dumps(data)
CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
CONFIG_FILE.write_text(toml_content, encoding=ENCODING)

Automatic Profile Management

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 Directory Structure

from fm_dlp_core.utils.config import get_config_dir

# Get configuration directory
config_dir = get_config_dir("my-app")  # Custom application name
print(f"Config directory: {config_dir}")

# Default directory for fm-dlp
default_dir = get_config_dir()  # Uses "fm-dlp"
print(f"Default config directory: {default_dir}")

Create your own search provider by subclassing BaseProvider:

from fm_dlp_core.commands.search.providers import BaseProvider


class SoundCloudProvider(BaseProvider):
    def _extract_results(self, query: str, limit: int, is_track: bool) -> list:
        # Implement your search logic
        # Return list of entries (dicts)
        return results

    def _extract_url(self, entry: dict, is_track: bool) -> str | None:
        return entry.get("permalink_url")

    def _fmt_entry(self, entry: dict, num: int, is_track: bool) -> str | None:
        return self.formatter.fmt_result(
            num=num,
            title=entry.get("title", "Unknown"),
            artist=entry.get("user", {}).get("username", "Unknown"),
            url=self._extract_url(entry, is_track),
            is_yt_video=False,
            is_track=is_track,
        )

    def _get_empty_message(self, query: str, is_track: bool) -> str:
        return f"No results found for '{query}'\n"


# Use your provider
provider = SoundCloudProvider(color=True, error_prefix="Error: ")
for result in provider.search(query="lo-fi", limit=5, is_track=True):
    print(result)

For advanced use cases, you can build custom yt-dlp options:

from fm_dlp_core.commands.downloader import DownloadParams, OptionsBuilder

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="firefox",
    remote="ejs:github",
    color=True,
)

builder = OptionsBuilder(params)
opts = builder.build()

# Add custom options
opts["extractor_args"] = {"youtube": {"skip": ["hls"]}}

# Use with yt-dlp directly
from yt_dlp import YoutubeDL

with YoutubeDL(opts) as ydl:
    ydl.download(["https://youtube.com/watch?v=..."])

For private or age-restricted content:

import asyncio
from fm_dlp_core import run_downloader

# Using browser cookies
asyncio.run(
    run_downloader(
        url="https://youtube.com/watch?v=...",
        codec="mp3",
        cookies="chrome",  # or "firefox", "edge", "opera"
        path="./downloads",
    )
)

# Using cookies file
asyncio.run(
    run_downloader(
        url="https://youtube.com/watch?v=...",
        codec="mp3",
        cookies="./cookies.txt",
        path="./downloads",
    )
)

The quality parameter supports the following formats:

import asyncio
from fm_dlp_core import run_downloader


async def download_playlist(playlist_url: str):
    await run_downloader(
        url=playlist_url,
        codec="flac",
        kbps=0,  # Lossless
        jobs=4,
        metadata=True,
        path="./music",
        color=True,
    )


asyncio.run(download_playlist("https://music.youtube.com/playlist?list=..."))

import asyncio
from fm_dlp_core import search, run_downloader


def get_top_tracks(artist: str, limit: int = 5) -> list[str]:
    return list(search(artist, limit=limit, yt_video=False, only_url=True))


async def download_artist(artist: str):
    urls = get_top_tracks(artist, limit=3)
    if urls:
        await run_downloader(
            url=" ".join(urls),
            codec="mp3",
            kbps=320,
            metadata=True,
            path=f"./music/{artist}",
        )


asyncio.run(download_artist("Porter Robinson"))

from fm_dlp_core import search

# Get raw data for programmatic use
for result in search(
    query="Daft Punk",
    limit=10,
    yt_video=False,
    album=False,
    raw=True,  # Returns dicts
):
    print(f"Title: {result['title']}")
    print(f"Artist: {result.get('artists', [{}])[0].get('name', 'Unknown')}")
    print(f"Duration: {result.get('duration')}s")
    print(f"URL: https://music.youtube.com/watch?v={result.get('videoId')}")
    print("-" * 40)

import asyncio
from fm_dlp_core import run_downloader


async def safe_download(url: str):
    try:
        await run_downloader(
            url=url,
            codec="mp3",
            kbps=192,
            path="./downloads",
        )
    except Exception as e:
        print(f"Download failed for {url}: {e}")


asyncio.run(safe_download("https://youtube.com/watch?v=invalid_id"))

from fm_dlp_core.utils.config import ParametersManager

# Save a profile with color=True
ParametersManager(color=True).set_parameters(
    codec="flac", kbps=0, quality="best", jobs=4,
    quiet=False, metadata=True, keep=False, only_video=False,
    cookies="chrome", remote="ejs:github",
)

# Save another profile with color=False
ParametersManager(color=False).set_parameters(
    codec="mp3", kbps=192, quality="720", jobs=2,
    quiet=True, metadata=True, keep=False, only_video=False,
    cookies="firefox", remote="ejs:github",
)

# Load specific profile
params = ParametersManager(color=True).get_parameters()   # flac profile
params_low = ParametersManager(color=False).get_parameters()  # mp3 profile

# Use a specific profile in download
import asyncio
from fm_dlp_core import run_downloader


async def download_with_profile(profile_color: bool):
    params = ParametersManager(color=profile_color).get_parameters()
    await run_downloader(
        url="https://youtube.com/watch?v=...",
        codec=params["codec"],
        kbps=params["kbps"],
        quality=params["quality"],
        jobs=params["jobs"],
        quiet=params["quiet"],
        metadata=params["metadata"],
        keep=params["keep"],
        only_video=params["only_video"],
        cookies=params["cookies"],
        remote=params["remote"],
        use_config=False,  # Manual param passing
        color=profile_color,
    )


asyncio.run(download_with_profile(True))

from fm_dlp_core.commands.downloader import URLParser

# Parse URLs from comma-separated string
parser = URLParser("url1,url2,url3", quiet=False)
urls = parser.parse()
print(urls)  # ['url1', 'url2', 'url3']

# Parse URLs from space-separated string
parser = URLParser("url1 url2 url3", quiet=False)
urls = parser.parse()

# Parse URLs from file (one per line, comma/space separated supported)
parser = URLParser("urls.txt", quiet=False)
urls = parser.parse()

# File content example:
# https://youtube.com/watch?v=abc123
# https://youtube.com/watch?v=def456, https://youtube.com/watch?v=ghi789
# # This is a comment (ignored)
# https://youtube.com/watch?v=jkl012