@mevdragon/vidfarm-devcli 0.9.0 → 0.10.0

package/README.md

@@ -50,7 +50,25 @@ Everything runs locally (`RECORDS_DRIVER=local`, `STORAGE_DRIVER=local`), includ
 
 Flags: `--port` (default 3000), `--dir` (default `./.vidfarm-local`), `--key` (bootstrap/browser key, or `VIDFARM_API_KEY`), `--fork <id>`, `--no-open`. `vidfarm <template_id>` is an alias for `serve <template_id>`.
 
-Beyond the local editor, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".
+Beyond the local editor, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, `clips` (see below), plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".
+
+## Clip hunting: `vidfarm clips`
+
+Mine a long-form video (podcast, VOD, webinar, YouTube URL) into tagged, searchable short clips — **local-first**: local ffmpeg for compute and your local `claude`/`codex` CLI subscription for scene evaluation, so it works with zero API keys. Provider keys (`--provider gemini|openai|openrouter`) are the fallback; `--cloud` is the explicit backup that runs the hunt on the deployed pipeline instead (bills AWS compute only — the AI runs on your saved BYOK keys, and the uploaded original auto-deletes from your temp folder after 30 days).
+
+```bash
+# hunt only 12:30–15:45, ~30s clips (soft 20–40s band), cropped vertical, no on-screen text
+vidfarm clips scan ./podcast.mp4 --range "12:30-15:45" --duration 30 --aspect vertical --no-text \
+  --prompt "guest reaction moments"
+
+vidfarm clips search "confused reaction after reading a message"
+vidfarm clips export <clip-ids…> --to ./picks
+
+# backup: run it in the cloud (or hunt a URL without downloading anything)
+vidfarm clips scan --cloud --url "https://youtube.com/watch?v=…" --duration 30 --aspect 9:16
+```
+
+Duration is a **soft range** (10→5–20s, 30→20–40s), `--range` means only those windows are decoded (the cost saver on long videos), and `--no-text` selects text-free scenes — caption *removal* (GhostCut) stays a per-finished-clip primitive, never a long-form pass. Run `vidfarm clips --help` for everything (`list`, `match`, `preset`, `sources`, `export`).
 
 ### Crash telemetry & opt-out
 

package/SKILL.director.md

@@ -208,6 +208,58 @@ Use it whenever you need to know what the video says or shows: writing/translati
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
 - **Desktop agents (Claude Code / Codex)**: fetch the `video-context.json` route directly (e.g. `vidfarm api GET /api/v1/compositions/<forkId>/video-context.json`) to ground edits in what the video says and shows.
 
+## Clip hunting (long-form → short-form clips)
+
+Mine a **long-form** video (podcast, stream VOD, webinar, any YouTube/TikTok/IG/X URL, or an upload) into a library of tagged, searchable **short clips**. This is the `/clips` surface — browse it at `https://vidfarm.cc/clips` (the Library page's "Finished / Clips" toggle).
+
+**Start a hunt** — `POST /clips/scan` (async: returns `202 { scan_id }` immediately):
+
+```jsonc
+{
+  // ONE source (pick one):
+  "source_url": "https://youtube.com/watch?v=…",   // downloaded into your temp folder first
+  "temp_file_id": "…",                              // a video you uploaded to temporary-files
+  "attachment_id": "…",                             // a video already in My Files
+  "s3_key": "…" ,                                   // an already-staged object
+
+  // What to hunt for — free text; inline hints are parsed too
+  "prompt": "people holding food up to their face, no text on screen",
+
+  // Hunt controls (all optional; also expressible inline in the prompt):
+  "ranges": ["12:30-15:45", "20:00-22:10"],  // ONLY hunt these source windows — big cost saver on long videos
+  "target_duration_sec": 30,                 // SOFT length band, not a hard cut: 10→5-20s, 30→20-40s, 60→40-80s, 120→80-160s
+  "aspect": "9:16",                          // crop every clip: 9:16 | 16:9 | 4:3 | 1:1 (synonyms: vertical/portrait, horizontal/landscape, square)
+  "crop_focus": "center",                    // center | top | bottom | left | right (top biases toward faces)
+  "avoid_text": true,                        // prefer scenes WITHOUT burned-in captions/on-screen text — a scene-SELECTION filter, NEVER GhostCut on the source
+  "tracer": "my-campaign"                    // rolls up all the hunt's billing/observability events
+}
+```
+
+- **Poll** `GET /clips/scan/:scanId` until the source `status` is `complete` (or `failed` — crashed pipelines are reconciled to `failed`, pollers never spin).
+- **Results**: `GET /clips/feed?source=<source_video_id>` (or the whole library), hybrid search via `POST /clips/search` `{ query: "someone looks confused" }`, per-clip download at `GET /clips/:clipId/download`. Clips carry taxonomy tags, a description, a transcript, an `aspect` field when cropped, and (with a gemini/openai key) a semantic embedding.
+- **Billing** — **AWS compute only** (`clip_scan_lambda` GB-seconds + Step Functions transitions, a fraction of a cent for typical hunts; the 202 response includes a `compute_estimate`). The AI tagging/refine runs on **your saved provider key (BYOK)** and is never wallet-billed. Submission is wallet-gated (402 when empty).
+- **The original stays temporary** — URL-ingested and uploaded sources live ONLY in your temp folder (`users/…/temporary/clip-sources/…`) with a hard **30-day TTL** (auto-deleted from S3 + the temp-file list). The hunted clips themselves are durable.
+- **Captions rule** — "no captions / no on-screen text" hunts are handled by scene SELECTION (the refine pass drops text-heavy scenes). **Never run GhostCut caption removal on a long-form source** (it is hard-capped at ~15 minutes); to actually erase burned-in text, apply `POST /api/v1/primitives/videos/remove-captions` to individual FINISHED clips afterwards.
+
+**devcli (local-first — this is the default way to hunt on your own machine):**
+
+```bash
+# Local machine power: local ffmpeg + your local claude/codex CLI subscription (no API key needed)
+vidfarm clips scan ./podcast.mp4 --range "12:30-15:45" --duration 30 --aspect vertical --no-text \
+  --prompt "guest reaction moments"
+
+# Provider keys are the fallback (--provider gemini|openai|openrouter); the cloud pipeline is the
+# EXPLICIT backup, never the default:
+vidfarm clips scan --cloud ./podcast.mp4 --duration 30 --aspect 9:16 --tracer my-campaign
+vidfarm clips scan --cloud --url "https://youtube.com/watch?v=…" --range "0:00-10:00"
+
+# Then search/reuse the library
+vidfarm clips search "confused reaction after reading a message"
+vidfarm clips export <clip-ids…> --to ./picks
+```
+
+Local scans persist to a SQLite library under `~/.vidfarm` (free compute, subscription-powered evaluation); `--cloud` uploads to your temp folder (30-day TTL) or passes `--url`, runs the deployed pipeline, and bills AWS compute only.
+
 ## Generate AI media and drop it on the timeline
 
 Both surfaces can generate a NEW AI video/image (optionally conditioned on reference images) and place it into the timeline — filling a blank gap or replacing a scene — using the async generation primitives (`POST /api/v1/primitives/videos/generate`, `/images/generate`). Generation is a **queued job**: the POST returns `202 { job_id }`, and the finished media URL only appears after the job settles (`result.primary_file_url` / `video.file_url` / an artifact `public_url`). Poll `GET /api/v1/user/me/jobs/:jobId` until `status: "succeeded"`.
@@ -472,6 +524,10 @@ Send a stable `tracer` on export so retries are traceable and filterable in job
 | `vidfarm files [--folder <path>]` | `GET /api/v1/user/me/attachments` | list My Files assets + folders |
 | `vidfarm get-file <id> [dest] [--print]` | (resolve id → view_url, then stream/print) | read one My Files asset |
 | `vidfarm put-file <file> [--folder <p>] [--as <name>] [--content/--stdin]` | `POST /api/v1/user/me/attachments/upload` | write into My Files (persistent) |
+| `vidfarm clips scan <video> [--range MM:SS-MM:SS] [--duration <s>] [--aspect 9:16] [--no-text] [--prompt "…"]` | (LOCAL: local ffmpeg + local claude/codex agent → `~/.vidfarm` SQLite) | hunt long-form video into short clips on this machine |
+| `vidfarm clips scan --cloud <video\|--url <url>> [--tracer <id>]` | temp-file presign/PUT/finalize + `POST /clips/scan` + poll | BACKUP: run the hunt on the deployed pipeline (bills AWS compute only) |
+| `vidfarm clips search "…"` / `clips match "…"` / `clips list` / `clips sources` | (local library; NL→criteria via local agent or provider key) | search/reuse the clip library |
+| `vidfarm clips preset list\|run\|save` / `clips export <ids…> --to <dir>` | (local library) | saved queries; copy clip MP4s out |
 
 **Frontend URLs are first-class output.** Every command that has a human-openable page (editor, discover, approved-post preview, share link) prints that prod frontend URL as a highlighted line. `render --wait` polls to completion and prints the final MP4 URL; `approve` prints the approved-post `share_url`. Add `--json` to any command for pure JSON (agent-friendly, no banners).
 
@@ -587,6 +643,7 @@ Remove burned-in captions/subtitles/on-screen text from any video URL (GhostCut-
 - Response: standard primitive job (`202 { job_id }`). The job probes the source, submits to GhostCut, polls to completion server-side (typically a few minutes), and mirrors the result. Poll `GET /api/v1/primitives/jobs/:jobId` until `status: "succeeded"`, then read `primary_file_url` / `video.file_url` (`captionsRemovedVideoUrl` in the output).
 - Billing: `~$0.10 per 30 seconds` of source video (per-chunk, 1-chunk minimum; `ghostcut_subtitle_removal` cost center), plus the small probe cost.
 - For the CURRENT fork's decompose flow, don't re-run this primitive — the caption-free mirror already exists via `GET /api/v1/compositions/:forkId/remove-video-captions`.
+- **Short clips only — hard cap ~15 minutes** (`GHOSTCUT_MAX_DURATION_SEC`, default 900s). Never point this at a long-form source: for "clips without captions" from a long video, run a clip hunt with `avoid_text: true` (scene selection — see "Clip hunting") and, if needed, apply this primitive to the individual FINISHED clips.
 
 Example:
 

package/SKILL.platform.md

@@ -229,7 +229,18 @@ Read-only companion: `GET /api/v1/compositions/:forkId/remove-video-captions` (l
 
 Standalone primitive: `POST /api/v1/primitives/videos/remove-captions` (alias: `POST /api/v1/primitives/remove-video-captions`; id `primitive:video_remove_captions` in `src/primitive-registry.ts`) exposes the same GhostCut pipeline for ANY video URL, decoupled from forks and decompose. The job probes the source (duration prices the task), submits, polls GhostCut to completion inside the job runner (12-minute budget, vs the fork routes where the client drives completion), mirrors `captions-removed.mp4` into primitive storage, and bills the `ghostcut_subtitle_removal` cost center per 30s chunk.
 
-Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-through cost: `GHOSTCUT_USD_PER_30S` (default 0.10).
+Configuration: `GHOSTCUT_KEY` and `GHOSTCUT_SECRET` env vars per stage. Pass-through cost: `GHOSTCUT_USD_PER_30S` (default 0.10). **Guard:** the primitive hard-fails sources longer than `GHOSTCUT_MAX_DURATION_SEC` (default 900s) — GhostCut is a per-finished-clip tool; long-form "no captions" requests are served by the clip-hunt `avoid_text` scene-selection filter instead, never by laundering a whole long video through GhostCut.
+
+## Clip hunting pipeline (long-form → short-form)
+
+`POST /clips/scan` starts a Step Functions STANDARD workflow (`…ClipScanWorkflow`): `probe_and_detect` → `Map(process_scene, maxConcurrency 5)` → `finalize`, all three states dispatching the same `infra/lambda/clip-scan.ts` on an `action` field. Business logic lives in the shared `src/services/clip-curation/` core (also consumed by devcli and the Hono API), with the hunt controls in `hunt.ts`:
+
+- **`hunt_spec`** — windows (time ranges; ffmpeg input-seeks per window so only the requested footage is DECODED — the actual cost saving), a soft `duration_band` (`resolveDurationBand`: 10→5-20s, 30→20-40s via ±target/3), output `aspect` + `crop_focus` (smart-centre ffmpeg crop applied to clips, thumbnails, AND tagging keyframes so the model judges the framed output), `avoid_text` (rides the keep/drop/merge refine pass as a selection filter), and `source_url` (RapidAPI ingest → the user's temp folder). The spec travels as ONE opaque JsonPath object through the state machine, so new hunt fields are Lambda-code-only changes — no state-machine redeploy.
+- **Sources are temporary** — URL ingests and uploads land at `users/{id}/temporary/clip-sources/…` with a hard 30-day TTL enforced three ways: tag-scoped S3 lifecycle (`vidfarm-temp=1`, tagged server-side at temp-file finalize/upload), native DynamoDB TTL (`expires_at_epoch_seconds`, top-level on the item), and the list-route sweep. Hunted clips (`clips/{owner}/…`) are durable.
+- **Billing: AWS compute ONLY.** Every Lambda invocation post-hoc bills its GB-seconds to the `clip_scan_lambda` cost center (idempotent on `awsRequestId`); `finalize` adds `step_functions_standard` scaled by scene count (3 + N transitions); URL ingest adds the existing `rapidapi_video_download` pass-through. `jobId = scan_id`, and the caller's `tracer` rides every event (gsi2-tracer rollups). The BYOK tagging/embedding spend (gemini/openai/openrouter keys in the state input) is deliberately never wallet-billed. Submission is wallet-gated (`assertWalletCanQueueJobs` → 402); the 202 response carries a pre-scan `compute_estimate`.
+- **Failure reconciliation** — the workflow has no failure hook into records, so `GET /clips/scan/:scanId` lazily `DescribeExecution`s a running scan and flips the scan+source records to `failed` (or `complete`) so pollers converge.
+- **devcli is LOCAL-FIRST** — `vidfarm clips scan` runs local ffmpeg and, by default, the user's local claude/codex CLI subscription (`LocalAgentClipClient`, implementing the same `ClipHuntModelClient` interface as the API providers; refine's model call lives on the client as `decideScenes` to make them swappable). Provider keys are the fallback; `--cloud` is the explicit backup that presign-uploads to the temp folder and drives this pipeline.
+- **Bundling gotcha** — the clip-scan and primitive-media Lambdas bundle `ffmpeg-static`/`ffprobe-static` with `forceDockerBundling: true`: ffmpeg-static downloads the binary for the platform it is installed on, so a mac-local bundle ships a darwin ffmpeg the Lambda cannot exec (`exit 126`). They also need `VIDFARM_DATA_DIR=/tmp/vidfarm` because `config.ts` mkdirs at import.
 
 ## Editor Chat
 
@@ -265,6 +276,7 @@ Key mechanics:
 - Every wallet mutation carries a `tracer` (idempotency key)
 - Provider spend is passed through at cost — no markup on AI provider calls
 - Platform infrastructure (cloud render, GhostCut, storage) has a small safety buffer applied
+- Clip hunts bill **AWS compute only** (`clip_scan_lambda` GB-seconds + `step_functions_standard` transitions, keyed to `jobId = scan_id`); the hunt's AI tagging runs on the caller's own provider keys (BYOK) and never touches the wallet
 - Failed jobs are refunded automatically when the failure is on the platform side
 - **Local `vidfarm serve` render is free + unguarded** — `publishCompositionToRenderer` runs the render in-process (`runPrimitiveJobInProcess`) and skips the wallet/paid guard when no cloud state machine is wired; only cloud render/templates are paid + wallet-guarded
 

package/dist/src/account-pages-legacy.js

@@ -6834,7 +6834,7 @@ export function renderLibraryPage(input) {
       .library-shell { display: grid; grid-template-rows: auto minmax(0, 1fr); gap: 12px; }
       .library-toolbar {
         display: grid;
-        grid-template-columns: minmax(220px, 1fr) auto auto auto;
+        grid-template-columns: auto minmax(200px, 1fr) auto auto;
         align-items: center;
         gap: 10px;
         padding: 10px 12px;
@@ -7031,8 +7031,7 @@ export function renderLibraryPage(input) {
         text-overflow: ellipsis;
         white-space: nowrap;
       }
-      .library-history-link { min-height: 38px; white-space: nowrap; }
-      .library-history-short { display: none; }
+      .library-toolbar .view-toggle { justify-self: start; }
       .library-empty { display: grid; place-items: center; min-height: 260px; border: 1px dashed rgba(191, 164, 109, 0.36); border-radius: 18px; color: #617087; background: rgba(255,252,247,.62); }
       ${renderReadyPostScheduleStyles()}
       @media (max-width: 1180px) {
@@ -7145,24 +7144,27 @@ export function renderLibraryPage(input) {
         .library-body { padding-top: 12px; }
         .library-shell { min-width: 0; }
         .library-list-shell { overflow: visible; padding-right: 0; }
-        .library-history-link, .library-options summary {
+        .library-options summary {
           min-height: 38px;
           width: 100%;
           padding: 0 8px;
           white-space: nowrap;
           font-size: 0.86rem;
         }
-        .library-history-link {
-          flex: 0 0 52px;
-          width: 52px;
+        .library-toolbar .view-toggle {
+          flex: 0 0 auto;
+          order: -1;
+        }
+        .library-toolbar .view-toggle-tab {
+          min-height: 38px;
+          padding: 0 12px;
+          font-size: 0.82rem;
         }
         .library-options {
           flex: 0 0 76px;
           width: 76px;
           min-width: 0;
         }
-        .library-history-full { display: none; }
-        .library-history-short { display: inline; }
         .library-selection-count {
           display: none;
           min-width: 0;
@@ -7247,8 +7249,11 @@ export function renderLibraryPage(input) {
         <div class="frame-body library-body">
           <section class="library-shell">
             <div class="library-toolbar">
+              <div class="view-toggle" role="tablist" aria-label="Library view">
+                <a class="view-toggle-tab is-active" role="tab" aria-current="page" href="${escapeAttribute(withAccountQuery("/library", input.currentAccountId))}">Finished</a>
+                <a class="view-toggle-tab" role="tab" href="${escapeAttribute(withAccountQuery("/clips", input.currentAccountId))}">Clips</a>
+              </div>
               <input class="library-search" data-library-search type="search" placeholder="Search published renders" autocomplete="off">
-              <a class="button secondary library-history-link" href="${escapeAttribute(withAccountQuery("/job-runs", input.currentAccountId))}"><span class="library-history-full">Render History</span><span class="library-history-short">Runs</span></a>
               <details class="library-options">
                 <summary>Options</summary>
                 <div class="library-options-panel">