VideoForge

VideoForge is a constrained Rust library for inspecting and archiving exact, public YouTube videos through an external yt-dlp process. It deliberately has no command-line binary and does not expose arbitrary yt-dlp arguments. Version 0.1 is YouTube-only; other providers such as X/Twitter are not accepted.

Requirements

• Rust 1.85 or newer.
• A current yt-dlp executable on PATH, or an explicit executable path.
• ffmpeg and ffprobe on PATH for archive downloads.
• The JavaScript runtime and YouTube EJS components recommended by the installed yt-dlp release (commonly Deno plus the EJS component) when YouTube extraction requires them. VideoForge disables remote component fetching, so install these dependencies independently and follow yt-dlp's official installation guide.

For example, install yt-dlp using an official package, Python package, or release binary, and install ffmpeg from the operating system package manager. VideoForge never self-updates these tools.

Usage

use std::{path::PathBuf, time::Duration};
use videoforge::{ArchiveOptions, VideoForge, VideoQuality, parse_video_target};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let forge = VideoForge::new();
    let target = parse_video_target("https://youtu.be/BaW_jenozKc")?;

    let summary = forge.inspect(&target, VideoQuality::Best, Duration::from_secs(120))?;
    println!("{}", summary.title);

    // Set authorized only after confirming that the download is permitted.
    let options = ArchiveOptions {
        output: PathBuf::from("video-archive"),
        authorized: true,
        ..ArchiveOptions::default()
    };
    let result = forge.archive(&[target], &options)?;
    assert_eq!(result.selected_ids.len(), result.archived + result.skipped + result.failed);
    Ok(())
}

VideoForge::with_executable selects a specific yt-dlp. Call dependency_info to report yt-dlp, ffmpeg, and ffprobe versions. The progress API reports inspection, download, verification, installation, skip, failure, and completion phases without exposing extractor data.

Scope And Safety

Accepted input is HTTPS only and must identify one 11-character YouTube video: youtube.com/watch?v=ID, youtu.be/ID, youtube.com/shorts/ID, youtube.com/live/ID, or youtube.com/embed/ID. www.youtube.com and m.youtube.com are also accepted. Credentials, ports, fragments, playlists, list parameters, extra query parameters, and other hosts or paths are rejected.

Downloads require ArchiveOptions::authorized = true; the caller is responsible for determining that it is authorized to save the content. The defaults impose a 2 GiB byte cap and a 30-minute timeout. VideoForge supports MP4, WebM, and Matroska outputs, checks container magic, hashes content with BLAKE3, and writes videoforge-video.json beside exactly one media file.

Existing recognized archives are fully verified before a requested skip. Current provider metadata and the requested quality policy must also match. Corrupt or stale recognized archives are rebuilt with staged replacement and rollback for ordinary runtime failures. A destination without a recognized VideoForge manifest or an internal installation marker is considered foreign and is never overwritten. Ambiguous state after an abrupt process or power failure is preserved for operator review instead of guessed or deleted. verify_archive can independently verify an archive directory.

VideoForge does not support authentication, cookies, credentials, proxies, geo bypass, impersonation, DRM bypass, plugins, remote components, SponsorBlock, access-control bypasses, or arbitrary extractor options. It only accepts metadata that yt-dlp identifies as public, age-unrestricted, non-live, and non-DRM. Every subprocess explicitly disables ambient proxies and yt-dlp geo bypass. Progress callbacks must return promptly; they are status observers, not places for blocking work.

You must comply with the YouTube Terms of Service and all applicable copyright and content licenses. A "Standard YouTube License" or an unknown/missing license does not grant redistribution rights. yt-dlp's software license governs the tool itself and does not grant any right to download, copy, or redistribute a video. VideoForge preserves source and attribution metadata but cannot determine whether a use is lawful.

Agent Guidance

Operational constraints for automated coding agents are embedded as videoforge::AGENT_GUIDE and are also available in AGENT_GUIDE.md.