Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat: a reference video can be a link, and yt-dlp turns it into a file (#89)

rponeawadd1468ec1957
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index d1ac6543..93b8b9e7 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -42,8 +42,10 @@ the boundary and launcher selection. Read it before the first command of any rou
- Reference-video reconstruction, reverse engineering, shot/B-roll/overlay analysis, or recreating
a video as Hypit source → read `references/reconstruction/route.md`. This is the route whatever
the author calls it — reconstruct, reverse-engineer, recreate, replicate, clone, remake, copy,
- rebuild, or the same idea in any language — and **a path to a video file, with or without words
- around it, is this route** even when no verb is given at all. A video path with a change attached —
+ rebuild, or the same idea in any language — and **a video, with or without words around it, is
+ this route** even when no verb is given at all. A path to a file and a link to one — TikTok,
+ YouTube, Instagram, Bilibili — are the same request; a link is fetched with `yt-dlp` and everything
+ after that reads the file. A video with a change attached —
this one but with our presenter, our product, our brand — is this route too, and the change is made
on the finished reconstruction. The path is the whole request: the working directory, the project
location and the vocabulary are yours to decide rather than to ask for.
@@ -51,7 +53,7 @@ the boundary and launcher selection. Read it before the first command of any rou
read `references/original-authoring/route.md`. This is the route whatever shape the request takes —
"make me a 45-second ranking video", "a talking-head explainer about X", an ad for a product, a
written script to produce, a topic and a duration, a format named on its own, or the same idea in
- any language — and **a description with no video path attached is this route** even when no verb is
+ any language — and **a description with no video attached is this route** even when no verb is
given at all. What it is for, who is in it and what it says are the author's; the working
directory, the project location, the packages and the generators are yours to decide rather than to
ask for.
diff --git a/.agents/skills/hypit/references/environment.md b/.agents/skills/hypit/references/environment.md
index ea215f01..2bd2d454 100644
--- a/.agents/skills/hypit/references/environment.md
+++ b/.agents/skills/hypit/references/environment.md
@@ -83,6 +83,9 @@ on Windows. Credentials load from a project's `.env` in the same shell that runs
`set -a && . ./.env && set +a`.
`uv` is required only when the selected Runtime Profile uses a managed Python program such as
WhisperX or OpenCV.
+Reconstructing a video given as a link rather than as a file needs `uv` too: `yt-dlp` is pinned under
+`services/yt-dlp` and run from there, so the version is the repository's rather than the machine's.
+`prepare_reference` names what is missing when a link is passed without it.
When the Runtime Profile selects the local WhisperX Endpoint, verify that the service answered its
health probe before `prepare_reference` or a Build, since a first start can spend several minutes
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index 67eb76d2..f22306e6 100644
--- a/.agents/skills/hypit/references/reconstruction/route.md
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -34,9 +34,13 @@ person has to invent the prompt again. `media:Image` is for material the author
Reference observation is part of the work and is expected to cost what it costs.
-## The video path is the whole request
+## The video is the whole request
-The author gives one thing: the path to a video. The working directory, the project name, which
+The author gives one thing: a video, as a path to a file or as a link to one. A link — TikTok,
+YouTube, Instagram, Bilibili — is fetched by `prepare_reference` before anything else runs, with the
+`yt-dlp` pinned under `services/yt-dlp` and run through `uv`, and every step after that reads the downloaded file without knowing it was ever a link. The
+download is cached by the link, so a route restarted after an interruption reaches the same bytes and
+therefore the same reference rather than paying for its observations twice. The working directory, the project name, which
packages to use and where the result goes are yours to decide. Ask the author about the video and
nothing else — what it is for, who is in it, what it should say. Those answers describe the result
they want; record them and apply them at step 23. Never interrupt to ask which generator, which
@@ -124,9 +128,12 @@ inside it. This is instant and may run before or during the sweep.
### 8. Prepare the reference
```bash
-hypit-reference-video-tools prepare_reference --video-path <path> --observer gemini|agent
+hypit-reference-video-tools prepare_reference --video-path <path or link> --observer gemini|agent
```
+`--video-path` takes a link as readily as a path. The result names the link it fetched under
+`source_url`, which is the only record of which video was reconstructed once the bytes are on disk.
+
Verify the WhisperX service answered its health probe before running this — a first start can spend
several minutes loading the model. `../environment.md` says how; `../host-setup.md` covers the
failure branches.
diff --git a/packages/reference-video-tools/package.json b/packages/reference-video-tools/package.json
index f73b60e5..6ac99c86 100644
--- a/packages/reference-video-tools/package.json
+++ b/packages/reference-video-tools/package.json
@@ -31,6 +31,7 @@
"@hypit/svs": "workspace:*",
"@hypit/video-cli": "workspace:*",
"@hypit/whisperx": "workspace:*",
+ "@hypit/yt-dlp": "workspace:*",
"tsx": "4.21.0"
},
"devDependencies": {
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index af1ff952..40012d5a 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -26,7 +26,7 @@ function usage(): string {
return [
"Usage:",
" hypit-reference-video-tools list_svml_packages",
- " hypit-reference-video-tools prepare_reference --video-path <path> [--observer gemini|agent] [--redo media|transcript|people|voices|systems|places|all]",
+ " hypit-reference-video-tools prepare_reference --video-path <path or link> [--observer gemini|agent] [--redo media|transcript|people|voices|systems|places|all]",
" hypit-reference-video-tools observe_reference --reference-id <id> [--shot-id <id> ...] [--reobserve]",
" hypit-reference-video-tools observe_reference --reference-id <id> --shot-id <id> [--shot-id <id> ...] --question <text>",
" hypit-reference-video-tools observe_reference --reference-id <id> --batch <questions.json>",
@@ -154,6 +154,11 @@ function usage(): string {
"decides — an uncovered stretch, a Frame reaching past the Canvas, a `playback` left at its default.",
"Pick the command that matches the route; neither infers which one you meant.",
"",
+ "--video-path takes a link as readily as a path. A TikTok, YouTube, Instagram or Bilibili URL is",
+ "fetched with yt-dlp before anything else runs, cached by the link so a restarted route reaches the",
+ "same bytes and therefore the same reference, and reported back as `source_url`. Everything after",
+ "the download reads the file without knowing it was ever a link.",
+ "",
"--observer picks who reads the reference, once per reference. `gemini` uploads video to Vertex and",
"needs GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS_JSON. `agent` needs no credentials: it",
"returns each observation as a task carrying its prompt and one tiled picture per shot, which the",
diff --git a/packages/reference-video-tools/src/media.ts b/packages/reference-video-tools/src/media.ts
index d701412f..4febf751 100644
--- a/packages/reference-video-tools/src/media.ts
+++ b/packages/reference-video-tools/src/media.ts
@@ -167,7 +167,10 @@ export async function cutClip(source: string, start: number, seconds: number, ta
/** One frame of a video, at the second asked for. */
export async function cutFrame(source: string, at: number, target: string): Promise<string> {
- return await extract(source, ["-i", source, "-ss", String(round(at)), "-frames:v", "1", "-q:v", "3"], target);
+ // `-pix_fmt yuvj420p` because JPEG is a full-range format and the encoder refuses full-range YUV
+ // input without being told which one it is writing. Video from the web is routinely full-range, so
+ // leaving it out refuses the still with `Non full-range YUV is non-standard` and writes nothing.
+ return await extract(source, ["-i", source, "-ss", String(round(at)), "-frames:v", "1", "-pix_fmt", "yuvj420p", "-q:v", "3"], target);
}
/**
@@ -186,7 +189,7 @@ export async function shotTile(clip: string, duration: number, target: string, c
await command("ffmpeg", [
"-hide_banner", "-loglevel", "error", "-y", "-i", clip,
"-vf", `fps=${rate},scale='min(${Math.round(cellWidth)},iw)':-2,tile=layout=${TILE_COLUMNS}x${rows}:padding=8:margin=8:color=black`,
- "-frames:v", "1", "-q:v", "3", target,
+ "-frames:v", "1", "-pix_fmt", "yuvj420p", "-q:v", "3", target,
], 300_000);
return target;
}
@@ -208,8 +211,8 @@ export async function prepareMedia(videoPath: string, root: string, duration: nu
// `-ss` goes after `-i`: seeking the output decodes from the start and lands on the frame asked
// for, where seeking the input lands on the keyframe before it.
await extract(videoPath, ["-i", videoPath, "-ss", String(bound.start), "-t", String(Math.max(0.1, bound.end - bound.start)), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "96k", "-movflags", "+faststart"], clip);
- await extract(videoPath, ["-i", videoPath, "-ss", String(bound.start + (bound.end - bound.start) / 2), "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-q:v", "3"], join(shotDir, `${id}-representative.jpg`));
- await extract(videoPath, ["-sseof", "-0.1", "-i", clip, "-update", "1", "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-q:v", "3"], join(shotDir, `${id}-tail.jpg`));
+ await extract(videoPath, ["-i", videoPath, "-ss", String(bound.start + (bound.end - bound.start) / 2), "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-pix_fmt", "yuvj420p", "-q:v", "3"], join(shotDir, `${id}-representative.jpg`));
+ await extract(videoPath, ["-sseof", "-0.1", "-i", clip, "-update", "1", "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-pix_fmt", "yuvj420p", "-q:v", "3"], join(shotDir, `${id}-tail.jpg`));
// Only the observer that reads pictures has anything to read them from, and building a tile per
// shot is a decode per shot. The other observer is handed the clip itself.
if (tiles) await shotTile(clip, bound.end - bound.start, join(shotDir, `${id}-frames.jpg`));
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index 084104ae..d8511a88 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -21,6 +21,7 @@ import { videoCliDistribution } from "@hypit/video-cli";
import { authorSource, invokedFrom, referenceRoot, referenceWords, renderElement, renderPreviews, spokenRange, standInSidecarPath } from "./authoring.js";
import type { RenderElementInput, RenderPreviewsInput, SpokenRange, StandInFocus, StandInSidecar } from "./authoring.js";
import { writePlaceholder } from "./placeholder.js";
+import { downloadReferenceVideo, isReferenceUrl } from "@hypit/yt-dlp";
import { authoringCheck, previewCheck, reviewLogPath } from "./checks.js";
import type { AuthoringCheckInput, PreviewCheckInput, ReconstructionCheckInput } from "./checks.js";
import {
@@ -1074,7 +1075,12 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
async prepare_reference(input): Promise<PrepareResult> {
assert(input.redo === undefined || input.redo === "media" || input.redo === "transcript" || input.redo === "people" || input.redo === "voices" || input.redo === "systems" || input.redo === "places" || input.redo === "all", "redo must be one of: media, transcript, people, voices, systems, places, all");
- const videoPath = resolve(input.video_path);
+ // A reference given as a link becomes a file before anything else runs, and everything after
+ // this reads the file without learning where it came from.
+ const fetched = isReferenceUrl(input.video_path)
+ ? await downloadReferenceVideo(input.video_path.trim(), join(referenceRoot(), "downloads"))
+ : undefined;
+ const videoPath = fetched?.path ?? resolve(input.video_path);
const file = await stat(videoPath).catch(() => undefined);
assert(file?.isFile(), `video_path is not a file: ${videoPath}`);
const reference = await referenceId(videoPath);
@@ -1170,6 +1176,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
persistent_systems: systems,
places,
observer,
+ ...(fetched === undefined ? {} : { source_url: fetched.url, downloaded: !fetched.cached }),
pending_observations: pending,
};
},
diff --git a/packages/yt-dlp/package.json b/packages/yt-dlp/package.json
new file mode 100644
index 00000000..79ae4c44
--- /dev/null
+++ b/packages/yt-dlp/package.json
@@ -0,0 +1,10 @@
+{
+ "name": "@hypit/yt-dlp",
+ "version": "0.0.0-dev",
+ "license": "SEE LICENSE IN LICENSE",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ }
+}
diff --git a/packages/yt-dlp/src/download.ts b/packages/yt-dlp/src/download.ts
new file mode 100644
index 00000000..15faf1b5
--- /dev/null
+++ b/packages/yt-dlp/src/download.ts
@@ -0,0 +1,133 @@
+/**
+ * Fetch a reference video that lives at a link rather than on disk.
+ *
+ * A reconstruction starts from a video, and most of the videos anybody wants to reconstruct are on
+ * TikTok, YouTube, Instagram or Bilibili rather than in a folder. `yt-dlp` is what turns one into a
+ * file; everything after that — shot detection, the transcript, the observations, the comparison —
+ * reads the file and never learns where it came from.
+ *
+ * The download is cached by the link. Re-running a route that was interrupted, or preparing the same
+ * reference twice, reaches the same bytes at the same path, which is what keeps the reference id
+ * stable: it is derived from the file's path, size and modification time, so a second download to a
+ * fresh temporary directory would present the same video as a different reference and throw away
+ * every observation already paid for.
+ *
+ * The tool is a pinned Python dependency under `services/yt-dlp`, reached through `uv`, and not a
+ * binary the machine happens to carry. `yt-dlp` releases constantly because it is chasing sites that
+ * keep changing, so an unpinned copy makes the same link fetch differently on two machines — which
+ * would make a reconstruction unreproducible for a reason that has nothing to do with the video. This
+ * is the same shape WhisperX and OpenCV already use for their Python programs.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** What a downloaded reference is, once it is a file like any other. */
+export type DownloadedReference = {
+ readonly path: string;
+ readonly url: string;
+ /** True when the bytes were already on disk from an earlier run. */
+ readonly cached: boolean;
+};
+
+/**
+ * Whether this is a link to fetch rather than a path to open.
+ *
+ * Only `http` and `https`. A Windows path opens as a URL with a single-letter scheme (`c:\clip.mp4`
+ * parses with protocol `c:`), and a route that read that as a link would hand the whole path to
+ * `yt-dlp` and report a network failure for a file sitting on the disk.
+ */
+export function isReferenceUrl(value: string): boolean {
+ try {
+ const parsed = new URL(value.trim());
+ return parsed.protocol === "http:" || parsed.protocol === "https:";
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * The uv project holding the pinned `yt-dlp`.
+ *
+ * Found by walking up from this module rather than from the working directory, which is wherever the
+ * author happened to run the command from and is routinely outside the tree.
+ */
+function serviceProject(): string {
+ let directory = dirname(fileURLToPath(import.meta.url));
+ while (true) {
+ const candidate = join(directory, "services", "yt-dlp", "pyproject.toml");
+ if (existsSync(candidate)) return dirname(candidate);
+ const parent = dirname(directory);
+ if (parent === directory) {
+ throw new Error("no services/yt-dlp project above this module; the Distribution is incomplete");
+ }
+ directory = parent;
+ }
+}
+
+/** Where one link's download lives, keyed by the link so a second run finds the first one's bytes. */
+function cacheDirectory(root: string, url: string): string {
+ return join(root, createHash("sha256").update(url).digest("hex").slice(0, 16));
+}
+
+async function existingDownload(directory: string): Promise<string | undefined> {
+ const entries = await readdir(directory).catch(() => []);
+ // `yt-dlp` writes `.part` files while it works, so a directory holding only those is an interrupted
+ // download rather than a finished one, and it is fetched again.
+ const finished = entries.filter((name) => !name.endsWith(".part") && /\.(mp4|mkv|webm|mov)$/iu.test(name));
+ return finished.length === 0 ? undefined : join(directory, finished.sort()[0]!);
+}
+
+/**
+ * Fetch one video and return the file it landed in.
+ *
+ * The format is asked for as a single muxed file rather than the best video and audio separately,
+ * because everything downstream probes one file for both streams. `--no-playlist` keeps a link that
+ * happens to sit inside a playlist from fetching the playlist.
+ */
+export async function downloadReferenceVideo(url: string, root: string): Promise<DownloadedReference> {
+ const directory = cacheDirectory(root, url);
+ await mkdir(directory, { recursive: true });
+
+ const held = await existingDownload(directory);
+ if (held !== undefined) return { path: held, url, cached: true };
+
+ const result = spawnSync("uv", [
+ "run", "--project", serviceProject(), "--frozen", "yt-dlp",
+ "--no-playlist",
+ "--no-progress",
+ "--quiet",
+ // Video and audio together, muxed. Sites serve the two separately now, so asking for the best
+ // single file resolves to a video-only stream — and a reference with no audio has no transcript,
+ // which is half of what the observers read. ffmpeg does the muxing and is already required by
+ // everything that opens this file next.
+ "--format", "bv*+ba/b",
+ "--merge-output-format", "mp4",
+ // Prefer H.264 at 1080 rather than requiring either. Nothing downstream reads above 720 — the
+ // analysis video, the representative frames and the tails are all `scale='min(720,iw)'` — so
+ // fetching a 4K source spends several hundred megabytes to make a 720p working copy. A
+ // `height<=1080` filter would refuse outright when a link offers nothing under the bound, which
+ // is a download that fails rather than one that is merely larger; a sort expresses the preference
+ // and still resolves to whatever the link actually has.
+ "--format-sort", "res:1080,vcodec:h264",
+ "--output", join(directory, "%(id)s.%(ext)s"),
+ url,
+ ], { encoding: "utf8", windowsHide: true, timeout: 900_000 });
+
+ if (result.error !== undefined && (result.error as NodeJS.ErrnoException).code === "ENOENT") {
+ throw new Error(
+ "uv is not installed, and a reference given as a link is fetched by a pinned yt-dlp that uv "
+ + "installs. It is the same tool the WhisperX and OpenCV programs need. Install it "
+ + "(https://docs.astral.sh/uv/), or download the video yourself and pass the path instead.");
+ }
+ if (result.status !== 0) {
+ throw new Error(`yt-dlp could not fetch ${url}: ${(result.stderr ?? "").trim().slice(-2000)}`);
+ }
+
+ const written = await existingDownload(directory);
+ if (written === undefined) throw new Error(`yt-dlp reported success but wrote no video for ${url}`);
+ return { path: written, url, cached: false };
+}
diff --git a/packages/yt-dlp/src/index.ts b/packages/yt-dlp/src/index.ts
new file mode 100644
index 00000000..f659c907
--- /dev/null
+++ b/packages/yt-dlp/src/index.ts
@@ -0,0 +1 @@
+export { downloadReferenceVideo, isReferenceUrl } from "./download.js";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 28c67d02..b1e109d5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2183,6 +2183,9 @@ importers:
'@hypit/whisperx':
specifier: workspace:*
version: link:../whisperx
+ '@hypit/yt-dlp':
+ specifier: workspace:*
+ version: link:../yt-dlp
tsx:
specifier: 4.21.0
version: 4.21.0
@@ -3109,6 +3112,8 @@ importers:
specifier: workspace:*
version: link:../workspace
+ packages/yt-dlp: {}
+
services/image-opencv: {}
services/media-lambda:
diff --git a/services/yt-dlp/README.md b/services/yt-dlp/README.md
new file mode 100644
index 00000000..18ad142e
--- /dev/null
+++ b/services/yt-dlp/README.md
@@ -0,0 +1,17 @@
+# Pinned yt-dlp
+
+A reconstruction starts from a video, and most of the videos worth reconstructing are at a link
+rather than in a folder. This project holds the one dependency that turns one into a file.
+
+The version is pinned and locked. `yt-dlp` releases constantly, because it is chasing sites that keep
+changing, and an unpinned copy means two machines fetch the same link differently — which makes a
+reconstruction unreproducible for a reason that has nothing to do with the video.
+
+It is invoked one command at a time rather than run as a service:
+
+```bash
+uv run --project services/yt-dlp --frozen yt-dlp --version
+```
+
+`packages/yt-dlp` is the Node side that calls it, decides whether a reference is a link at all, and
+caches what it fetched.
diff --git a/services/yt-dlp/package.json b/services/yt-dlp/package.json
new file mode 100644
index 00000000..2357bdb9
--- /dev/null
+++ b/services/yt-dlp/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@hypit/yt-dlp-service-runtime",
+ "version": "0.1.0",
+ "license": "SEE LICENSE IN LICENSE",
+ "type": "module",
+ "exports": {
+ "./pyproject.toml": "./pyproject.toml"
+ },
+ "files": [
+ "pyproject.toml",
+ "uv.lock",
+ "README.md"
+ ]
+}
diff --git a/services/yt-dlp/pyproject.toml b/services/yt-dlp/pyproject.toml
new file mode 100644
index 00000000..e1732aa9
--- /dev/null
+++ b/services/yt-dlp/pyproject.toml
@@ -0,0 +1,13 @@
+[project]
+name = "hypit-yt-dlp"
+version = "0.1.0"
+description = "Pinned yt-dlp, for fetching a reference video that lives at a link"
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = { text = "Hypit Open Source License (Apache-2.0 with additional conditions); see LICENSE at the repository root" }
+dependencies = [
+ "yt-dlp==2026.8.19",
+]
+
+[tool.uv]
+package = false
diff --git a/services/yt-dlp/uv.lock b/services/yt-dlp/uv.lock
new file mode 100644
index 00000000..d00b87dd
--- /dev/null
+++ b/services/yt-dlp/uv.lock
@@ -0,0 +1,23 @@
+version = 1
+revision = 3
+requires-python = ">=3.10, <3.14"
+
+[[package]]
+name = "hypit-yt-dlp"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+ { name = "yt-dlp" },
+]
+
+[package.metadata]
+requires-dist = [{ name = "yt-dlp", specifier = "==2026.8.19" }]
+
+[[package]]
+name = "yt-dlp"
+version = "2026.8.19"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1e/e0/832fa4ca334b766a06933a196066edc3dba37cdb6f14cd98d59bcc69a4b4/yt_dlp-2026.8.19.tar.gz", hash = "sha256:9e213e48cea35c66b378e4447903f118f6392a5fa380a2b6d7070ec86f4e0af1", size = 3052025, upload-time = "2026-08-19T23:48:59.291Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/69/b2/8cd1613f56eed7ceb64fbd4df3f1c01246bfb098e6f398228bafda22b80b/yt_dlp-2026.8.19-py3-none-any.whl", hash = "sha256:1d57897e94c6665a0a6f9bc54b34e584284e32c034ffab3a7df25d8f7b24eedf", size = 3185533, upload-time = "2026-08-19T23:48:56.925Z" },
+]