Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -119,6 +123,7 @@ npx pixelvault-cli upload build-output.png
| `describe <id>` | Write an AI description (alt text, caption, OCR, tags) for an image you already uploaded |
| `optimize <files...>` | Compress images locally — no account needed (resize, convert, strip metadata; never writes a bigger file) |
| `optimize-video <id>` | Preserve a hosted MP4 and create a social-ready H.264/AAC fast-start copy |
| `enrich-video <id>` | Generate transcript and storyboard artifacts for an owned hosted MP4 |
| `get <id>` | Get an image's URL/metadata, or download it (optionally transformed) |
| `meta <id>` | Replace an image's custom metadata (`--meta k=v`, `--metadata '<json>'`, or `--clear`) |
| `delete <id>` | Delete an image |
Expand Down Expand Up @@ -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
Expand Down
61 changes: 61 additions & 0 deletions src/commands/enrich-video.ts
Original file line number Diff line number Diff line change
@@ -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.`,
);
}
},
});
1 change: 1 addition & 0 deletions src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
20 changes: 20 additions & 0 deletions src/lib/video-enrichment.ts
Original file line number Diff line number Diff line change
@@ -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<VideoData> {
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;
}
30 changes: 30 additions & 0 deletions src/lib/video-upload.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -38,6 +67,7 @@ export interface VideoData {
social_compatible: boolean | null;
compatibility_warnings: { code: string; message: string }[];
social_optimization: VideoSocialOptimization;
enrichment: VideoEnrichment;
}

interface UploadSession {
Expand Down
120 changes: 120 additions & 0 deletions tests/commands/enrich-video.test.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown>) {
const { default: command } = await import("../../src/commands/enrich-video.js");
const runnable = command as unknown as {
run(context: { args: Record<string, unknown> }): Promise<void>;
};
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");
});
});
Loading