oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-video/resources/existing-media.md

@@ -0,0 +1,185 @@
+# Existing Video Analysis and Editing
+
+Use this branch for processing a supplied video or a real, already-rendered
+video. Work in a new run directory and retain the source. Audio-only requests
+stay with `oma-voice`. The OMA creation CLI, providers, asset bus and
+`render-spec.json` remain separate from the upstream editing project format.
+
+## Resolve the upstream skill
+
+1. Check the runtime skill catalog for `ffmpeg-skill` from
+   `https://github.com/kajisho5/ffmpeg-skill`. Reuse its advertised installed
+   location and read its complete `SKILL.md` when available.
+2. If it is absent or its support bundle is incomplete, load it without a
+   persistent installation or another agent:
+
+   ```bash
+   bunx skills use kajisho5/ffmpeg-skill@ffmpeg-skill
+   ```
+
+   Omit `--agent`. Read the emitted skill instructions and use the actual
+   supporting-files directory from the result for every relative path. Do not
+   guess a cache path or treat successful prompt output as a completed edit.
+3. Confirm that the supporting directory retains the complete package layout:
+   `SKILL.md`, `package.json`, all of `scripts/` including the `_common/` package,
+   `templates/` and `references/`. Scripts import sibling modules and use files
+   outside their own directory. An entry file or selected scripts alone are not
+   a usable bundle. Record the resolved source, version and support path with
+   the run; report an incomplete bundle rather than assembling guessed files.
+4. Follow the loaded upstream instructions for the selected operation. They
+   own the script and flag selection, command recipes, templates, editing
+   `project.json`, and probe/check/look workflow. Consult the selected script's
+   help or the requested reference instead of copying the cookbook here.
+   Do not start every job with `doctor`; follow the upstream failure-diagnosis
+   order. The standalone `bunx ffmpeg-skill` installer is not this loading path.
+5. An already-connected upstream MCP server is an optional execution surface.
+   Discover its actual tools and argument schemas before calling it. Retain
+   `mcp/server.py` and the complete script bundle when using that surface; its
+   contract comes from the same scripts. Do not configure a server or invent
+   tool names merely because a requested tool was not listed initially.
+
+The upstream package needs local Python and FFmpeg/FFprobe, plus the encoders,
+filters, fonts or optional transcription engine required by the chosen
+operation. A loaded skill does not establish those capabilities. If a requested
+operation or evidence is not supported by the loaded scripts or connected MCP,
+report the missing capability. Do not invent a raw FFmpeg command fallback.
+
+## Retain source-timeline evidence
+
+Before deciding from the media, retain the measurements exposed by the upstream
+probe and selected operation: actual stream indexes, rotation, dimensions, time
+bases, start times, channel layout, duration and any measured frame timestamps.
+Keep source PTS alongside time measured from the clip's start when available.
+Frame number divided by nominal FPS is not a source timestamp for VFR or
+nonzero-start media.
+
+Express selected audio and video on one source timeline and preserve their
+relative start offset. Map a detector's resampled audio clock back to that
+common timeline before applying intervals to video. Record the conversion and
+any gap, padding or frame/sample boundary adjustment; do not independently reset
+each stream's first retained sample to zero.
+
+The loaded upstream tools may not expose an exact source-PTS or frame inventory.
+Contact-sheet labels and requested extraction times do not establish that
+inventory. If the task requires exact mapping that the available tools cannot
+prove, state the limitation and retain the evidence they do provide. Do not
+fabricate source PTS, silently substitute nominal-FPS arithmetic, or claim exact
+sampling from an approximate extraction.
+
+## Select samples and interpret the picture
+
+Resolve the sampling definition before extracting:
+
+| Definition | Meaning |
+|---|---|
+| Codec keyframes | Decoder-marked random-access frames; encoding-dependent |
+| I-pictures | Intra-coded pictures; not necessarily random-access frames |
+| Scene changes | Visual-change candidates under a stated source-dependent threshold |
+| Time sampling | Source frames selected under the requested interval or timestamp policy |
+
+These are different sets. If an ambiguous "key frames" request changes the
+result materially, resolve its meaning; otherwise state the selected method.
+Choose an operation actually exposed by the loaded skill. An exact timestamp
+grid additionally needs nearest-source-frame evidence; a contact sheet does
+not prove it. Report unsupported sampling rather than silently changing its
+definition. Keep the selection parameters and each image's supported timestamp
+mapping. Image numbering alone carries no timing.
+
+Run the host vision tool on the actual extracted images for visual analysis.
+Record counts per supported source timestamp, with occluded or uncertain
+instances marked. Visible instances in one frame and unique identities across
+time are different claims; identity totals need tracking or explicit matching.
+Never sum frame counts to claim a unique-object total. Sparse samples cannot
+establish that an event never appeared between them; refine the relevant range
+when that is the question. If vision is unavailable, retain the images and
+report the missing interpretation. Mechanical measurements do not establish
+subject identity, interesting content or visual quality.
+
+## Decide which intervals may be removed
+
+Amplitude-based silence, absence of speech and unwanted content are separate
+criteria. Music can be loud without speech; speech can be quiet; a pause can
+carry a meaningful visual event. Use the user's criterion to decide removals.
+A long introduction is not automatically removable.
+
+Choose amplitude thresholds from the request or measured room tone and quiet
+speech, and minimum silence from the requested pause policy. Inspect channels
+separately when a downmix could mask speech. With no audio stream there are no
+audio-silence measurements. For speech-driven edits, require timed VAD or
+transcription regions from an available provider. `oma-voice` may return only
+text; inspect its response before treating it as a timing source. Missing words
+are not evidence of silence. Never invent word or segment times. Retain the
+model, channel, sample rate, thresholds and time-origin conversion.
+
+Before handing intervals to the upstream edit operation:
+
+1. Map measured candidates to source time, clip to media bounds, sort and merge
+   overlaps of the same classification. Close an open trailing silence at the
+   actual audio end; absent audio beyond that end is not measured silence.
+2. Protect measured speech with request-appropriate context padding bounded by
+   the source. Subtract these protected regions from amplitude candidates so
+   quiet breaths and word boundaries are not removed solely for their level.
+3. Listen to disputed regions with their adjacent phrase and inspect the video
+   when detectors or context disagree. Retain and identify unresolved regions
+   when the evidence cannot establish the requested removal criterion.
+4. Apply the requested minimum removal length after reconciliation. Save the
+   accepted removals, their reasons and the complementary keep intervals.
+   This mapping must also govern captions and other retained tracks.
+
+## Apply one edit timeline
+
+Pass the accepted intervals and required stream relationships to the supported
+upstream operation. Keep audio and video on the same edit mapping; removing
+silence from audio alone while retaining an unchanged picture shifts sync.
+Keyframe-constrained stream-copy cuts and frame/sample-accurate boundaries are
+different results. Record the precision and any adjusted boundary, gap or
+padding. An empty keep list needs an explicit empty-result decision.
+
+Retained subtitle and additional audio tracks need the same mapping. Do not
+silently drop them or keep their old timing. If the loaded operation cannot
+preserve the required A/V offset, boundary precision or selected streams,
+report that limitation rather than claiming a synchronized result.
+
+For multi-step editing, let upstream own its `project.json` and templates.
+OMA's creation `script.json`, `timing.json` and `render-spec.json` are distinct
+contracts. Do not pass one format as the other or imply that an adapter exists.
+
+## Assemble a dubbed clip
+
+Use `oma-voice` for transcription, synthesis and utterance fitting, and
+`oma-translation` for spoken translation. Timing must come from the supplied
+timeline or a provider that returns measured regions; plain transcript text
+has no timing. Return the fitted audio to this branch for placement through a
+supported upstream operation.
+
+When the user requests an unchanged picture, preserve its encoded video stream
+and use a compatible container where the supported tool permits it. Do not
+silently transcode it. Put source and dub on an explicit common clock, retaining
+nonzero PTS and the intended leading and inter-utterance gaps. A delayed
+container start alone is not proof that the dub contains the required silence.
+
+Do not truncate the picture to conceal a short dub. Resolve missing coverage
+through utterance fitting or request-appropriate silence padding. Preserve or
+mix background audio only as requested. If the upstream operation cannot keep
+the picture, coverage, container compatibility or offset requested, report the
+unsupported requirement before claiming success.
+
+## Return evidence in the requested format
+
+Retain the upstream exit status, output probe, delivery checks and any required
+contact-sheet path and actual inspection result. Interpret them against the
+requested edit. File existence or successful decoding alone does not establish
+correct cut choices, visual counts or natural speech. Report unresolved timing,
+coverage, capability and visual-inspection limits.
+
+Use the user's requested report or file format. The upstream's default report
+layout does not override that request; keep its probe/check/look evidence even
+when presenting it in a different shape. Do not claim an image was inspected
+when no image-viewing tool was available.
+
+## References
+
+- [Upstream ffmpeg-skill](https://github.com/kajisho5/ffmpeg-skill): the loaded
+  `SKILL.md`, its conditional references, scripts, templates and MCP contract.
+- [Skills CLI use](https://github.com/vercel-labs/skills/blob/main/docs/commands.md#skills-use):
+  prompt and complete support-directory loading without an installed skill.

package/skills/oma-video/resources/hyperframes-authoring/README.md

@@ -0,0 +1,44 @@
+# HyperFrames authoring
+
+Each run has an HTML project at `<runDir>/hyperframes/`. `oma video compose`
+prepares the latest HyperFrames CLI, local GSAP, optional Pretendard font,
+asset copies, and an `AUTHORING.md` contract. The agent writes `index.html`.
+
+```bash
+oma video compose <runDir> --output json
+# Read hyperframes/AUTHORING.md and its upstream API references.
+# Replace hyperframes/index.html with the finished composition.
+oma video render <runDir> --output json
+```
+
+## Contract
+
+- The run's `render-spec.json` remains authoritative. The project copy rewrites
+  media paths to `assets/`; `render-spec.js` exposes it as `window.OMA_VIDEO_SPEC`.
+- Use a standalone root with `data-composition-id`, `data-width`, `data-height`,
+  and `data-duration`. Convert frame offsets and durations to seconds with fps.
+- Use HTML `img`, `video`, and `audio` elements. Each audio element needs a unique
+  id. HyperFrames controls media playback; do not seek or play it yourself.
+  Sound-effect takes live under `assets/audio/sfx/` and are placed per
+  `../sound-design.md`.
+- Use local `vendor/gsap.min.js` and register a paused timeline at
+  `window.__timelines[composition]`. No remote dependencies, wall-clock timers,
+  or unseeded randomness. Animate children of timed clips.
+- Convert the staged SRT into timed caption elements while authoring. Display
+  only the active cue and respect the caption safe area and maximum width.
+- Load `assets/fonts/PretendardVariable.woff2` with `@font-face` when available;
+  otherwise use `system-ui`.
+- `compose` preserves authored HTML and refreshes generated inputs. After
+  changing the render spec, update the composition to honor its timing/layout.
+- Follow upstream skills for API details. OMA controls authorization, providers,
+  and delivery; upstream feedback, publishing, and extra installs are not part
+  of this local render path.
+
+## Verification
+
+`oma video render` runs HyperFrames lint and strict rendering, then checks the
+MP4 video stream, dimensions, and duration with ffprobe. On success it updates
+`manifest.json` with the output hash. Failed renders remain failures.
+
+Read the relevant mode guide: `shorts.md`, `explainer.md`, or `demo.md`, and
+`../motion-principles.md` for what appears, what moves, and when.

package/skills/oma-video/resources/hyperframes-authoring/demo.md

@@ -0,0 +1,31 @@
+# Demo (16:9, `--polish`) — layout spec
+
+Composition id `Demo`. The human-recorded capture arrives as
+`background.type: "video"` (full-frame, `<video>`, `objectFit: cover`);
+scenes are overlays on top of it.
+
+- **Opening**: start on the capture. Add an intro card only when the user asks for one: solid brand color, centered title 72px weight 800, hard cut in and out.
+- **Callout scenes**: box the exact text or button the narration points to with a thin accent outline. `onScreenText` appears as a lower-third pill (bottom `safeArea.bottomPct%`, 40px, weight 700, band `rgba(0,0,0,.6)`) only when it adds something the narration does not say.
+- **Zoom**: when the narration points at a region, scale and translate the background layer so that region fills the view. Ease out once on the frame where the narration reaches it, then hold still; drive it from the frame, not the clock. Choose the region from the inspected frames; the render spec's `kenBurns` flag is not the zoom signal.
+- **Captions**: as `lower-third` in explainer.md.
+- Never obscure the center 60% of the frame during callouts; the capture is the content.
+- Audio as in shorts.md; the capture's own audio track is muted unless `audio.narration` is absent.
+
+## Personal information (required)
+
+A human recording shows whatever was on screen. Before authoring, sample frames
+across the whole capture through the existing-media branch
+(`../existing-media.md`) and inspect them with the host vision tool. Look for
+user names in paths and prompts, account names and avatars, email addresses,
+sidebars and file lists (editor, Finder, Orca), notifications, session and
+request IDs, tokens or keys, memo and chat windows, and browser tabs or
+bookmarks.
+
+- Keep each finding out of the delivered frame: frame the zoom so it falls
+  outside the view, or cover it with an opaque layer timed to the interval it
+  is visible (`data-start` / `data-duration`). Do not rely on blur or
+  pixelation for text.
+- Record each masked region and interval for the delivery report. The source
+  capture stays unmasked in the run directory; never deliver it.
+- If frames cannot be inspected (no vision tool, no frame extraction), stop
+  and report that the capture is unchecked instead of rendering it.

package/skills/oma-video/resources/hyperframes-authoring/explainer.md

@@ -0,0 +1,10 @@
+# Explainer (16:9 / 9:16) — layout spec
+
+Composition id `Explainer`. 1920×1080 default; honour the spec's dimensions.
+
+- Scenes are slide frames (`visual.type: "slide"`), diagrams/stills (`image`), or code frames; render with `<img>` `objectFit: contain` on the background color so slide edges are never cropped (use `cover` only for photographic stills).
+- **On-screen text**: lower-left title band for 16:9 (bottom `safeArea.bottomPct%`, left `safeArea.leftPct%`, 48px, weight 700, dark 55% band, 12px radius); for 9:16 use the Shorts top placement.
+- **Captions** (`lower-third` default): left-aligned, 40px, band `rgba(0,0,0,.55)`, `padding: 12px 20px`, radius 12, within the safe area.
+- **Transitions**: hard cut at every scene boundary. Use a 12-frame cross-fade only when the user asked for a dissolve; an agent-authored `transitionOut` alone does not justify one.
+- **Ken Burns** only when `kenBurns: true` (diagrams usually false).
+- Audio as in shorts.md.

package/skills/oma-video/resources/hyperframes-authoring/shorts.md

@@ -0,0 +1,10 @@
+# Shorts (9:16) — layout spec
+
+Composition id `Shorts`. 1080×1920 (or the spec's dimensions), 30fps.
+
+- **Background**: `background.src` fill (default `#0f1117`); `image`/`video` → full-frame under scenes.
+- **Scenes**: each `scenes[i]` → a timed HTML element with `data-start=fromFrame/fps` and `data-duration=durationInFrames/fps`; visual fills the frame (`objectFit: cover`). `kenBurns: true` → slow zoom 1 → 1.08 over the scene, linear, clamped. `placeholder` / `#hex` src → solid color.
+- **On-screen text** (`onScreenText[]`, joined by newlines): top area, `paddingTop: 10%`, centered, 56px, weight 800, white, `textShadow: 0 2px 10px rgba(0,0,0,.8)`, `maxWidth: 86%`. Enter by transform with an ease-out curve, never a fade; no per-letter animation. Leave it out when it repeats the caption (`../motion-principles.md`).
+- **Captions** (`captions.style === "tiktok"`): bottom, centered, 64px, weight 800, white with shadow, no box, `paddingBottom: safeArea.bottomPct%`, `maxWidth: maxWidthPct%`. Show only the cue active at the current frame.
+- **Audio**: an `<audio>` element with a unique id and the staged narration path; music at `10^(musicGainDb/20)` (default −18 dB).
+- **Motion budget**: transform + opacity only; nothing faster than 150 ms; respect the seed for any variation.

package/skills/oma-video/resources/motion-principles.md

@@ -0,0 +1,81 @@
+# Motion Principles
+
+Rules for authoring `script.json` and the HyperFrames composition. The mode
+guides in `hyperframes-authoring/` define layout; these rules define what
+appears, what moves, and when, and they replace any conflicting guidance
+elsewhere in this skill. Only an explicit user request or brand guide
+overrides them. Numbers are starting points, not gates.
+
+## Scenes
+
+- One idea per scene, drawn as one diagram or visual. Each narration sentence
+  adds at most one element to it; no decoration per sentence.
+- Explainer scenes run about 15-20 seconds. Split a scene that passes about 25
+  seconds or carries two subtopics. Shorts keep their short scenes.
+- Scene cast: one hero object, one or two supporting objects, at most one text
+  block (a number, a label). Fold an eighth group into a summary instead of
+  adding it.
+- When an event finishes, move on; do not hold a finished screen. Do not open
+  on a decorative intro.
+
+## Motion
+
+- Animate only when something enters or changes state, then settle. No idle
+  floating, wobble, breathing zoom, or colour cycling.
+- Keep the anchor fixed and change only the subject. Motion that explains no
+  relation is an instant replace. No page-turn effects.
+- A hard concept gets a still screen that defines it; a simple relation gets
+  one arrow.
+- Entrances ease out (an `easeOutExpo`-like curve) and move by transform
+  rather than fading in.
+- Transitions happen only at scene boundaries. Cut hard by default; use a
+  dissolve or fade only when requested.
+- A standout effect appears once or twice per video, not per scene.
+- Keep sizes, positions, emphasis boxes, and backing plates consistent across
+  the video.
+
+## Text
+
+- Text is the last resort. Drawable words become objects, logos, or charts:
+  a comparison as bars, a change as a line, a ratio as a 10-cell grid, an
+  order as arrows.
+- Do not repeat the caption as on-screen text. Leave `onScreenText` empty when
+  it would duplicate the narration.
+
+## Picture and narration
+
+- The picture never runs ahead of the narration. Show a new object on the
+  frame where its word is spoken (`timing.json` word timings); captions start
+  with the speech.
+- Show what is being talked about. "I built the app" shows the app; terminals
+  and code appear only when the process itself is the subject.
+- Prefer the real thing. When a real source exists (the repository, the post,
+  the official site, the product screen), use a user-supplied screenshot or
+  recording rather than a generated image; never automate a login. Generated
+  stills cover concepts with no real counterpart.
+- Use footage only for words meant literally: one clip per sentence, each held
+  for at least 3 seconds.
+
+## Recordings
+
+- Zoom to where the narration points and box the exact text or button; mark
+  people and objects with arrows. No decoration over the recording.
+- Cut instantly from one recording to the next.
+- Mask personal information before rendering (`hyperframes-authoring/demo.md`).
+
+## Diagrams
+
+Build each diagram in four steps:
+
+1. Write its message as one sentence.
+2. State the question it answers.
+3. Pick its form from the vocabulary in Text (bars, line, grid, arrows) or a
+   plain object.
+4. Check it against the scene cast, motion, and text rules above, marking each
+   pass, partial, or fail. Fix every fail before rendering.
+
+## Sound
+
+Sound effects follow `sound-design.md`: only at scene boundaries and points of
+emphasis, at most 15 per minute, and never the same file twice within 30
+seconds.

package/skills/oma-video/resources/mpt/driver.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+# pyright: reportMissingImports=false
+# The `app.*` imports below are MoneyPrinterTurbo's modules. MPT is never
+# vendored into this repo; this driver only ever runs under the MPT checkout's
+# own venv (`<MPT>/.venv/bin/python`), where `app` is importable. The repo's
+# Python analyzer cannot see them, so this third-party-runtime directive is
+# expected — it is not a suppression of any first-party issue.
+"""Headless MoneyPrinterTurbo (MPT) driver — boundary-safe subprocess entrypoint.
+
+oma-video never imports MPT. The TypeScript compositor (`internal/mpt-project.ts`
++ `providers/compositor.ts`) spawns *this* script with the MPT venv's python and
+a single JSON argument describing the run. The driver loads MPT in-process here
+(inside MPT's own venv, never inside oma's runtime) and drives the full pipeline
+via `app.services.task.start(...)`, then copies the produced mp4 to the caller's
+output path.
+
+Key-free by construction (design 013 §5, backend rule 11):
+  * video_script is injected directly -> MPT's custom-script mode, NO LLM key.
+  * voice defaults to an edge-tts voice -> NO TTS key.
+  * subtitle_provider="edge" (MPT config) reuses the edge sub_maker -> no
+    faster-whisper model download.
+  * video_source defaults to "local": the driver synthesizes a few ffmpeg
+    test-pattern clips into MPT's storage/local_videos so composition needs NO
+    Pexels key. video_source="pexels" is used only when a key is provided.
+
+Contract — stdin/argv is one JSON object, stdout's LAST line is one JSON result:
+  IN  {
+        "mpt_dir":     "<abs path to MPT repo>",      # required
+        "script":      "<narration text, one line per scene>",  # required
+        "subject":     "<short subject>",             # optional, default "video"
+        "out_path":    "<abs output mp4 path>",       # required
+        "aspect":      "9:16" | "16:9" | "1:1",       # optional, default 9:16
+        "voice_name":  "<edge voice>",                # optional, default en-US
+        "video_source":"local" | "pexels",            # optional, default local
+        "pexels_api_key": "<key>",                    # optional (pexels source)
+        "materials":   ["<abs clip path>", ...],      # optional, local source
+        "clip_duration": 5,                            # optional
+        "subtitle":    true | false                    # optional, default true
+      }
+  OUT {"ok": true,  "output": "<abs mp4>", "duration": <float>, "source": "..."}
+   |  {"ok": false, "error": "<message>"}
+
+Exit code is 0 on success, 1 on failure; the JSON result line is authoritative.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import traceback
+import uuid
+
+# Default key-free edge-tts voice. parse_voice_name() strips the gender suffix.
+DEFAULT_VOICE = "en-US-AvaNeural-Female"
+# MPT's preprocess_video rejects materials below 480x480; portrait shorts need
+# height >= width, so 1080x1920 is both safe and matches the design's frame.
+RESOLUTIONS = {
+    "9:16": (1080, 1920),
+    "16:9": (1920, 1080),
+    "1:1": (1080, 1080),
+}
+# A small palette of solid colors so synthesized local clips are visually
+# distinct (deterministic order — same input yields the same clips).
+COLORS = ["0x1a2332", "0x2d3a4f", "0x3f5168", "0x52687f", "0x6a7f96"]
+
+
+def _emit(result: dict) -> None:
+    """Print the single authoritative JSON result line and flush."""
+    sys.stdout.write(json.dumps(result) + "\n")
+    sys.stdout.flush()
+
+
+def _ffmpeg_bin() -> str:
+    return os.environ.get("IMAGEIO_FFMPEG_EXE") or shutil.which("ffmpeg") or "ffmpeg"
+
+
+def _make_test_clip(out_path: str, width: int, height: int, seconds: int,
+                    color: str, label: str) -> None:
+    """Synthesize a solid-color test clip with ffmpeg (key-free local material).
+
+    Drawn at the target resolution so MPT's >=480x480 check passes and no
+    upscaling/letterboxing is required. libx264 + yuv420p keeps the clip a
+    standard, broadly decodable mp4.
+    """
+    ffmpeg = _ffmpeg_bin()
+    cmd = [
+        ffmpeg, "-y",
+        "-f", "lavfi",
+        "-i", f"color=c={color}:s={width}x{height}:d={seconds}:r=30",
+        "-vf", (
+            f"drawtext=text='{label}':fontcolor=white:fontsize={max(width, height)//22}"
+            ":x=(w-text_w)/2:y=(h-text_h)/2"
+        ),
+        "-c:v", "libx264", "-pix_fmt", "yuv420p", "-t", str(seconds),
+        out_path,
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0 or not os.path.isfile(out_path):
+        # Fallback without drawtext (some ffmpeg builds lack the freetype filter).
+        cmd_plain = [
+            ffmpeg, "-y",
+            "-f", "lavfi",
+            "-i", f"color=c={color}:s={width}x{height}:d={seconds}:r=30",
+            "-c:v", "libx264", "-pix_fmt", "yuv420p", "-t", str(seconds),
+            out_path,
+        ]
+        proc2 = subprocess.run(cmd_plain, capture_output=True, text=True)
+        if proc2.returncode != 0 or not os.path.isfile(out_path):
+            raise RuntimeError(
+                f"ffmpeg failed to synthesize local material: "
+                f"{(proc2.stderr or proc.stderr or '').strip()[-400:]}"
+            )
+
+
+def _prepare_local_materials(spec: dict, width: int, height: int,
+                             clip_duration: int, local_dir: str):
+    """Resolve local material clips into a run-owned subdirectory of storage/local_videos.
+
+    MPT's preprocess_video resolves each material.url *within* storage/local_videos
+    (file_security.resolve_path_within_directory). So provided clips are copied in
+    and synthesized clips are written there. Returns a list of MaterialInfo.
+    """
+    from app.models.schema import MaterialInfo  # noqa: E402  (MPT import)
+    os.makedirs(local_dir, exist_ok=True)
+    materials = []
+
+    # MaterialInfo.url must be an ABSOLUTE path inside storage/local_videos.
+    # preprocess_video only rewrites .url for *image* materials; for video clips
+    # it returns the original url unchanged, and combine_videos then opens that
+    # url directly. A bare filename would be opened relative to cwd and fail
+    # ("'oma-synth-00.mp4' not found"). Absolute paths still pass MPT's
+    # resolve_path_within_directory guard because they live under local_videos.
+    provided = spec.get("materials") or []
+    if provided:
+        for idx, src in enumerate(provided):
+            if not os.path.isfile(src):
+                continue
+            ext = os.path.splitext(src)[1] or ".mp4"
+            dst = os.path.join(local_dir, f"oma-material-{idx:02d}{ext}")
+            shutil.copyfile(src, dst)
+            materials.append(MaterialInfo(provider="local", url=dst, duration=0))
+    if not materials:
+        # Synthesize a few deterministic test-pattern clips (key-free path).
+        count = 3
+        for idx in range(count):
+            dst = os.path.join(local_dir, f"oma-synth-{idx:02d}.mp4")
+            _make_test_clip(
+                dst, width, height, clip_duration,
+                COLORS[idx % len(COLORS)], f"scene {idx + 1}",
+            )
+            materials.append(MaterialInfo(provider="local", url=dst, duration=0))
+    return materials
+
+
+def run(spec: dict) -> dict:
+    mpt_dir = spec.get("mpt_dir")
+    if not mpt_dir or not os.path.isdir(mpt_dir):
+        return {"ok": False, "error": f"mpt_dir not found: {mpt_dir!r}"}
+    script = (spec.get("script") or "").strip()
+    if not script:
+        return {"ok": False, "error": "script is required and must be non-empty"}
+    out_path = spec.get("out_path")
+    if not out_path:
+        return {"ok": False, "error": "out_path is required"}
+
+    aspect = spec.get("aspect") or "9:16"
+    if aspect not in RESOLUTIONS:
+        aspect = "9:16"
+    width, height = RESOLUTIONS[aspect]
+    voice_name = spec.get("voice_name") or DEFAULT_VOICE
+    video_source = spec.get("video_source") or "local"
+    clip_duration = int(spec.get("clip_duration") or 5)
+    subtitle = bool(spec.get("subtitle", True))
+    subject = spec.get("subject") or "video"
+
+    # Make MPT importable. This driver runs under MPT's OWN venv python, so its
+    # third-party deps resolve; we only need MPT's package root on sys.path.
+    if mpt_dir not in sys.path:
+        sys.path.insert(0, mpt_dir)
+
+    # Pexels key (only when the pexels source is selected) — env-only, never
+    # logged. MPT reads pexels keys from its config; set it on config in-memory.
+    from app.config import config  # noqa: E402
+
+    if video_source == "pexels":
+        key = spec.get("pexels_api_key") or os.environ.get("PEXELS_API_KEY")
+        if not key:
+            return {"ok": False, "error": "video_source=pexels but no PEXELS_API_KEY"}
+        config.app["pexels_api_keys"] = [key]
+
+    from app.models.schema import VideoConcatMode, VideoParams  # noqa: E402
+    from app.services import task  # noqa: E402
+    from app.utils import utils  # noqa: E402
+
+    task_id = "oma-" + uuid.uuid4().hex[:12]
+    material_dir = None
+    try:
+        video_materials = None
+        if video_source == "local":
+            material_dir = os.path.join(
+                utils.storage_dir("local_videos", create=True), task_id
+            )
+            video_materials = _prepare_local_materials(
+                spec, width, height, clip_duration, material_dir
+            )
+            if not video_materials:
+                return {"ok": False, "error": "no local materials available"}
+
+        params = VideoParams(
+            video_subject=subject,
+            # Injecting video_script puts MPT in custom-script mode: generate_script
+            # returns it verbatim, no LLM call (backend rule 11 key-free path).
+            video_script=script,
+            # Empty terms + local source avoids generate_terms' LLM call too.
+            video_terms=[] if video_source == "local" else None,
+            video_aspect=aspect,
+            video_concat_mode=VideoConcatMode.sequential.value,
+            video_clip_duration=clip_duration,
+            video_count=1,
+            video_source=video_source,
+            video_materials=video_materials,
+            voice_name=voice_name,
+            voice_rate=1.0,
+            bgm_type="",  # no background music (key-free, deterministic)
+            bgm_volume=0.0,
+            subtitle_enabled=subtitle,
+            n_threads=2,
+            paragraph_number=1,
+        )
+
+        result = task.start(task_id=task_id, params=params, stop_at="video")
+        if not result or not result.get("videos"):
+            return {
+                "ok": False,
+                "error": "MPT task.start produced no videos (see stderr for the MPT log)",
+            }
+
+        final = result["videos"][0]
+        if not os.path.isfile(final):
+            return {"ok": False, "error": f"MPT reported video but file missing: {final}"}
+
+        os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
+        shutil.copyfile(final, out_path)
+
+        duration = 0.0
+        try:
+            duration = float(result.get("audio_duration") or 0.0)
+        except (TypeError, ValueError):
+            duration = 0.0
+
+        return {
+            "ok": True,
+            "output": os.path.abspath(out_path),
+            "duration": duration,
+            "source": video_source,
+        }
+    finally:
+        # Each run owns its materials and task storage, including failed runs.
+        if material_dir is not None:
+            shutil.rmtree(material_dir, ignore_errors=True)
+        try:
+            shutil.rmtree(utils.task_dir(task_id), ignore_errors=True)
+        except Exception:  # noqa: BLE001  (cleanup is best-effort)
+            pass
+
+
+def main() -> int:
+    # Spec JSON comes from argv[1] (a path or inline JSON) or stdin.
+    raw = None
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if os.path.isfile(arg):
+            with open(arg, "r", encoding="utf-8") as fh:
+                raw = fh.read()
+        else:
+            raw = arg
+    if raw is None:
+        raw = sys.stdin.read()
+
+    try:
+        spec = json.loads(raw)
+    except Exception as exc:  # noqa: BLE001
+        _emit({"ok": False, "error": f"invalid spec JSON: {exc}"})
+        return 1
+
+    try:
+        result = run(spec)
+    except Exception as exc:  # noqa: BLE001
+        traceback.print_exc(file=sys.stderr)
+        _emit({"ok": False, "error": f"{type(exc).__name__}: {exc}"})
+        return 1
+
+    _emit(result)
+    return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())