# VideoForge Agent Guide
VideoForge is intentionally narrower than `yt-dlp`. Agents integrating or
modifying it must preserve the following boundaries.
## External Dependencies
VideoForge executes `yt-dlp` directly without a shell. Archive downloads also
require `ffmpeg` and `ffprobe`. Current YouTube extraction may require a supported
JavaScript runtime such as Deno and locally installed EJS components; consult the
official `yt-dlp` documentation. Remote component retrieval is disabled, and the
library never installs or updates dependencies.
Install these tools through trusted system packages or official distributions.
Use `VideoForge::with_executable` only to select a trusted local `yt-dlp` binary,
and `dependency_info` to inspect dependency versions.
## Required Workflow
1. Parse an exact URL with `parse_video_target`.
2. Optionally call `inspect(target, quality, timeout)` and show the source,
attribution, reported video license, and redistribution warning to the user.
3. Independently establish that the user is authorized to archive the video.
4. Set `ArchiveOptions::authorized` to `true` and choose explicit byte and time
limits.
5. Call `archive` or `archive_with_progress` and inspect every accumulated
`ArchiveFailure`.
6. Retain `videoforge-video.json` with the media and use `verify_archive` when
consuming or moving an archive.
Supported URLs are HTTPS `watch`, `youtu.be`, `shorts`, `live`, and `embed`
forms for an exact 11-character ID. Playlists, authentication, cookies,
credentials, proxies, geo bypass, impersonation, access-control workarounds,
plugins, remote components, self-update, SponsorBlock, arbitrary arguments, and
DRM bypass are out of scope and must not be added.
Version 0.1 accepts no non-YouTube providers. Add future providers only through
separate typed URL, policy, process, and archive implementations.
The default byte limit is 2 GiB and the default timeout is 30 minutes. Archives
contain one MP4, WebM, or Matroska media file plus one manifest. Existing valid
archives may be verified and skipped; recognized corrupt archives are repaired
with staged replacement and runtime rollback; foreign destination directories
are refused. Ambiguous state after abrupt process or power loss is preserved for
operator review rather than automatically deleted.
## Rights And Terms
Authorization is a mandatory caller decision, not a metadata inference. Follow
the YouTube Terms of Service and applicable law. The reported Standard YouTube
License, or an unknown license, does not grant redistribution. A Creative Commons
label still requires review of its terms and attribution obligations.
The license of `yt-dlp` covers that software only. It grants no rights in video
content. VideoForge preserves source, uploader/channel, reported license, and
attribution fields, but those fields are informational and are not legal advice.
## Maintenance Rules
- Keep every `yt-dlp` invocation config-free, plugin-free, remote-component-free,
YouTube-only, playlist-disabled, proxy-disabled, geo-bypass-disabled, bounded,
and non-interactive.
- Never invoke a shell or expose arbitrary process arguments.
- Keep metadata and diagnostic buffers bounded and kill the whole process tree on
timeout or byte-limit violations.
- Reinspect metadata for archive downloads and never persist signed media URLs,
request headers, format arrays, cookies, or credentials.
- Preserve symlink, traversal, container-magic, BLAKE3, exact-file-set, staging,
backup, rollback, and directory-sync checks.
- Keep network-independent fake-executable tests for argument hardening and all
archive safety invariants.
- Keep progress callbacks prompt and nonblocking; perform expensive work after
the archive call returns.