npm - @mevdragon/vidfarm-devcli - Versions diffs - 0.13.0 → 0.15.0 - Mend

@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (427) hide show

package/.agents/skills/talking-head-recut/references/styles/terminal.html ADDED Viewed

@@ -0,0 +1,196 @@
+<!--
+  Style: terminal — dark · JetBrains Mono · ASCII border · prompt · multi-color highlight
+  ─────────────────────────────────────────────────────────────────────
+  Tokens
+    bg     #0d1117   (deep terminal)
+    ink    #e6edf3
+    muted  #7d8590
+    accent #4ade80   (green — primary output)
+    accent2#fbbf24   (amber — string/warn)
+    accent3#f472b6   (magenta — variable)
+    accent4#60a5fa   (blue — function/path)
+  Fonts
+    mono (everything) — ui-monospace, "SF Mono", Menlo, monospace
+    (Real JetBrains Mono would need a woff2 ship; mono fallback fine.)
+  Best with
+    layouts: split, pip
+    frames:  hairline, clean
+    content: 技术分析 / 代码片段 / 性能数据 / 工程思考
+  Notes
+    - "Blinking cursor" must be a CSS animation, NOT a data-anim. Allowed
+      because pure CSS @keyframes on a single visual indicator is harmless.
+    - For animated reveal of lines, use data-anim="fade-in" per line.
+-->
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <title>style · terminal</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: #0a0c12;
+        font-family: ui-sans-serif, system-ui, sans-serif;
+      }
+      .stage {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        transform-origin: top left;
+        transform: scale(0.5);
+        overflow: hidden;
+      }
+      .card-host {
+        position: absolute;
+        left: 0;
+        top: 0;
+        width: 1920px;
+        height: 1080px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="stage">
+      <div class="card-host">
+        <div class="card" data-card-id="ref-terminal">
+          <style>
+            .card[data-card-id="ref-terminal"] .root {
+              --bg: #0d1117;
+              --ink: #e6edf3;
+              --muted: #7d8590;
+              --green: #4ade80;
+              --amber: #fbbf24;
+              --magenta: #f472b6;
+              --blue: #60a5fa;
+              --font-mono: ui-monospace, "SF Mono", Menlo, "Courier New", monospace;
+              width: 100%;
+              height: 100%;
+              position: relative;
+              overflow: hidden;
+              background: var(--bg);
+              color: var(--ink);
+              padding: 36px 48px;
+              box-sizing: border-box;
+              font: 28px/1.55 var(--font-mono);
+            }
+            .card[data-card-id="ref-terminal"] .ascii-frame {
+              position: absolute;
+              inset: 16px;
+              border: 2px solid #2c333e;
+              border-radius: 6px;
+              box-shadow:
+                inset 0 0 0 1px #1a1f27,
+                0 0 0 1px #06080c;
+            }
+            .card[data-card-id="ref-terminal"] .titlebar {
+              position: absolute;
+              left: 36px;
+              top: 12px;
+              padding: 0 8px;
+              background: var(--bg);
+              font: 600 14px/1 var(--font-mono);
+              color: var(--muted);
+              letter-spacing: 0.12em;
+            }
+            .card[data-card-id="ref-terminal"] .content {
+              position: relative;
+              padding: 18px 12px;
+              display: flex;
+              flex-direction: column;
+              gap: 14px;
+            }
+            .card[data-card-id="ref-terminal"] .prompt {
+              color: var(--green);
+            }
+            .card[data-card-id="ref-terminal"] .line .blue {
+              color: var(--blue);
+            }
+            .card[data-card-id="ref-terminal"] .line .amber {
+              color: var(--amber);
+            }
+            .card[data-card-id="ref-terminal"] .line .pink {
+              color: var(--magenta);
+            }
+            .card[data-card-id="ref-terminal"] .line .green {
+              color: var(--green);
+            }
+            .card[data-card-id="ref-terminal"] .line .muted {
+              color: var(--muted);
+            }
+            .card[data-card-id="ref-terminal"] .kicker {
+              color: var(--muted);
+              font: 600 16px/1 var(--font-mono);
+              letter-spacing: 0.22em;
+              margin-bottom: 4px;
+            }
+            .card[data-card-id="ref-terminal"] .headline {
+              font: 700 56px/1.15 var(--font-mono);
+              color: var(--ink);
+              margin: 4px 0 14px;
+            }
+            .card[data-card-id="ref-terminal"] .headline .hl {
+              background: rgba(74, 222, 128, 0.18);
+              color: var(--green);
+              padding: 0 6px;
+            }
+            .card[data-card-id="ref-terminal"] .cursor {
+              display: inline-block;
+              width: 14px;
+              height: 28px;
+              background: var(--green);
+              margin-left: 4px;
+              vertical-align: -4px;
+              animation: ref-term-blink 1s steps(1) infinite;
+            }
+            @keyframes ref-term-blink {
+              50% {
+                opacity: 0;
+              }
+            }
+          </style>
+          <div class="root">
+            <div class="ascii-frame"></div>
+            <span class="titlebar">~/notes/takeaway-007.md</span>
+            <div class="content">
+              <div class="kicker" data-anim="fade-in" data-anim-at="0.05" data-anim-duration="0.3">
+                $ cat takeaway
+              </div>
+              <h2
+                class="headline"
+                data-anim="fade-in"
+                data-anim-at="0.25"
+                data-anim-duration="0.45"
+              >
+                缓存命中率提升到 <span class="hl">92%</span>
+              </h2>
+              <div class="line" data-anim="fade-in" data-anim-at="0.55" data-anim-duration="0.35">
+                <span class="prompt">$</span> bench --tier <span class="amber">"hot"</span>
+                <span class="muted">--n 10k</span>
+              </div>
+              <div class="line" data-anim="fade-in" data-anim-at="0.8" data-anim-duration="0.35">
+                <span class="muted">→</span> <span class="blue">p50</span>=<span class="green"
+                  >12ms</span
+                >
+                <span class="blue">p99</span>=<span class="green">38ms</span>
+                <span class="pink">hit</span>=<span class="green">92.4%</span>
+              </div>
+              <div class="line" data-anim="fade-in" data-anim-at="1.05" data-anim-duration="0.35">
+                <span class="muted">// before this change: hit=63%, p99=210ms</span>
+              </div>
+              <div class="line" data-anim="fade-in" data-anim-at="1.35" data-anim-duration="0.3">
+                <span class="prompt">$</span><span class="cursor"></span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>

package/.agents/skills/talking-head-recut/references/styles/whiteboard.html ADDED Viewed

@@ -0,0 +1,170 @@
+<!--
+  Style: whiteboard — paper · Caveat handwriting · sketched borders · marker highlight
+  ─────────────────────────────────────────────────────────────────────
+  Tokens
+    bg     #fdf6e3   (warm paper)
+    ink    #1a1a1a
+    muted  #6e6a5b
+    accent #ff6b35   (orange marker)
+    accent2#2557a7   (blue pen — annotations)
+    accent3#ffe066   (yellow highlighter)
+  Fonts
+    headline & body — Caveat (handwriting); falls back to "ui-serif, cursive"
+    annotations    — Caveat
+  Best with
+    layouts: pip, overlay, split
+    frames:  polaroid, clean
+    content: 教程 / 解构 / 草图思考 / 灵感整理
+  Notes
+    - SVG strokes have subtle path jitter to look hand-drawn.
+    - data-anim "draw-path" is ideal for the sketched border + highlights.
+-->
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <title>style · whiteboard</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: #0a0c12;
+        font-family: ui-sans-serif, system-ui, sans-serif;
+      }
+      .stage {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        transform-origin: top left;
+        transform: scale(0.5);
+        overflow: hidden;
+      }
+      .card-host {
+        position: absolute;
+        left: 0;
+        top: 0;
+        width: 1920px;
+        height: 1080px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="stage">
+      <div class="card-host">
+        <div class="card" data-card-id="ref-whiteboard">
+          <style>
+            .card[data-card-id="ref-whiteboard"] .root {
+              --bg: #fdf6e3;
+              --ink: #1a1a1a;
+              --muted: #6e6a5b;
+              --accent: #ff6b35;
+              --accent2: #2557a7;
+              --accent3: #ffe066;
+              --font-hand: "Caveat", "LXGW WenKai TC", ui-serif, cursive;
+              width: 100%;
+              height: 100%;
+              position: relative;
+              overflow: hidden;
+              background-color: var(--bg);
+              background-image:
+                radial-gradient(circle at 30% 20%, rgba(0, 0, 0, 0.025) 0%, transparent 50%),
+                radial-gradient(circle at 80% 70%, rgba(0, 0, 0, 0.02) 0%, transparent 50%);
+              padding: 48px 56px;
+              box-sizing: border-box;
+              display: flex;
+              flex-direction: column;
+              justify-content: center;
+              gap: 26px;
+              color: var(--ink);
+              font-family: var(--font-hand);
+            }
+            .card[data-card-id="ref-whiteboard"] .sketch-border {
+              position: absolute;
+              inset: 16px;
+              pointer-events: none;
+            }
+            .card[data-card-id="ref-whiteboard"] .sketch-border path {
+              stroke: var(--ink);
+              stroke-width: 3;
+              fill: none;
+              stroke-linecap: round;
+              stroke-linejoin: round;
+            }
+            .card[data-card-id="ref-whiteboard"] .kicker {
+              align-self: flex-start;
+              font: 700 32px/1 var(--font-hand);
+              color: var(--accent);
+              transform: rotate(-2deg);
+              padding-left: 8px;
+            }
+            .card[data-card-id="ref-whiteboard"] .title {
+              margin: 0;
+              font: 700 120px/1 var(--font-hand);
+              color: var(--ink);
+            }
+            .card[data-card-id="ref-whiteboard"] .marker {
+              position: relative;
+              display: inline-block;
+              padding: 0 8px;
+              color: var(--ink);
+            }
+            .card[data-card-id="ref-whiteboard"] .marker::before {
+              content: "";
+              position: absolute;
+              left: 0;
+              right: 0;
+              top: 30%;
+              bottom: 18%;
+              background: var(--accent3);
+              z-index: -1;
+              transform: skewX(-4deg);
+            }
+            .card[data-card-id="ref-whiteboard"] .detail {
+              margin: 0;
+              font: 400 40px/1.4 var(--font-hand);
+              color: var(--muted);
+              max-width: 92%;
+            }
+            .card[data-card-id="ref-whiteboard"] .note {
+              align-self: flex-start;
+              padding: 6px 12px;
+              font: 600 28px/1 var(--font-hand);
+              color: var(--accent2);
+              border-bottom: 3px wavy var(--accent2);
+              transform: rotate(-1deg);
+            }
+          </style>
+          <div class="root">
+            <svg class="sketch-border" viewBox="0 0 1888 1048" preserveAspectRatio="none">
+              <path
+                d="M 12 12 L 1876 16 L 1872 1036 L 16 1032 Z"
+                data-anim="draw-path"
+                data-anim-at="0.05"
+                data-anim-duration="0.8"
+              />
+            </svg>
+            <span class="kicker" data-anim="fade-in" data-anim-at="0.1" data-anim-duration="0.4">
+              ✎ TAKEAWAY
+            </span>
+            <h2 class="title" data-anim="fade-in" data-anim-at="0.4" data-anim-duration="0.5">
+              把复杂问题<span class="marker">画出来</span>。
+            </h2>
+            <p class="detail" data-anim="fade-in" data-anim-at="0.85" data-anim-duration="0.45">
+              文字让人争辩，图让人对齐。当所有人都在白板前看同一张图，分歧自然消失。
+            </p>
+            <span class="note" data-anim="fade-in" data-anim-at="1.2" data-anim-duration="0.4">
+              ← 试试每次会议都画
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>

package/.agents/skills/talking-head-recut/references/styles/xhs.html ADDED Viewed

@@ -0,0 +1,206 @@
+<!--
+  Style: xhs (小红书) — cream + hot pink · chips · #hashtags · ❤️💬 row
+  ─────────────────────────────────────────────────────────────────────
+  Tokens
+    bg     #fff5e9   (warm cream)
+    ink    #1d1418
+    muted  #8a7a78
+    accent #ff2e63   (hot pink — chip + interaction icon)
+    accent2#ff8a4c   (orange — tag)
+    accent3#f0c419   (yellow — pin)
+  Fonts
+    headline & body — Noto Sans SC fallback: ui-sans-serif, system-ui, "PingFang SC", sans-serif
+  Best with
+    layouts: overlay, stack (especially in portrait/9:16)
+    frames:  clean, polaroid
+    content: 社交剪辑 / 生活方式 / 种草 / 短视频高光
+-->
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <title>style · xhs (小红书)</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: #0a0c12;
+        font-family: ui-sans-serif, system-ui, sans-serif;
+      }
+      .stage {
+        position: relative;
+        width: 1920px;
+        height: 1080px;
+        transform-origin: top left;
+        transform: scale(0.5);
+        overflow: hidden;
+      }
+      .card-host {
+        position: absolute;
+        left: 0;
+        top: 0;
+        width: 1920px;
+        height: 1080px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="stage">
+      <div class="card-host">
+        <div class="card" data-card-id="ref-xhs">
+          <style>
+            .card[data-card-id="ref-xhs"] .root {
+              --bg: #fff5e9;
+              --ink: #1d1418;
+              --muted: #8a7a78;
+              --accent: #ff2e63;
+              --accent2: #ff8a4c;
+              --accent3: #f0c419;
+              --font-sans: ui-sans-serif, system-ui, "PingFang SC", "Hiragino Sans GB", sans-serif;
+              width: 100%;
+              height: 100%;
+              position: relative;
+              overflow: hidden;
+              background: var(--bg);
+              color: var(--ink);
+              font-family: var(--font-sans);
+              padding: 36px 44px;
+              box-sizing: border-box;
+              display: flex;
+              flex-direction: column;
+              gap: 22px;
+            }
+            .card[data-card-id="ref-xhs"] .user-row {
+              display: flex;
+              align-items: center;
+              gap: 14px;
+            }
+            .card[data-card-id="ref-xhs"] .avatar {
+              width: 56px;
+              height: 56px;
+              border-radius: 50%;
+              background: linear-gradient(135deg, #ff2e63, #ff8a4c);
+              box-shadow:
+                0 0 0 3px #fff,
+                0 0 0 4px rgba(255, 46, 99, 0.3);
+            }
+            .card[data-card-id="ref-xhs"] .user-info {
+              flex: 1;
+            }
+            .card[data-card-id="ref-xhs"] .user-name {
+              font: 700 22px/1.1 var(--font-sans);
+              color: var(--ink);
+            }
+            .card[data-card-id="ref-xhs"] .user-sub {
+              font: 400 16px/1.3 var(--font-sans);
+              color: var(--muted);
+            }
+            .card[data-card-id="ref-xhs"] .follow {
+              padding: 8px 20px;
+              border-radius: 999px;
+              background: var(--accent);
+              color: #fff;
+              font: 700 16px/1 var(--font-sans);
+            }
+            .card[data-card-id="ref-xhs"] .title {
+              margin: 0;
+              font: 800 84px/1.1 var(--font-sans);
+              color: var(--ink);
+              letter-spacing: -0.01em;
+            }
+            .card[data-card-id="ref-xhs"] .title .heart {
+              color: var(--accent);
+            }
+            .card[data-card-id="ref-xhs"] .detail {
+              margin: 0;
+              font: 500 28px/1.5 var(--font-sans);
+              color: var(--ink);
+              max-width: 94%;
+            }
+            .card[data-card-id="ref-xhs"] .tags {
+              display: flex;
+              flex-wrap: wrap;
+              gap: 10px;
+            }
+            .card[data-card-id="ref-xhs"] .tag {
+              padding: 8px 18px;
+              border-radius: 999px;
+              background: rgba(255, 46, 99, 0.12);
+              color: var(--accent);
+              font: 600 18px/1 var(--font-sans);
+            }
+            .card[data-card-id="ref-xhs"] .tag.orange {
+              background: rgba(255, 138, 76, 0.16);
+              color: var(--accent2);
+            }
+            .card[data-card-id="ref-xhs"] .tag.yellow {
+              background: rgba(240, 196, 25, 0.18);
+              color: #a98209;
+            }
+            .card[data-card-id="ref-xhs"] .interactions {
+              display: flex;
+              gap: 28px;
+              margin-top: auto;
+              padding-top: 14px;
+              border-top: 1px solid rgba(0, 0, 0, 0.06);
+              font: 700 22px/1 var(--font-sans);
+              color: var(--ink);
+            }
+            .card[data-card-id="ref-xhs"] .interactions span {
+              display: inline-flex;
+              align-items: center;
+              gap: 8px;
+            }
+            .card[data-card-id="ref-xhs"] .interactions .heart-ic {
+              color: var(--accent);
+              font-size: 26px;
+            }
+          </style>
+          <div class="root">
+            <div class="user-row" data-anim="fade-in" data-anim-at="0.05" data-anim-duration="0.4">
+              <div class="avatar"></div>
+              <div class="user-info">
+                <div class="user-name">@小研究员</div>
+                <div class="user-sub">关注我，看我每天拆一段视频 · 18分钟前</div>
+              </div>
+              <div class="follow">+ 关注</div>
+            </div>
+            <h2 class="title" data-anim="fade-in" data-anim-at="0.3" data-anim-duration="0.5">
+              亲测有效！<span class="heart">♥</span> 30 秒抓住注意力的小技巧
+            </h2>
+            <p class="detail" data-anim="fade-in" data-anim-at="0.7" data-anim-duration="0.45">
+              开头别废话——直接抛结论。听众的大脑在前 3 秒就决定要不要继续，
+              这是平台算法之外，最朴素也最重要的事实。
+            </p>
+            <div class="tags" data-anim="fade-in" data-anim-at="1.0" data-anim-duration="0.4">
+              <span class="tag">#内容创作</span>
+              <span class="tag orange">#播客剪辑</span>
+              <span class="tag yellow">#开头技巧</span>
+            </div>
+            <div
+              class="interactions"
+              data-anim="fade-in"
+              data-anim-at="1.25"
+              data-anim-duration="0.4"
+            >
+              <span><span class="heart-ic">♥</span> 12.4k</span>
+              <span>💬 386</span>
+              <span>⭐ 891</span>
+              <span
+                style="margin-left: auto; color: var(--muted); font-weight: 400; font-size: 18px"
+                >📤 分享</span
+              >
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </body>
+</html>

package/.agents/skills/vidfarm-media/SKILL.md ADDED Viewed

@@ -0,0 +1,85 @@
+---
+name: vidfarm-media
+description: Media resolution for video workflows — narration TTS, word-level timings, BGM, SFX, and image/clip sourcing through vidfarm. Use when a video needs audio (voiceover/narration, music, sound effects), caption word timings, or media assets. Ships the shared audio engine scripts/audio.mjs (audio_request.json → audio_meta.json) used by faceless-explainer, product-launch-video, and general-video; documents vidfarm tts/stt BYOK primitives, the keyless local Kokoro + whisper.cpp engines, and My Files / clip-library / generation sourcing. No third-party media accounts — everything is user-owned or generated on the user's keys.
+---
+# vidfarm-media
+One engine and one rule. The engine: `scripts/audio.mjs` turns a neutral `audio_request.json` into narration files, word timings, a music bed, and SFX — written into the project and described by one meta JSON. The rule: **no third-party media accounts, ever** — audio and images are the user's own files, found in the user's My Files / clip library, generated on the user's provider keys, or produced by keyless local models. If a source needs a sign-up, it is not a source.
+## Preflight (run once, before the brief)
+Check which engines this run will use and say so in one line — then continue. There is nothing to sign in to and no reason to stop.
+- Saved keys: `vidfarm provider-keys`, or env `OPENAI_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY`.
+- Key present → BYOK cloud speech: `vidfarm tts` (promptable voice via `--style`) and `vidfarm stt` (real word timestamps on an OpenAI whisper-1 key).
+- No key → keyless local engines: Kokoro-82M TTS (`npx hyperframes tts`) and whisper.cpp timings (`npx hyperframes transcribe`). They download model weights on first use and never need an account.
+- Don't write keys into a per-repo `.env`. Details: `references/tts.md`.
+## The audio engine
+```bash
+node <SKILL_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json [--only tts,bgm,sfx]
+```
+Adapters in faceless-explainer and product-launch-video resolve this engine at `../../vidfarm-media/scripts/audio.mjs` (override with `$HF_MEDIA_ENGINE`); general-video calls it directly. Full schema lives in the script's header comment; the shape:
+```jsonc
+// audio_request.json — one line per narrated segment; `id` is the caller's join key
+{
+  "provider": "auto",                  // auto = keyless local Kokoro; openai/gemini/openrouter = vidfarm BYOK
+  "voice": "af_heart",                 // Kokoro id, or a cloud preset (alloy…, Kore…) — see references/tts.md
+  "speed": 1.0,                        // Kokoro only
+  "lines": [
+    { "id": "01", "text": "Opening line.", "sfx": ["whoosh"] },
+    { "id": "02", "sfx": ["click"] }   // sfx-only lines are how adapters fetch SFX later
+  ],
+  "bgm": { "mode": "retrieve", "query": "calm cinematic underscore" } // "none" disables; no generate mode exists
+}
+```
+```jsonc
+// audio_meta.json — id-keyed; every path RELATIVE to --hyperframes
+{
+  "voices": [{ "id": "01", "path": "assets/voice/01.wav", "duration_s": 4.21,
+               "words": [{ "id": "w0", "text": "Opening", "start": 0.02, "end": 0.31 }] }],
+  "bgm": { "path": "assets/bgm/track.mp3", "query": "…", "duration_s": 22.4 },   // or null + a note
+  "sfx": [{ "id": "01", "file": "assets/sfx/whoosh.mp3", "offset_s": 0, "duration_s": 0.9, "volume": 0.35 }],
+  "notes": ["bgm: skipped — …"]        // every graceful skip is explained here
+}
+```
+Contract points:
+- `--only` **merges**: sections not listed are preserved from the existing `--out` meta (generate `--only tts,bgm`, then `--only sfx` later — nothing is lost).
+- Word timings are real (local whisper.cpp) when possible, else estimated by proportional character weighting. Timings never fail the run.
+- BGM is **not** loop-extended by the engine — the workflow assemblers loop-extend short beds to the video length at mount time. `bgm_pending` is never set; `scripts/wait-bgm.mjs` exists as an exit-0 shim.
+- Mount the results per `hyperframes-core`: each `voices[].path` and (`bgm.path`, `sfx[]`) as `<audio>` tracks; `voices[].words` drive captions.
+## TTS / STT providers
+| Need | Command | Notes |
+| --- | --- | --- |
+| Narration, promptable voice (BYOK) | `vidfarm tts "…" --style "calm, warm narrator"` | Local-first on your env key; `--voice alloy`/`Kore`…; `--cloud` = saved-key platform job → `POST /api/v1/primitives/audio/speech` |
+| Narration, zero keys | `npx hyperframes tts "…" -v af_heart --json` | Kokoro-82M, local, WAV + duration in JSON |
+| Transcript + SRT (BYOK) | `vidfarm stt <file\|url>` | Gemini key labels speakers; OpenAI whisper-1 gives real word timestamps |
+| Word timings, zero keys | `npx hyperframes transcribe <audio> --json` | whisper.cpp; writes word-level `transcript.json` |
+| Captions straight into a composition | `vidfarm captions generate <dir>` | whisper-1 real timings when an OpenAI key exists; estimates otherwise |
+Voices, styles, formats, and the exact word-timestamp paths: `references/tts.md`.
+## BGM and SFX resolution order
+1. **User file / URL** — `bgm.file` / `bgm.url` in the request; copied or downloaded into `assets/bgm/`.
+2. **My Files** — `vidfarm files --search "<query> music"` (needs `$VIDFARM_API_KEY`); the user's own uploaded library, searchable by meaning when notes are annotated.
+3. **Local dir** — `$MUSIC_DIR` / `$SFX_DIR` (or request `bgm.dir` / `sfx_dir`), picked by filename keyword match against the query.
+4. **Skip, with a note** — a silent bed or a missing whoosh is fine; a stock-audio account is not. The meta's `notes[]` says exactly what was skipped and why.
+## Sourcing images and footage
+Same ownership rule, different surfaces:
+- **My Files** — `vidfarm files --search "<meaning>"`; annotate assets with `vidfarm annotate-file <id> --notes "…"` so search finds them later; write with `vidfarm put-file`.
+- **Clip library** — `vidfarm clips search "<text>"` over clips hunted from the user's long-form footage (`vidfarm clips scan <video>`).
+- **Generate on the user's keys** — `vidfarm generate image|video --prompt "…"` (BYOK primitives; `--place <dir>` drops the result straight into a composition).
+- Never hotlink or scrape third-party stock; a capture workflow's own screenshots and the user's brand assets are always fair game.