From 1a86e66f532624d098c8e2f2b12bed4175840e19 Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Mon, 16 Nov 2026 09:03:45 +0100 Subject: [PATCH] feat: add video enrichment command --- README.md | 21 +++++ src/commands/enrich-video.ts | 61 ++++++++++++++ src/index.ts | 1 + src/lib/video-enrichment.ts | 20 +++++ src/lib/video-upload.ts | 30 +++++++ tests/commands/enrich-video.test.ts | 120 ++++++++++++++++++++++++++++ 6 files changed, 253 insertions(+) create mode 100644 src/commands/enrich-video.ts create mode 100644 src/lib/video-enrichment.ts create mode 100644 tests/commands/enrich-video.test.ts diff --git a/README.md b/README.md index d92a9f4..1676085 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,9 @@ pixelvault upload demo.mp4 --social # Convert an existing hosted video pixelvault optimize-video vid_xyz +# Generate transcript + storyboard artifacts for an existing hosted video +pixelvault enrich-video vid_xyz + # List your images pixelvault list @@ -84,6 +87,7 @@ The CLI is designed for AI coding agents. Output contract: - `upload` prints **only the URL** to stdout for images, PDFs, and MP4 videos. PDFs are served as forced downloads and do not support image transforms. Add `--optimized` for the smaller WebP/AVIF image variant; it falls back to the original URL for SVG, GIF, PDF, and private images - `upload` streams local MP4 files and automatically switches to multipart upload above 100 MB. It also accepts public MP4 URLs and has PixelVault import them directly. `--private [--expires 12h]` returns signed video and poster URLs. `--social` requests a separate H.264/AAC fast-start copy, waits for it, and prints the post-ready URL while preserving the original; `--json` returns both `original_url` and `social_ready_url`. Every video response includes duration, dimensions, codecs, fast-start status, and social-compatibility warnings. Video limits: Free 25 MB, Starter 100 MB, Pro 250 MB - `optimize-video` converts an existing upload, waits for the derived social-ready URL, and prints only that URL; `--no-wait` enqueues and returns, while `--json` returns the full state +- `enrich-video` generates plain-text, WebVTT, timestamped JSON, and storyboard artifacts for an owned upload; stdout is the enrichment JSON, `--no-wait` enqueues, and `--json` returns the full video state - Image and PDF uploads support `--idempotency-key` and `--dedupe`; folder, image optimization, reuse, metadata, and AI-description options are rejected for MP4 files and URLs - `list` outputs one URL per line - `meta` prints the stored metadata as JSON @@ -119,6 +123,7 @@ npx pixelvault-cli upload build-output.png | `describe ` | Write an AI description (alt text, caption, OCR, tags) for an image you already uploaded | | `optimize ` | Compress images locally — no account needed (resize, convert, strip metadata; never writes a bigger file) | | `optimize-video ` | Preserve a hosted MP4 and create a social-ready H.264/AAC fast-start copy | +| `enrich-video ` | Generate transcript and storyboard artifacts for an owned hosted MP4 | | `get ` | Get an image's URL/metadata, or download it (optionally transformed) | | `meta ` | Replace an image's custom metadata (`--meta k=v`, `--metadata ''`, or `--clear`) | | `delete ` | Delete an image | @@ -174,6 +179,22 @@ an already-compatible original is returned unchanged, a running job is reused, and a completed derivative is returned without another conversion. Failed jobs refund their reserved seconds. +### Transcript and Storyboard Enrichment + +```bash +pixelvault enrich-video vid_xyz # wait; print enrichment JSON +pixelvault enrich-video vid_xyz --no-wait # enqueue and return pending state +pixelvault enrich-video vid_xyz --json # full video response +``` + +Enrichment generates a plain-text transcript, timed WebVTT captions, +timestamped JSON segments, a storyboard index, and bounded JPEG sheets. Silent +videos skip the transcript but still receive a storyboard. Sources must be 1 +second through 10 minutes and at most 100 MB. Monthly source-minute allowances +are 2 on Free, 30 on Starter, and 120 on Pro. The remaining allowance must cover +the full source duration. Artifacts inherit the video's public or private +visibility and are removed with the source. + ### Generate Options ```bash diff --git a/src/commands/enrich-video.ts b/src/commands/enrich-video.ts new file mode 100644 index 0000000..ba58876 --- /dev/null +++ b/src/commands/enrich-video.ts @@ -0,0 +1,61 @@ +import { defineCommand } from "citty"; +import { apiRequest } from "../lib/client.js"; +import { requireApiKey } from "../lib/config.js"; +import { CliError } from "../lib/errors.js"; +import { jsonOut, stderr } from "../lib/output.js"; +import type { VideoData } from "../lib/video-upload.js"; +import { waitForVideoEnrichment } from "../lib/video-enrichment.js"; + +export default defineCommand({ + meta: { + name: "enrich-video", + description: "Generate transcript and storyboard artifacts for an owned MP4", + }, + args: { + id: { + type: "positional", + description: "Video ID (e.g. vid_abc123)", + required: true, + }, + wait: { + type: "boolean", + description: "Wait up to five minutes for enrichment to finish", + default: true, + }, + json: { + type: "boolean", + description: "Output the full video response instead of only enrichment", + default: false, + }, + }, + async run({ args }) { + const apiKey = requireApiKey(); + const id = String(args.id); + let { data } = await apiRequest<{ data: VideoData }>({ + method: "POST", + path: `/v1/videos/${encodeURIComponent(id)}/enrich`, + auth: apiKey, + }); + + if (args.wait) data = await waitForVideoEnrichment(data, apiKey); + if (data.enrichment.status === "failed") { + throw new CliError( + data.enrichment.error?.message ?? "Video enrichment failed. Try again.", + ); + } + + if (args.json) { + jsonOut(data); + return; + } + + jsonOut(data.enrichment); + if (data.enrichment.status === "complete") { + stderr("Transcript and storyboard generated. The original is unchanged."); + } else { + stderr( + `Enrichment ${data.enrichment.status}. Run pixelvault enrich-video ${id} later to check again.`, + ); + } + }, +}); diff --git a/src/index.ts b/src/index.ts index c0fb1b1..98b3266 100644 --- a/src/index.ts +++ b/src/index.ts @@ -18,6 +18,7 @@ const main = defineCommand({ describe: () => import("./commands/describe.js").then((m) => m.default), optimize: () => import("./commands/optimize.js").then((m) => m.default), "optimize-video": () => import("./commands/optimize-video.js").then((m) => m.default), + "enrich-video": () => import("./commands/enrich-video.js").then((m) => m.default), get: () => import("./commands/get.js").then((m) => m.default), meta: () => import("./commands/meta.js").then((m) => m.default), delete: () => import("./commands/delete.js").then((m) => m.default), diff --git a/src/lib/video-enrichment.ts b/src/lib/video-enrichment.ts new file mode 100644 index 0000000..9a99375 --- /dev/null +++ b/src/lib/video-enrichment.ts @@ -0,0 +1,20 @@ +import { setTimeout as delay } from "node:timers/promises"; +import { getVideo } from "./video-optimization.js"; +import type { VideoData } from "./video-upload.js"; + +const POLL_INTERVAL_MS = 2_000; +const WAIT_TIMEOUT_MS = 5 * 60 * 1_000; + +export async function waitForVideoEnrichment( + initial: VideoData, + apiKey: string, +): Promise { + let video = initial; + const deadline = Date.now() + WAIT_TIMEOUT_MS; + while (video.enrichment.status === "pending" || video.enrichment.status === "processing") { + if (Date.now() >= deadline) return video; + await delay(POLL_INTERVAL_MS); + video = await getVideo(video.id, apiKey); + } + return video; +} diff --git a/src/lib/video-upload.ts b/src/lib/video-upload.ts index 7a9abab..94e345f 100644 --- a/src/lib/video-upload.ts +++ b/src/lib/video-upload.ts @@ -15,6 +15,35 @@ export interface VideoSocialOptimization { error?: { code: string; message: string }; } +export interface VideoEnrichment { + status: "not_requested" | "pending" | "processing" | "complete" | "failed"; + requested_at?: string; + completed_at?: string | null; + transcript?: { + status: "complete" | "skipped"; + text_url?: string; + vtt_url?: string; + segments_url?: string; + language?: string | null; + languages?: string[]; + model?: string | null; + segment_count?: number; + reason?: "no_audio"; + }; + storyboard?: { + status: "complete"; + index_url: string; + frame_count: number; + sheets: { + url: string; + start_seconds: number; + end_seconds: number; + frame_count: number; + }[]; + } | null; + error?: { code: string; message: string }; +} + export interface VideoData { id: string; kind: "video"; @@ -38,6 +67,7 @@ export interface VideoData { social_compatible: boolean | null; compatibility_warnings: { code: string; message: string }[]; social_optimization: VideoSocialOptimization; + enrichment: VideoEnrichment; } interface UploadSession { diff --git a/tests/commands/enrich-video.test.ts b/tests/commands/enrich-video.test.ts new file mode 100644 index 0000000..d9bee31 --- /dev/null +++ b/tests/commands/enrich-video.test.ts @@ -0,0 +1,120 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +vi.mock("../../src/lib/config.js", () => ({ + requireApiKey: () => "pv_live_test", + getApiUrl: () => "https://api.test.pixelvault.dev", +})); + +const originalFetch = globalThis.fetch; +afterEach(() => { + globalThis.fetch = originalFetch; + vi.restoreAllMocks(); +}); + +const video = { + id: "vid_1", + kind: "video", + url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + original_url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + visibility: "public", + mime_type: "video/mp4", + size: 1_000, + filename: "clip.mp4", + created_at: "2026-01-01T00:00:00.000Z", + width: 640, + height: 360, + duration_seconds: 5, + video_codec: "h264", + audio_codec: "aac", + has_audio: true, + fast_start: true, + social_compatible: true, + compatibility_warnings: [], + social_optimization: { preset: "social", status: "not_requested" }, +}; + +function fakeApi(body: unknown) { + const calls: { url: string; init: RequestInit }[] = []; + globalThis.fetch = vi.fn(async (url: string, init: RequestInit) => { + calls.push({ url: String(url), init }); + return { ok: true, json: async () => body }; + }) as unknown as typeof fetch; + const out = vi.spyOn(process.stdout, "write").mockImplementation(() => true); + const err = vi.spyOn(process.stderr, "write").mockImplementation(() => true); + return { + calls, + stdout: () => out.mock.calls.map((call) => String(call[0])).join(""), + stderr: () => err.mock.calls.map((call) => String(call[0])).join(""), + }; +} + +async function run(args: Record) { + const { default: command } = await import("../../src/commands/enrich-video.js"); + const runnable = command as unknown as { + run(context: { args: Record }): Promise; + }; + await runnable.run({ + args: { id: "vid_1", wait: false, json: false, ...args }, + }); +} + +describe("enrich-video command", () => { + it("prints completed artifact metadata as JSON", async () => { + const api = fakeApi({ + data: { + ...video, + enrichment: { + status: "complete", + transcript: { + status: "complete", + vtt_url: "https://img.pixelvault.dev/proj_1/vid_1.transcript.vtt", + }, + storyboard: { + status: "complete", + index_url: "https://img.pixelvault.dev/proj_1/vid_1.storyboard.json", + frame_count: 16, + sheets: [], + }, + }, + }, + }); + + await run({}); + + expect(api.calls[0].url).toBe( + "https://api.test.pixelvault.dev/v1/videos/vid_1/enrich", + ); + expect(api.calls[0].init.method).toBe("POST"); + expect(JSON.parse(api.stdout())).toMatchObject({ + status: "complete", + transcript: { vtt_url: expect.stringContaining("transcript.vtt") }, + storyboard: { index_url: expect.stringContaining("storyboard.json") }, + }); + expect(api.stderr()).toContain("original is unchanged"); + }); + + it("reports a queued job", async () => { + const api = fakeApi({ + data: { ...video, enrichment: { status: "pending" } }, + }); + + await run({}); + + expect(JSON.parse(api.stdout())).toEqual({ status: "pending" }); + expect(api.stderr()).toContain("Enrichment pending"); + }); + + it("surfaces a failed job message", async () => { + fakeApi({ + data: { + ...video, + enrichment: { + status: "failed", + error: { code: "enrichment_failed", message: "Transcription failed." }, + }, + }, + }); + + await expect(run({})).rejects.toThrow("Transcription failed"); + }); +});