@amaster.ai/pi-video-gen 0.1.18 → 0.1.19

package/skills/video-gen/references/remotion-handoff.md

@@ -0,0 +1,21 @@
+# Remotion handoff
+
+Use Remotion when the work needs exact text, UI, charts, editable React animation or frame control. Write an ordinary local Remotion project with an entry that calls `registerRoot()`. Install matching `remotion`, `@remotion/bundler`, `@remotion/renderer`, React and React DOM in that project. Provide an installed Chrome or Chromium binary through `browserExecutable` or `REMOTION_BROWSER_EXECUTABLE`. The plugin does not install packages or download a browser during a tool call.
+
+Write `<jobDir>/remotion-input.json` and call `video_compose({"composeSpecPath":".../remotion-input.json"})`:
+
+```json
+{"projectDir":"/absolute/path/remotion-project","compositionId":"Promo","assets":{"demo":"/absolute/path/demo.mp4"},"inputProps":{"title":"Product"}}
+```
+
+The project must be inside the trusted working directory. Set `entryPoint` to a project-relative file when the usual `src/index.ts`, `src/index.tsx`, `src/index.js` or `src/index.jsx` is missing or ambiguous. `assets` paths stay on the Node side. The plugin copies the project's original `public/` tree into the job snapshot, keeps relative paths such as `logo.png` and `fonts/brand.woff`, then copies injected assets into reserved `__pi_video_gen__/`. If the original public tree already uses this namespace, the call fails without overwriting it. The plugin passes `videoGenAssets: { demo: "__pi_video_gen__/demo.mp4" }` in `inputProps`; the composition uses `staticFile(videoGenAssets.demo)`. Ordinary `staticFile('logo.png')` and font references continue to work.
+
+Treat the configured video output directory as generated artifacts. Keep the Remotion entry and every source file it imports outside that directory; it is excluded from the frozen project fingerprint so sibling jobs cannot invalidate one another. The entry is checked and rejected if it is inside the output directory. Do not configure video output inside the project's `public/` tree.
+
+For `video_render`, use `assembly.type: "remotion"` with the same project fields. Every shot ID appears in `videoGenAssets` after download, and additional `assembly.assets` may be supplied under distinct IDs. Before a paid submission, the plugin builds a temporary public snapshot with browser-playable placeholder video and renders one frame. After download it rebuilds the snapshot with actual clips. Original project source, dependency files and original `public/` content are frozen separately from generated clip hashes; adding generated clips does not invalidate the paid input fingerprint.
+
+For batch `video_render`, the selected composition must expose `props.videoGenShotTimesSec`, a map from every shot ID to a time in seconds where that shot is visible in the finished film. Set it in `defaultProps` for a fixed edit, or return it from `calculateMetadata` when timing depends on the actual clips. The plugin checks the map during the placeholder preflight, then reads the actual map after rendering and extracts final QC frames at those times. The values must be finite and within the composition duration. Direct `video_compose` does not need this map.
+
+The final MP4 and assembly manifest live under `<jobDir>/assembly/` for `video_render`; direct `video_compose` writes them in its own job directory. Preserve the Remotion project as an editable deliverable. Inspect actual frames after rendering; a successful bundle and media probe do not establish visual correctness.
+
+Remotion has its own [license terms and FAQ](https://www.remotion.dev/docs/license/faq). The project owner should check the applicable terms before using this path in commercial automation. The plugin does not bundle Remotion code.

package/skills/video-gen/references/video-render-workflow.md

@@ -0,0 +1,23 @@
+# Render script and recovery
+
+Create `<outputDir>/<jobId>/render-input.json`. The job ID and each shot ID use letters, digits, dash or underscore. The parent directory is the immutable job. Use `video_generate` directly when batch automation and recovery are unnecessary.
+
+```json
+{
+  "title": "Mixed product film",
+  "style": "cinematic product demo",
+  "shots": [
+    {"id":"opening","prompt":{"visuals":"static medium shot","action":"presenter lifts the product"},"firstFramePath":"/absolute/path/opening.png","durationSec":5},
+    {"id":"demo","videoPath":"/absolute/path/demo.mp4"}
+  ],
+  "assembly": {"type":"remotion","projectDir":"/absolute/path/project","compositionId":"Promo"}
+}
+```
+
+Each shot has exactly one source. `videoPath` uses a local video and has no prompt, frame, reference asset or duration fields. A generated shot requires `firstFramePath` or a nonempty `referenceAssets` array, plus a structured `prompt` with `visuals` and `action`. `lastFramePath` requires `firstFramePath`. When using provider-managed reference assets without a first frame, also supply film-level `style` and shot-level `scene`; those prompt fields do not replace the visual input. The plugin snapshots local inputs, records remote task handles immediately and does not submit paid work again when resuming a finished shot.
+
+`assembly` is optional. Without it, clips are concatenated in shot order. For a local FFmpeg timeline, use `{"type":"timeline","timeline":{"segments":[{"id":"a","shotId":"opening","durationSec":5},{"id":"b","shotId":"demo","durationSec":5}]}}`; timeline segments may also carry supported overlay, narration and transition fields. Every segment must refer to an existing shot ID and must not supply a separate `video` or `image`. For Remotion, pass `projectDir`, `compositionId`, optional `entryPoint`, `inputProps`, `assets` and `browserExecutable`. The plugin supplies a `videoGenAssets` map keyed by shot ID and merges extra assets with distinct IDs.
+
+Before the first paid submit, the script checks all shot references, existing media, model capabilities and assembly environment. Remotion additionally bundles the project with placeholder video, selects the composition and renders frame zero. This does not prove that the eventual generated codec or duration is compatible; downloaded clips are checked again. If assembly fails after generation, rerun the same script after fixing the environment. The saved shot files and handles remain; changing frozen project source, original public resources, existing assets or the script requires a new job.
+
+Approval is scoped to the generated shots, provider/account, model and duration. Reuse an existing approval only for the same scope. On ambiguous remote submission, inspect the provider console, then use `/video-gen recover <jobId> <shotId> reset` only when the task is confirmed absent or `adopt <taskId>` when found. Cancellation stops local work and may not cancel provider billing. A legacy completed manifest without a saved final SHA-256 cannot verify the old film; compose its saved clips in a new job directory.