@remixmate/cli 0.1.0

package/skills/gen-voice/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: gen-voice
+description: |
+  Text-to-speech (TTS) skill: synthesize narration audio from text via ab-api's `/tool/minimaxT2aV2` endpoint (Minimax TTS).
+
+  Use this skill immediately whenever the user asks for any of:
+  - AI voice-over, TTS, text-to-speech, generate narration audio
+  - Use Minimax for speech synthesis
+  - Read a piece of text aloud / produce an audio file from text
+
+  Even when the user does not explicitly say "AI", any request that turns text into speech should route here.
+triggers:
+  - AI voice-over, TTS, text-to-speech, generate narration audio
+  - Use Minimax for speech synthesis
+  - Read a piece of text aloud / produce an audio file from text
+---
+
+# Text-to-Speech (TTS) Skill
+
+Wraps ab-api's `POST /tool/minimaxT2aV2` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, backed by the **Minimax TTS** model.
+
+## Auth & environment
+
+There is no skill-local env file — the executing process inherits the system environment. Examples below say `python`; on macOS you may need `python3`.
+
+- **Enterprise OpenClaw**: auth is already injected, **no need** to set `PRIV_TOKEN` / `--priv-token`.
+- **Other environments**: configure the token. See the Tianyan privateToken doc internally. Without a token, non-interactive runs fail; interactive runs prompt.
+
+| Env var | Description | Default |
+|---------|-------------|---------|
+| `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
+| `MM_API_BASE_URL` | API root | see `gen_voice.py` default |
+| `AGENT_NAME` | Optional `x-invoke-agent` header | none |
+
+## Operations
+
+> This skill was migrated from a Python script to an ab-skill CLI HTTP handler (`entry.type: http`). The agent invocation is unchanged (same tool name `gen_voice`, same params as in `skill.json`); local repro goes through `ab-skill gen-voice ...`. The legacy `--download` flag has been removed — audio URLs are persisted in the cloud and play directly.
+
+1. **Text**: confirm what to synthesize. Punctuation drives pauses (commas short, periods long).
+2. **Voice**: if the user prefers a specific voice, run `--list-voices` first and pick a matching id.
+3. **Output**: by default the audio URL is printed; add `--json-output` for a structured result that includes per-line subtitle timestamps.
+
+### List available voices
+
+```bash
+ab-skill gen-voice --list-voices
+```
+
+To inspect the local language-tagged fallback catalog used by the voice resolver (no remote API call), add `--local`:
+
+```bash
+ab-skill gen-voice --list-voices --local
+```
+
+The local catalog prints one voice per line as `<voice-id>\t<lang>\t<display-name>`.
+
+### Default synthesis (URL output)
+
+```bash
+ab-skill gen-voice --text "<text-to-synthesize>"
+```
+
+### With voice + speed
+
+```bash
+ab-skill gen-voice \
+  --text "<text-to-synthesize>" \
+  --voice-id "female-shaonv" \
+  --speed 1.2
+```
+
+### JSON output (with subtitle timestamps)
+
+```bash
+ab-skill gen-voice --text "<text-to-synthesize>" --json-output
+```
+
+## Common CLI flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--text` | Text to synthesize (required, except with `--list-voices`) | — |
+| `--voice-id` | Voice id (use `--list-voices` to discover) | `Chinese (Mandarin)_Male_Announcer` |
+| `--speed` | Speech rate, 0.5–2.0 | `1.0` |
+| `--list-voices` | List available voices and exit | — |
+| `--local` | Used with `--list-voices`: print the local fallback catalog (offline) | off |
+| `--json-output` | Emit JSON (url, audio_length_ms, subtitles) | off |
+| `--priv-token` | Override token | env var |
+
+## Speed guidance
+
+| Use case | Recommended speed |
+|----------|-------------------|
+| Reading / audiobook | 0.8–1.0 |
+| Voice-over / narration | 1.0–1.2 |
+| Fast announcement | 1.2–1.5 |
+
+## Error handling
+
+- **401** / **token missing** (non-OpenClaw): set `PRIV_TOKEN`.
+- **Business `code != 0`**: read `msg` on stderr.
+- **429**: rate-limited; retry later.
+- **Invalid voice id**: re-check via `--list-voices`.
+- **Network**: verify connectivity and `MM_API_BASE_URL`.

package/skills/gen-voice/skill.json

@@ -0,0 +1,21 @@
+{
+  "name": "gen-voice",
+  "toolName": "gen_voice",
+  "tier": "atomic",
+  "title": "Text-to-Speech (Minimax)",
+  "description": "Text-to-speech (TTS): synthesize narration audio from text via the Minimax TTS model. Returns the persisted audio URL — no download needed.",
+  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "AGENT_NAME"],
+  "entry": { "type": "http", "handler": "gen-voice" },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "text": { "type": "string", "description": "Text to synthesize (required)" },
+      "voice_id": { "type": "string", "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids." },
+      "speed": { "type": "number", "description": "Speech rate, 0.5-2.0" },
+      "list_voices": { "type": "boolean", "description": "List available voices and exit" },
+      "local": { "type": "boolean", "description": "Used together with list_voices=true: print the voice-resolver fallback catalog with language tags (no remote /voice/page call). Output is one '<id>\\t<lang>\\t<name>' line per voice." },
+      "json_output": { "type": "boolean", "description": "Emit a JSON result (url, audio_length_ms, subtitles)" }
+    },
+    "required": []
+  }
+}

package/skills/gen-voice/version.json

@@ -0,0 +1,7 @@
+{
+  "skillName": "gen-voice",
+  "repoName": "agent-skill-media-maker",
+  "skillId": "338",
+  "version": "V5",
+  "skillDescription": "语音合成（TTS）技能，将文字转为语音音频（调用 ab-api /tool/minimaxT2aV2，基于 Minimax TTS）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- AI 配音、语音合成、文字转语音、TTS、文本转音频、生成语音\n- 使用 minimax 语音合成\n- 用户想要将一段文字朗读出来、生成音频\n\n即使用户没有明确说「使用 AI」，只要他们想要将文字转为语音，也要使用本 skill。"
+}

package/skills/prepare-video-assets/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: prepare-video-assets
+description: |
+  Asset-preparation skill: resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a `job_id` for the subsequent `render_video` call.
+
+  Use this skill as soon as the user mentions any of these intents:
+  - Generate / prepare video assets, resolve assets, render-ready
+  - "Make me a video about X" (the agent calls gen_script → prepare_video_assets → render_video)
+  - Regenerate one asset (image / audio) for a specific scene
+
+  Next step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.
+triggers:
+  - Generate / prepare video assets
+  - Resolve missing assets in a DSL
+  - User confirmed the script and the agent needs to prepare assets for review
+  - User asks to regenerate a specific scene's image or narration
+---
+
+# Prepare Video Assets Skill
+
+Phase 1 of the two-phase video pipeline. Takes a Video DSL plus a template binding, walks every `AssetRef` declared in the DSL, calls the matching atomic skills to fill in missing assets (`gen-image`, `gen-voice`, `gen-video`, `gen-digital-human`), persists the resulting RenderPlan to ab-api, and prints a `job_id` for the user-confirmation step.
+
+> **Next step**: after the user reviews the assets and confirms, call **`render_video`** with the `job_id` returned by this skill.
+
+## Pipeline (this skill's part only)
+
+```
+DSL + template_id (or binding)
+    ↓
+[1] DSL Validator → schema check + normalize
+    ↓
+[2] Template Binder → produce RenderPlan
+    ↓
+[3] Asset Resolver → for every AssetRef, call atomic skills as needed
+    ↓
+[3b] Persist RenderPlan to DB → stdout "📦 render job jobId: N"
+    ↓
+(user reviews → confirms → render_video --job-id N)
+```
+
+## Atomic-skill dependencies
+
+The asset resolver invokes the following skills based on `AssetRef` declarations:
+
+| Asset type | Skill called | Notes |
+|------------|--------------|-------|
+| `image` + `source: gen-image` | `gen-image` | Text-to-image / image-to-image. |
+| `audio` + `source: gen-voice` | `gen-voice` | Narration TTS. |
+| `video` + `source: gen-video` | `gen-video` | AI-generated video clips. |
+| `avatar` + `source: gen-digital-human` | `gen-digital-human` | Talking-head digital-human segments. |
+
+## Authentication & environment
+
+| Env var | Description | Default |
+|---------|-------------|---------|
+| `PRIV_TOKEN` | Tianyan token (needed for asset generation + DB persist). | (none) |
+| `MM_API_BASE_URL` | Asset-generation API root (ab-agent proxy). | `http://localhost:3001/api` |
+| `MM_BACKEND_API_URL` | Backend API root (RenderPlan persistence). | `http://localhost:2999/api` |
+| `ASSET_CACHE_DIR` | Asset cache directory. | `./.asset-cache/` |
+
+## Canonical usage (inline DSL JSON, no temp files)
+
+```bash
+python3 <SkillDir>/scripts/prepare_video_assets.py \
+  --dsl-json '<DSL_JSON_STRING>' \
+  --template-id html-slide
+```
+
+- `<DSL_JSON_STRING>` is the JSON the agent received from `gen_script` — pass inline; **do not** write it to disk.
+- `--save-job` defaults to on, persisting the RenderPlan and printing `📦 render job jobId: N`.
+- Image and audio URLs are printed to stdout under `🔊 TTS audio:` and `🖼  Image assets:` sections.
+- When `PRIV_TOKEN` / `MM_BACKEND_API_URL` are missing the wrapper auto-degrades to file mode and prints a notice.
+
+## File-mode fallback (single-user / local debug)
+
+```bash
+python3 <SkillDir>/scripts/prepare_video_assets.py \
+  --dsl my-video.dsl.json \
+  --template-id html-slide
+```
+
+`--template-id` automatically calls template-bind internally; or pass `--binding my-video.binding.json` if you have a pre-generated binding.
+
+## Image-URL handling (agent rules)
+
+**DSL image assets must use HTTPS URLs.** During Remotion rendering, headless Chrome fetches the images directly over the network — no local download is needed.
+
+| Situation | Correct action |
+|-----------|----------------|
+| Image in a DSL AssetRef | Use the raw HTTPS URL. |
+| Showing an asset preview to the user | Use Markdown inline image syntax: `![name](https://...)`. **Do not** Read an HTTPS URL. |
+| Need to understand the image (to draft a title / bullets) | `curl` it down locally and read it; the DSL still carries the HTTPS URL. |
+| Avoid WebFetch on images | Internal-domain images are blocked by the WebFetch security policy. |
+
+## Pre-render user confirmation (Phase 2)
+
+This skill is the **first half** of a two-phase user-confirmation flow. After it returns, the agent must show the user the resolved assets and wait for confirmation before calling `render_video`. The recommended summary format:
+
+```markdown
+## Render confirmation
+
+### Video overview
+| Field | Value |
+|------|-----|
+| Title | ... |
+| Actual duration | xxs (after audio adjustment) |
+| Aspect ratio | 9:16 |
+| Scenes | x |
+
+### Scenes & assets
+| # | Purpose | Duration | Narration excerpt | Image | Audio |
+|---|---------|----------|--------------------|-------|-------|
+| 1 | opening | 6.2s | ... | ![scene-01](https://...) | [🔊 listen](http://cdn.../narration-scene-01.mp3) |
+| 2 | point   | 11.5s | ... | ![scene-02](https://...) | [🔊 listen](http://cdn.../narration-scene-02.mp3) |
+
+### Asset status
+- ✅ Images: x/x generated
+- ✅ TTS: x/x generated
+- ❌ Failed: list any failures
+
+> Reply "continue" to start rendering. To regenerate a specific asset, tell me which one.
+```
+
+## Regeneration pattern
+
+To regenerate a specific asset (e.g. the user is unhappy with scene 2's image):
+
+1. Update that scene's prompt / params in the DSL.
+2. Call this skill again with the updated `dsl_json` (or the minimal narration-override JSON when the gen_script skeleton is cached in the session).
+3. A new `job_id` is issued. Show the new assets and ask for confirmation again.
+4. After confirmation, call `render_video` with the **new** `job_id`.
+
+## Test mode: skip asset generation (`--stub-image-url` / `--stub-video-url`)
+
+During dev / debug the user may want to exercise the pipeline without burning gen-image / gen-video quota. With a stub URL set, every `image+source=gen-image` AssetRef (or `video+source=gen-video`) is short-circuited at the resolver to that URL — no generation request is sent. TTS is unaffected and always runs for real.
+
+### Usage rules
+
+- The URL is passed **verbatim**; do not rewrite it.
+- If the user expressed the intent but did not supply a URL, the agent must ask which fallback URL to use — never invent one.
+- The upstream `gen_script.py --stub-image-url / --stub-video-url` is the source-of-truth solution; this skill's flag is the render-layer safety net. Both layers can be enabled at the same time.
+- If the user does not re-state test mode in a later turn, **do not** carry the previous stub URL forward.
+
+### Command examples
+
+```bash
+python3 <SkillDir>/scripts/prepare_video_assets.py \
+  --dsl-json '<DSL_JSON_STRING>' \
+  --template-id picture-book-en \
+  --stub-image-url "https://cdn.example.com/placeholder.jpg"
+```
+
+Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is lower than the CLI flag.
+
+## Common CLI flags (inherited from render_video.py via the wrapper)
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dsl` | Input DSL file path. | — |
+| `--dsl-json` | DSL JSON as an inline string (preferred). | — |
+| `--template-id` | Template id (auto-bind). | — |
+| `--binding` | TemplateBinding file path. | — |
+| `--binding-json` | TemplateBinding JSON as an inline string. | — |
+| `--save-job` | Persist RenderPlan to the database; pass `--no-save-job` to disable. | **on by default** |
+| `--asset-cache-dir` | Asset cache directory. | `.asset-cache/` |
+| `--max-asset-retries` | Max retries per asset. | `3` |
+| `--asset-timeout` | Per-asset generation timeout (seconds). | `300` |
+| `--private-token` | Tianyan token. | env var |
+| `--stub-image-url` | Test mode: short-circuit image+source=gen-image assets to this URL. | — |
+| `--stub-video-url` | Test mode: short-circuit video+source=gen-video assets to this URL. | — |
+
+## Asset-resolution strategy
+
+The Asset Resolver handles each `AssetRef` in this order:
+
+1. **status = generated / approved**: asset is ready — use the URL as-is.
+2. **status = planned / missing**: call the matching atomic skill to generate it.
+3. **Generation failed**: retry up to `maxRetries`; final failures are recorded in the RenderPlan errors.
+4. **Parallel generation**: assets of the same type are generated in parallel; different types are sequenced by dependency.
+5. **Cache reuse**: assets with the same payload are checked against `asset-cache-dir` to avoid duplicate generation.
+
+## Error handling
+
+- **DSL validation failed**: pre-validate with `gen-script --validate`.
+- **Template not found**: confirm the templateId is in the registry.
+- **Asset generation failed**: inspect the RenderPlan `errors` field and the atomic skill logs.
+- **Stale skeleton**: if the agent submits gen_script's raw skeleton verbatim as `dsl_json`, the agent-layer precall rejects with a skeleton-placeholder error. Fill in real narration for every scene.
+
+## See also
+
+- **`render_video`** — the Phase 3 skill that consumes this skill's `job_id` and produces the final video.
+- **`template-bind`** — Lists available templates. Called internally by this skill when `--template-id` is provided.

package/skills/prepare-video-assets/scripts/prepare_video_assets.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Thin wrapper that delegates to the canonical render_video.py with --resolve-only forced on.
+
+The two-phase video pipeline shares one Python implementation:
+
+  prepare_video_assets  →  render_video.py --resolve-only ...  (this file)
+  render_video          →  render_video.py ...                 (sibling skill)
+
+By exec'ing the canonical script we get verbatim stdout / stderr / exit-code / signal forwarding
+without any subprocess wrapper layer. The agent layer's stdout parsing for the
+"📦 render job jobId: N" line therefore continues to work unchanged.
+
+The wrapper unconditionally injects --resolve-only as the first argument. The MCP tool schema for
+this skill excludes job_id / render_plan / resolve_only / upload_title / no_upload / renderer, so
+the LLM cannot push this entry point into Phase 3 territory; even if a shell caller passes those
+flags directly to this wrapper, --resolve-only still wins because asset-resolve-and-exit always
+short-circuits before the render step in render_video.py.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+
+def _canonical_script_path() -> str:
+    """Resolve the absolute path to the render-video skill's render_video.py.
+
+    Layout (relative to this file):
+        apps/ab-skill/skills/prepare-video-assets/scripts/prepare_video_assets.py  <-- HERE
+        apps/ab-skill/skills/render-video/scripts/render_video.py                  <-- target
+
+    The relative jump is ../../render-video/scripts/render_video.py.
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(
+        os.path.join(here, "..", "..", "render-video", "scripts", "render_video.py")
+    )
+
+
+def main() -> None:
+    script = _canonical_script_path()
+    if not os.path.isfile(script):
+        # Fail fast with a human-readable message rather than letting execv raise OSError.
+        print(
+            f"❌ prepare_video_assets wrapper could not locate the canonical render script.\n"
+            f"   Expected at: {script}\n"
+            f"   This indicates the render-video skill is missing from the skill tree.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    # Force --resolve-only into argv before any user-supplied flag.
+    forwarded = ["--resolve-only", *sys.argv[1:]]
+    os.execv(sys.executable, [sys.executable, script, *forwarded])
+
+
+if __name__ == "__main__":
+    main()

package/skills/prepare-video-assets/skill.json

@@ -0,0 +1,23 @@
+{
+  "name": "prepare-video-assets",
+  "toolName": "prepare_video_assets",
+  "tier": "orchestration",
+  "title": "Video Asset Preparation",
+  "description": "Resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a job_id for the subsequent render_video call. This is Phase 1 of the two-phase video pipeline; Phase 3 (Remotion render) lives in render_video.",
+  "envVars": ["PRIV_TOKEN", "MM_API_BASE_URL", "MM_BACKEND_API_URL", "AGENT_NAME", "REMOTION_RENDER_API_URL", "REMOTION_RENDER_MODE", "REMOTION_OUTPUT_DIR", "ASSET_CACHE_DIR"],
+  "scriptPath": "scripts/prepare_video_assets.py",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "dsl_json": { "type": "string", "description": "DSL JSON as an inline string (preferred — no disk write needed; required for multi-user concurrent flows). Pass the full DSL JSON, or — when a gen_script skeleton is cached in the session — a minimal JSON with only scenes[].audio.narration.text overrides (the agent layer merges narration onto the cached skeleton)." },
+      "dsl": { "type": "string", "description": "DSL file path (legacy fallback; prefer dsl_json inline)." },
+      "template_id": { "type": "string", "description": "Template id. When provided, the script invokes template-bind internally; no separate binding step is needed." },
+      "binding_json": { "type": "string", "description": "TemplateBinding JSON as an inline string (alternative to template_id; no file needed)." },
+      "binding": { "type": "string", "description": "TemplateBinding file path (optional; auto-generated when template_id is provided)." },
+      "save_job": { "type": "boolean", "description": "Persist the RenderPlan to the database (default true). On success the stdout contains '📦 render job jobId: N'. Auto-degrades to false when PRIV_TOKEN is missing, falling back to file mode. Pass false to opt out explicitly." },
+      "stub_image_url": { "type": "string", "description": "Test-mode image stub URL (renderer-side short-circuit). Only pass when the user explicitly says things like 'just testing / don't actually generate / use a placeholder image / save credits' AND provides a concrete URL. With this set, every image+source=gen-image AssetRef is short-circuited to that URL with no gen-image call. Do not pass otherwise; if the user expressed the intent without a URL, ask for one — do not invent one." },
+      "stub_video_url": { "type": "string", "description": "Test-mode video stub URL (renderer-side short-circuit). Only pass when the user explicitly says things like 'just testing / don't actually generate the video / use a placeholder clip / save credits' AND provides a concrete URL. With this set, every video+source=gen-video AssetRef is short-circuited to that URL with no gen-video call. Do not pass otherwise; if the user expressed the intent without a URL, ask for one — do not invent one." }
+    },
+    "required": []
+  }
+}

package/skills/prepare-video-assets/version.json

@@ -0,0 +1,7 @@
+{
+  "skillName": "prepare-video-assets",
+  "repoName": "agent-skill-media-maker",
+  "skillId": "476",
+  "version": "V1",
+  "skillDescription": "Asset-preparation skill (Phase 1 of the two-phase video pipeline). Resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a job_id for the subsequent render_video call."
+}

package/skills/render-video/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: render-video
+description: |
+  Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.
+
+  Use this skill as soon as the user mentions any of these intents (after assets are already prepared):
+  - Render the video, composite the video, export the video
+  - Turn the prepared assets into the final clip
+  - Render with Remotion
+
+  Prerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.
+triggers:
+  - Render the video, composite the video, export the video
+  - Turn the prepared assets into the final clip
+  - Render with Remotion
+  - Agent has a job_id from prepare_video_assets and needs the final video
+---
+
+# Render Video Skill
+
+Loads a persisted RenderPlan from the database (or a local file fallback), compiles the timeline, drives the **Remotion** engine, and emits the final playable video file.
+
+> **Prerequisite**: assets must already be generated via `prepare_video_assets`. That skill returns a `job_id` integer; pass it here.
+
+## Render pipeline (this skill's part only)
+
+```
+job_id  ─► RenderPlan loaded from DB
+              │
+              ▼
+       [4] Timeline Compiler ─► Remotion props + frame numbers
+              │
+              ▼
+       [5] Renderer ─► Remotion ─► MP4
+              │
+              ▼ (auto-upload by default; --no-upload skips)
+       [6] Uploader ─► Alibaba OSS ─► playback URL
+```
+
+Phases 1–3 (DSL validation, template binding, asset resolution) are owned by **`prepare_video_assets`**. This skill picks up at phase 4.
+
+## Authentication & environment
+
+Rendering supports two modes:
+
+- **local** (default if `REMOTION_RENDER_MODE` unset): runs Remotion CLI locally; requires Node.js 18+ and a headless Chrome.
+- **remote**: calls the standalone **remotion-renderer** service (at `<monorepo-root>/remotion-renderer/`) — best for environments without Node.js, long videos, or to avoid consuming local resources.
+
+| Env var | Description | Default |
+|---------|-------------|---------|
+| `PRIV_TOKEN` | Tianyan token (needed to load the RenderPlan from the DB and to upload). | (none) |
+| `MM_BACKEND_API_URL` | Backend API root URL (RenderPlan / VOD lookups). | `http://localhost:2999/api` |
+| `REMOTION_RENDER_API_URL` | Remote renderer base URL (ab-render). | `http://localhost:3000` |
+| `REMOTION_RENDER_MODE` | Default render mode (`remote` / `local`); CLI `--renderer` overrides it. | `remote` |
+| `REMOTION_OUTPUT_DIR` | Render output directory. | `./output/` |
+| `REMOTION_CONCURRENCY` | Local Remotion render concurrency. | `2` |
+| `ASSET_CACHE_DIR` | Asset cache directory (read-only for this skill — assets are already resolved). | `./.asset-cache/` |
+| `REMOTION_REMOTE_POLL_TIMEOUT` | Remote-render polling timeout (seconds). | `1800` |
+| `REMOTION_REMOTE_POLL_INTERVAL` | Remote-render polling interval (seconds). | `5` |
+
+## Canonical usage (database job mode)
+
+> ⚠️ **`job_id` must be a positive integer.** It is the value N from `prepare_video_assets`'s stdout line `📦 render job jobId: N`. Never pass `0`, a placeholder string, or descriptive text.
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --job-id <jobId>
+```
+
+`--save-job` is on by default. After the render, the Manifest is written back into the database under the same `jobId`.
+
+### Fallback: file mode (single-user / local debug)
+
+When the DB is unavailable, the script accepts a pre-generated RenderPlan file:
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --render-plan output/render-plan.json
+```
+
+### Render and upload to Alibaba Cloud OSS (default behavior)
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --job-id 42 --upload-title "My video"
+```
+
+After rendering, the script auto-uploads by default; `render-manifest.json` then contains an `upload.fileUrl` field. **Prefer `upload.playbackUrl`** (transcoded) over `upload.fileUrl` (raw VOD) when surfacing the URL to a user.
+
+### Render but skip the upload
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --job-id 42 --no-upload
+```
+
+### Upload an existing video standalone
+
+```bash
+python3 <SkillDir>/scripts/upload_video.py --file output/video.mp4 --title "My video"
+```
+
+`upload_video.py` is a standalone upload tool that uploads any local video file to Alibaba Cloud OSS and returns the usable URL. Use cases:
+
+- Manual upload after a `--no-upload` render.
+- Uploading video files not produced by Remotion.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--file` | Local video file path. | required |
+| `--title` | Upload title. | filename |
+| `--priv-token` | Override the token. | env var |
+
+### Specify the output path
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --job-id 42 --output final-video.mp4
+```
+
+## Common CLI flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--job-id` | RenderPlan job id loaded from the database (primary input). | — |
+| `--render-plan` | Existing RenderPlan file path (single-user / local debug fallback). | — |
+| `--save-job` | Persist Manifest to the database; pass `--no-save-job` to disable. | on (auto-degrades when token missing) |
+| `-o` / `--output` | Output video file path. | `output/video.mp4` |
+| `--asset-cache-dir` | Asset cache directory. | `.asset-cache/` |
+| `--private-token` | Tianyan token. | env var |
+| `--upload` | Auto-upload to Alibaba Cloud OSS after rendering (local mode only). | **on** |
+| `--no-upload` | Skip the upload (local mode only). | off |
+| `--upload-title` | Upload title (defaults to filename). | — |
+| `--renderer` | Render mode: `remote` (default) / `local`. | `remote` |
+| `--remote-poll-timeout` | Remote-render polling timeout (seconds). | `1800` |
+| `--remote-poll-interval` | Remote-render polling interval (seconds). | `5` |
+
+The script also accepts `--resolve-only`, `--dsl`, `--dsl-json`, `--template-id`, `--binding`, `--binding-json`, `--stub-image-url`, `--stub-video-url` for shell-level convenience and back-compat, but **the MCP tool surface of this skill exposes only the rendering parameters**. To resolve / regenerate assets, call `prepare_video_assets` instead.
+
+## Render outputs
+
+After rendering, the output directory contains:
+
+```
+output/
+├── video.mp4              # Final video
+├── render-plan.json       # RenderPlan snapshot
+├── render-manifest.json   # Render metadata (duration, resolution, frame count; includes upload.fileUrl by default)
+└── remotion-props.json    # The full props passed to Remotion (debug)
+```
+
+## Remote-render mode
+
+When to use:
+
+- The local machine does not have Node.js 18+ / headless Chrome.
+- Long or high-resolution videos where you do not want to tie up the local machine.
+- CI / batch rendering.
+
+### Example invocation
+
+```bash
+python3 <SkillDir>/scripts/render_video.py --job-id 42 --renderer remote --upload-title "Remote render test"
+```
+
+In remote mode:
+
+- `POST /render` returns a `taskId` immediately; the script polls `POST /renderStatus`.
+- **No** local `output/video.mp4` is produced (the MP4 is rendered on the server and uploaded directly to OSS).
+- `render-manifest.json.upload.fileUrl` comes from the remote response.
+- `render-plan.json` gains a `renderMode: "remote"` field and a `remoteTaskId`.
+- `--upload` / `--no-upload` are ineffective in remote mode (the server handles the upload).
+
+### Fallback on failure
+
+If the remote service is unreachable or auth fails, the script exits with a detailed message. Re-run the same `--job-id` with `--renderer local` as a fallback.
+
+### Service deployment
+
+The Remotion render project lives at the monorepo root under `<monorepo-root>/remotion-renderer/` and is deployed as a **standalone HTTP service**. The client script in this skill only sends POST requests and does not participate in server-side code sync.
+
+- Server code + deployment docs: `<monorepo-root>/remotion-renderer/README.md`.
+- Local debugging: in the renderer directory run `npm install && npm run server:dev`; the client defaults to `http://localhost:3000`.
+- Production: set `REMOTION_RENDER_API_URL` to the production base URL.
+
+## Error handling
+
+- **`job_id` missing or not assets-ready**: the script exits non-zero with a message like "render job N is not in assets-ready state". The agent should call `prepare_video_assets` again with the updated DSL to regenerate, then re-call this skill with the new `job_id`.
+- **DSL validation failed** (only reachable via `--render-plan` file mode if the plan is malformed): pre-validate with `gen-script --validate`.
+- **Remotion render failed**: check the Node.js version (18+ required). When deps are missing the script auto-runs `npm install`; if that fails, run it manually inside `<monorepo-root>/remotion-renderer/` (overridable via `REMOTION_RENDERER_DIR`).
+- **Remote render failed**: inspect `render-plan.json.errors` and the server log; fall back to `--renderer local` if needed.
+- **Timeouts**: remote rendering accepts `--remote-poll-timeout`.