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 import Download
from fm_dlp_core.commands.downloader.params import 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 import Download
from fm_dlp_core.commands.downloader.params import 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"])

Save Download Parameters

from fm_dlp_core.utils.config.parametrs import set_parameters, get_parameters

# Save parameters with a specific color/key
set_parameters(
    codec="mp3",
    kbps=256,
    quality="720p",
    jobs=4,
    quiet=False,
    metadata=True,
    keep=False,
    only_video=False,
    cookies="chrome",
    remote="ejs:github",
    color=True,  # This serves as the profile key
)

# Load saved parameters for the same profile
params = get_parameters(color=True)
print(params)  # {'codec': 'mp3', 'kbps': 256, ...}

# Different profile
set_parameters(codec="flac", kbps=0, color=False)
params_high = get_parameters(color=False)

Set Download Path

from fm_dlp_core.utils.config.path import set_path, get_path

# Set download path
result = set_path("/my/download/folder")
print(result)  # "Configuration saved successfully"

# Get current path
path = get_path()
print(f"Downloads will be saved to: {path}")

Configuration File Examples

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

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

import asyncio
from fm_dlp_core import Download
from fm_dlp_core.commands.downloader.params import DownloadParams

class MyDownloader(Download):
    def _sync_download(self, url: str):
        # Override to add custom behavior
        print(f"Downloading: {url}")
        super()._sync_download(url)

async def main():
    params = DownloadParams(
        url="https://youtube.com/watch?v=...",
        codec="mp4",
        kbps=0,
        quality="1080p",
        jobs=2,
        quiet=False,
        metadata=True,
        keep=False,
        save=False,
        use_config=False,
        path="./videos",
        only_video=True,
        cookies=None,
        remote="ejs:github",
        color=True,
    )
    async with MyDownloader(params) as downloader:
        await downloader.download_all()

asyncio.run(main())

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.parametrs import set_parameters, get_parameters

# Save a profile with 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",
    color=True,
)

# Save another profile with 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",
    color=False,
)

# Load specific profile
params = get_parameters(color=True)  # Returns the flac profile
params_low = get_parameters(color=False)  # Returns the 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 = get_parameters(color=profile_color)
    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