videoforge 0.1.0

A constrained, typed Rust wrapper for archiving public YouTube videos with yt-dlp
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# 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

```rust,no_run
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](https://www.youtube.com/static?template=terms)
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`](AGENT_GUIDE.md).