# Ubuntu/Debian
sudo apt install mpv

# Fedora/RHEL
sudo dnf install mpv

# Arch Linux
sudo pacman -S mpv

brew install mpv

Download from mpv.io/installation.

The primary entry point of the toolkit. Run with no arguments it opens an interactive hub for managing your entire media catalog; with a subcommand it runs that one task and exits (see the sections below).

bunkr-api                  # interactive dashboard
bunkr-api <command> ...    # scrape | download | stream | open | import | mint | inspect

Common Examples:

# Launch the main interactive catalog menu
bunkr-api

# Jump directly to a specific album detail view by its Database ID
bunkr-api open 17

# Import a local JSON metadata file and view it immediately
bunkr-api import ./album_metadata.json

# Search and resolve an album directly from the command line
bunkr-api scrape "Natalie Roush" --mode broad --per 40 --sort latest

Main Catalog Commands:

Inside the main menu, use these single-character commands:

The Album Detail View:

Once inside an album, the "Action Context" menu allows for granular media control:

1. Stream target(s): Launch your media player (MPV/VLC). Supports range selection.
2. Download target(s): Queue specific files for multi-threaded download.
3. Download ALL: Immediately begin retrieving every file in the album.
4. Copy link: Output the specific signed CDN URL for the chosen track to the terminal.
5. Mint new tokens: Triggers a manual batch refresh of CDN signatures with a real-time progress bar.
6. Stage/Unstage: Flag specific items (or the whole album) for later batch retrieval.
7. Navigation (n/p): Flip through pages of large asset inventories.

Upgrading from the bare-argument form? bunkr-api 17, bunkr-api "query", bunkr-api --db-id 17 and bunkr-api -i file.json still work for now: they are translated to open, scrape and import with a deprecation note on stderr. Prefer the explicit subcommands in scripts.

Why this command is the best choice for users:

1. Centralized Control: You never need to leave this interface to perform 99% of your tasks.
2. State Management: It automatically saves your progress; if you "Stage" items, they stay staged until you decide to download them.
3. Visual Feedback: Uses the full power of the Rich library to provide a clean, color-coded view of your library's health and token status.

A high-performance retrieval engine that utilizes a multi-threaded worker pool and the yt-dlp backend to maximize your bandwidth. It handles token resolution and directory organization automatically.

bunkr-api download [OPTIONS]

Common Examples:

# Download an entire album using 5 concurrent workers
bunkr-api download --db-id 17 --workers 5

# Download a specific range of files (e.g., first five files)
bunkr-api download --db-id 17 --number 1-5

# The Triage Workflow: Retry all files currently marked as 'FAILED' in the DB
bunkr-api download --triage --workers 3

# The Staged Workflow: Download everything globally marked as 'STAGED'
bunkr-api download --staged

# Point a download to a specific external hard drive path
bunkr-api download --db-id 17 -o "D:/Media/Archive"

Available Options:

Interactive Mode: If you run bunkr-api download in a terminal without choosing a source (--db-id, --staged, --triage, -i), it launches a catalog browser identical to the main dashboard, allowing you to pick an album and specify workers visually. Without a terminal (cron, pipes) it exits with an error instead of waiting for input. The source options are mutually exclusive.

Why this command is useful:

1. Error Recovery: The --triage flag is the fastest way to clean up a catalog that had network interruptions during a large batch.
2. Automation: It is perfect for headless environments or cron jobs (e.g., bunkr-api download --staged running every night).
3. Resource Management: You can precisely control system load by adjusting the --workers flag based on your current internet speed and CPU availability.

Stream content directly to your media player without downloading. This command automatically triggers the "Escape Hatch" to refresh any expired tokens before playback starts.

bunkr-api stream --db-id ID [OPTIONS]

Common Examples:

# Stream an entire album by its Database ID
bunkr-api stream --db-id 17

# Stream a specific selection (e.g., tracks 1, 5, and 10 through 15)
bunkr-api stream --db-id 17 --number 1,5,10-15

# Force playback in VLC instead of the default MPV
bunkr-api stream --db-id 17 --player vlc

# Stream everything currently marked as 'STAGED' in your database
bunkr-api stream --staged

Available Options:

Note on MPV: When using MPV, bunkr-api opens a JSON IPC server. This allows the terminal to show you exactly which track is playing, the current timestamp, and the buffer/cache duration in real-time.

Why this command is useful:

1. Low Latency: It bypasses the Main Menu logic, allowing you to start video playback in one command.
2. Headless Maintenance: If you know an album ID, you can start a stream without ever seeing the catalog list.
3. Staging Workflow: You can spend time "Staging" items via bunkr-api or bunkr-api inspect, and then later just run bunkr-api stream --staged to play your curated queue.

A deep-resolution engine designed to discover albums, extract asset metadata, and synchronize findings with your local database. Bypasses detection and provides real-time feedback during the resolution process.

bunkr-api scrape [QUERY] [OPTIONS]

Common Examples:

# Search for a creator and enter the interactive selection menu
bunkr-api scrape "InpossibleOreo"

# Perform a strict search with high result volume and custom sorting
bunkr-api scrape "Natalie" --mode strict --per 60 --sort mostfiles

# Browse trending videos from the last 24 hours
bunkr-api scrape --top videos

# Archive metadata to a specific folder without using the default export path
bunkr-api scrape "CreatorName" --save-json --output "C:/Backups/Bunkr_Metadata"

Available Options:

After the selection: once you pick an album it is cataloged in the database and its detail view opens, so you can stream, download or stage it straight away.

Deep Resolution Intelligence: Unlike basic scrapers, bunkr-api scrape performs a deep resolution. It navigates into your selected album, parses the internal JavaScript state, and extracts the True IDs required for streaming and downloading.

Why this command is useful:

1. Direct Cataloging: It is the primary way to "feed" your database. Any album resolved here becomes immediately available in bunkr-api, bunkr-api download, and bunkr-api stream.
2. Metadata Archival: By using --save-json, you can create a portable snapshot of an album's contents (including original filenames and sizes) before a link potentially goes dead.
3. Bypass Navigation: If you know exactly what you are looking for, flags like --mode strict and --sort mostfiles get you to the correct result much faster than manual browsing.

The "Swiss Army Knife" for your local database. bunkr-api inspect allows you to generate reports, manage staging queues, and perform database maintenance or schema migrations without writing raw SQL.

bunkr-api inspect [COMMAND] [TARGET] [OPTIONS]

Common Examples:

# View a global summary of your database health and pipeline metrics
bunkr-api inspect view dashboard

# Get a detailed per-album breakdown of completion % and total sizes
bunkr-api inspect view albums

# Dump every internal field for a specific album (useful for debugging IDs)
bunkr-api inspect view album --id 11

# Stage a range of assets globally for the next download run
bunkr-api inspect stage asset 50-100

# Repair metadata drift: Recompute file counts and aggregate sizes from actual records
bunkr-api inspect db --recount

# Permanently delete specific albums and their associated file records
bunkr-api inspect db --wipe 12,15-20

Available Sub-Commands:

1. view (Reporting)

2. stage (Queue Management)

Used to flag items for batch actions in bunkr-api download or bunkr-api stream.

• Targets: album (cascades to all files) or asset (individual files).
• Selection: Supports IDs, comma-separated lists, ranges, or all.
• Options: Use --off to remove the staging flag.

3. db (Maintenance & Write Ops)

Raw Table Dumps: You can filter any raw table view using --search "text" or change the output volume with --limit 50 or --all.

Why this command is useful:

1. Data Integrity: If the scraper crashes mid-way, --recount ensures your dashboard doesn't show "33 files" when only 10 were successfully cataloged.
2. Audit Logs: view expiring helps you predict which downloads might fail before you even start them.
3. Schema Evolution: As the project grows, add-column allows you to update your local database structure without losing your existing history.

A dedicated maintenance utility designed to keep your media library "hot." Because Bunkr CDN links use 2-hour time-limited expiration (ex) timestamps, they eventually stop working. bunkr-api mint automates the process of fetching fresh signatures using the stored True IDs in your database.

bunkr-api mint [OPTIONS]

Common Examples:

# Launch the background daemon
# This will poll your entire database every 60s and refresh tokens near expiry
bunkr-api mint

# Perform a one-shot targeted refresh for a specific album and then exit
bunkr-api mint --album-id 17

Available Options:

The "Escape Hatch" Workflow:

While the main bunkr-api dashboard triggers an automated "Escape Hatch" refresh when you start a stream or download, running bunkr-api mint in a separate terminal window is the recommended workflow for heavy users.

• Concurrency: Uses a semaphore-controlled worker pool to refresh dozens of tokens simultaneously without hitting rate limits.
• Progress Tracking: Features a real-time Rich progress bar and spinner so you can see exactly which assets are being updated.
• Database Sync: Automatically updates the signed_cdn_url and token_expiry_timestamp columns in your SQLite database.

Pro Tip: If you are planning a massive download session (100+ files), run bunkr-api mint in the background first to ensure every link is valid before the download engine starts.

Why this command is useful:

1. Continuous Uptime: Keeps your catalog ready for instant streaming at any time, even weeks after the initial scrape.
2. Headless Operations: Can be run on a server or a separate monitor to act as a "watchdog" for your media library.
3. Low Overhead: The daemon stays idle most of the time, only consuming network resources when tokens are actually nearing their expiration window (default 10 minutes).

Everything the CLI tools do is also available as a plain Python library, so you can script your own workflows, like cron jobs, batch imports, custom dashboards, all without touching the terminal UI at all. BunkrAPI is a single facade class wrapping the scraper, downloader, player, and database.

from bunkr_api import BunkrAPI

api = BunkrAPI()  # uses the same ~/.bunkr_api/media_tracker.db as the CLI tools

Async by design: nearly every method that touches the network, disk, or a subprocess is async def including download_album, which internally spawns a real worker pool via loop.run_in_executor() rather than blocking. This means you can safely await these from inside your own event loop (e.g. a web server request handler) without deadlocking. The only fully synchronous methods are the pure catalog lookups (get_albums, get_album, get_assets, get_valid_url) and delete_album. If you're writing a simple standalone script (not already inside an event loop), wrap your entry point in asyncio.run(...) as shown in every example below.

Full Method Reference:

Catalog & Retrieval (sync)

Scraping & Resolution (async)

Media Execution (async)

Maintenance

Example ; the classic three-step flow:

import asyncio
from bunkr_api import BunkrAPI

async def main():
    api = BunkrAPI()

    results = await api.search("Natalie Roush")
    if results:
        album_id = await api.resolve_album(results[0]["url"])
        print(f"Album registered with ID: {album_id}")
        await api.download_album(album_id, workers=3)

asyncio.run(main())

Example ; the same flow, collapsed into one call:

import asyncio
from bunkr_api import BunkrAPI

async def main():
    api = BunkrAPI()
    results = await api.search("Natalie Roush")
    if results:
        album_id = await api.resolve_and_download(results[0]["url"], workers=5)
        print(f"Resolved and downloaded album {album_id}")

asyncio.run(main())

Example ; browsing your existing catalog without touching the network:

from bunkr_api import BunkrAPI

api = BunkrAPI()

for album in api.get_albums():
    print(f"#{album['id']} — {album['title']} ({album['file_count']} files)")

# Drill into one album
album = api.get_album(5)
if album:
    for asset in api.get_assets(5):
        print(f"  {asset['title']} — {asset['download_status']}")
        # Get a guaranteed-fresh link, even if the cached token expired
        print(f"  -> {api.get_valid_url(asset['id'])}")

Example ; streaming programmatically:

import asyncio
from bunkr_api import BunkrAPI

async def main():
    api = BunkrAPI()
    # Stream tracks 1, 3, and 5-8 from album 17 in VLC instead of the MPV default
    await api.stream_album(17, indices_spec="1,3,5-8", player="vlc")

asyncio.run(main())

Example ; maintenance batch jobs (great for a nightly cron script):

import asyncio
from bunkr_api import BunkrAPI

async def nightly_maintenance():
    api = BunkrAPI()

    # Keep every token in the database fresh
    await api.refresh_tokens()

    # Pick up anything you staged earlier via `bunkr-api inspect stage` or the dashboard
    await api.download_staged(workers=4)

    # Give yesterday's network blips another chance
    await api.retry_failed(workers=4)

asyncio.run(nightly_maintenance())

Example ; resolving several albums concurrently with asyncio.gather:

import asyncio
from bunkr_api import BunkrAPI

async def main():
    api = BunkrAPI()
    urls = [
        "https://bunkr.cr/a/first-album",
        "https://bunkr.cr/a/second-album",
        "https://bunkr.cr/a/third-album",
    ]

    # resolve_album() itself is I/O-bound (network), so gathering several
    # at once is a genuine speedup, not just cosmetic concurrency.
    album_ids = await asyncio.gather(*(api.resolve_album(u) for u in urls))
    print(f"Registered {len(album_ids)} albums: {album_ids}")

    # Then download them all, one at a time (download_album already
    # parallelizes its own worker pool internally via `workers=`)
    for album_id in album_ids:
        await api.download_album(album_id, workers=5)

asyncio.run(main())

Example ; cleaning up an album you no longer want:

from bunkr_api import BunkrAPI

api = BunkrAPI()
was_deleted = api.delete_album(5)
print(f"Album 5 removed: {was_deleted}")  # False if it never existed

Why the Python API is useful:

1. No CLI required for automation: cron jobs, scheduled maintenance, or a custom Discord bot can all drive the same database the interactive tools use, with zero terminal interaction.
2. Composable: every method returns plain dicts/lists/ints/bools. No custom objects to learn, so it's trivial to slot into an existing script, web framework, or notebook.
3. Safe to embed: because the network/disk/subprocess methods are genuinely async (not just decorated), you can call them from inside your own already-running event loop; a FastAPI route handler, a Discord.py command, a Jupyter cell, all without the classic "asyncio.run() cannot be called from a running event loop" crash.