remotion-best-practices

What the source does

• FilesystemDeclared9 observations
• NetworkDeclared11 observations
• ShellDeclared6 observations
• DependenciesNot pinnedSome versions float
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: critical finding, no behavioural pass.

b64decode( ... subprocess.

fps = eval(fps_str) if "/" in str(fps_str) else float(fps_str or 30)

2. Read current .env values (which keys are set vs placeholder)

1. Read .env

1. Read the current .env file

# Read .env, update/add the key, write back

voice-design-ref.wav

await page.goto(`http://127.0.0.1:${server.address().port}/index.html`);

tone.wav

key = hashlib.sha1(f"{txt}|{size}|{hex_color}|{bold}".encode()).hexdigest()[:16]

key = hashlib.sha1(f"{txt}|{size}|{hex_color}".encode()).hexdigest()[:16]

key = hashlib.sha1(f"{txt}|{size}|{fill}".encode()).hexdigest()[:16]

key = hashlib.sha1(f"ph|{scene['slug']}|{accent}|{W}x{H}".encode()).hexdigest()[:16]

key = hashlib.sha1(f"{txt}|{size}|{fill}".encode()).hexdigest()[:16]

"  uv run ../../tools/ltx2.py --lora crt-terminal "

import { MazeDecoration } from '../../../lib/components';

} from '../../../../../lib/components';

} from '../../../../../lib/components';

import { useTheme } from '../../config/theme';

return Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGB")

Body=base64.b64decode(output_base64),

img = Image.open(io.BytesIO(base64.b64decode(b64)))

Body=base64.b64decode(output_base64),

img = Image.open(io.BytesIO(base64.b64decode(b64))).convert("RGB")

react, react-dom, @types/react, typescript

Audit 0.4.1 · source sha 11df17db21da · 29 Oct 2026Report an issue or request a re-scan

• Publisherdigitalsamba GitHub organizationOwner of the repository this skill is read from
• Source folderdigitalsamba/claude-code-video-toolkitThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict11df17db21daA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create professional videos autonomously using claude-code-video-toolkit — AI voiceovers, image generation, music, talking heads, and Remotion rendering.

---
name: video_toolkit
description: Create professional videos autonomously using claude-code-video-toolkit — AI voiceovers, image generation, music, talking heads, and Remotion rendering.
metadata:
  openclaw:
    emoji: "🎬"
    skillKey: "video-toolkit"
    os: ["darwin", "linux"]
    requires:
      bins: ["node", "python3", "ffmpeg", "npm"]
---

# Video Toolkit

Create professional explainer videos from a text brief. The toolkit uses open-source AI models on cloud GPUs (Modal or RunPod) for voiceover, image generation, music, and talking head animation. Remotion (React) handles composition and rendering.

## CRITICAL: Toolkit Path

The toolkit lives at a fixed path. **ALWAYS `cd` here before running any tool command.**

```bash
TOOLKIT=~/.openclaw/workspace/claude-code-video-toolkit
cd $TOOLKIT
```

**NEVER run tool commands from inside a project directory.** Tools resolve paths relative to the toolkit root.

## CRITICAL: Progress Reporting

**ALWAYS add `--progress json` to every cloud GPU tool command.** This gives you structured JSON Lines on stderr so you can monitor job status, detect stuck jobs, and report progress to the user in real-time.

```bash
# CORRECT — always include --progress json
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3 --progress json

# WRONG — no visibility into job status
uv run tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3
```

Tools that support `--progress json`: `music_gen.py`, `qwen3_tts.py`, `flux2.py`, `upscale.py`, `sadtalker.py`, `image_edit.py`, `dewatermark.py`, `ltx2.py`, `chain_video.py`.

See the **Progress Reporting** section below for output format and stage definitions.

## CRITICAL: Long-Running Tasks — Use yieldMs, Not background:true

**Any tool command that takes more than 30 seconds MUST use `exec` with `yieldMs` so you can report progress to the user live.** This includes: batch FLUX generation, chain_video, SadTalker, music generation, and any multi-scene pipeline.

```
exec command:"cd ~/.openclaw/workspace/claude-code-video-toolkit && uv run tools/chain_video.py --output-dir /path/ --progress json ..." yieldMs:10000
```

**The polling loop:**
1. `exec` with `yieldMs:10000` starts the command and returns control to you every 10 seconds
2. Read the `--progress json` output — look for `"stage":"item"` (scene complete) or `"stage":"complete"` (all done)
3. Report progress to the user ("Scene 05/30 complete, 17%")
4. Poll again: `process action:poll sessionId:<id>`
5. Repeat until `"stage":"complete"`

**Why:** Your agent run ends when you finish responding. If you use `bash background:true`, you lose the ability to report progress — the user sees silence until they nudge you. With `yieldMs`, you stay in the loop.

**NEVER do this:**
- `bash background:true command:"long running thing"` then promise to "monitor" — you can't, your run ends
- Break a batch into individual tool calls across separate messages — your run ends between each one
- Promise to "continue autonomously" — you literally cannot without an external trigger

## Setup

### Step 1: Check Current State

```bash
cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run tools/verify_setup.py
```

If everything shows `[x]`, skip to "Quick Test" below. Otherwise continue setup.

### Step 2: Install Python Dependencies

```bash
cd ~/.openclaw/workspace/claude-code-video-toolkit
uv sync
```

Note: `uv sync` creates its own `.venv/` from the lockfile, so it sidesteps Debian/Ubuntu's managed-Python restrictions (PEP 668) — no `--break-system-packages` needed. If `uv` is missing, install it first: `curl -LsSf https://astral.sh/uv/install.sh | sh`.

### Step 3: Configure Cloud GPU Endpoints

The toolkit needs cloud GPU endpoint URLs in `.env`. Check if `.env` exists and has Modal endpoints:

```bash
cat ~/.openclaw/workspace/claude-code-video-toolkit/.env | grep MODAL
```

If Modal endpoints are configured, you're ready. If not, **ask the user to provide Modal endpoint URLs** or set up Modal:

```bash
uv sync --extra modal
uv run modal setup   # Opens browser for authentication

# Deploy each tool — capture the endpoint URL from output
cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run modal deploy docker/modal-qwen3-tts/app.py
uv run modal deploy docker/modal-flux2/app.py
uv run modal deploy docker/modal-music-gen/app.py
uv run modal deploy docker/modal-sadtalker/app.py
uv run modal deploy docker/modal-image-edit/app.py
uv run modal deploy docker/modal-upscale/app.py
uv run modal deploy docker/modal-propainter/app.py
uv run modal deploy docker/modal-ltx2/app.py      # Requires: uv run modal secret create huggingface-token HF_TOKEN=hf_...
```

**LTX-2 prerequisite:** Before deploying LTX-2, create a HuggingFace secret and accept the [Gemma 3 license](https://huggingface.co/google/gemma-3-12b-it-qat-q4_0-unquantized):
```bash
uv run modal secret create huggingface-token HF_TOKEN=hf_your_read_access_token
```

Add each URL to `.env`:
```
ACEMUSIC_API_KEY=...                          # Free key from acemusic.ai/api-key (best music quality)
MODAL_QWEN3_TTS_ENDPOINT_URL=https://...modal.run
MODAL_FLUX2_ENDPOINT_URL=https://...modal.run
MODAL_MUSIC_GEN_ENDPOINT_URL=https://...modal.run
MODAL_SADTALKER_ENDPOINT_URL=https://...modal.run
MODAL_IMAGE_EDIT_ENDPOINT_URL=https://...modal.run
MODAL_UPSCALE_ENDPOINT_URL=https://...modal.run
MODAL_DEWATERMARK_ENDPOINT_URL=https://...modal.run
MODAL_LTX2_ENDPOINT_URL=https://...modal.run
```

Optional but recommended — Cloudflare R2 for reliable file transfer:
```
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=video-toolkit
```

### Step 4: Verify and Quick Test

```bash
cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run tools/verify_setup.py
```

All tools should show `[x]`. Then run a quick test to confirm the GPU pipeline works:

```bash
cd ~/.openclaw/workspace/claude-code-video-toolkit
uv run tools/qwen3_tts.py --text "Hello, this is a test."

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-29
   ✕BLOCK F 47 / 100

   first audit · source 11df17db21da

Questions about remotion-best-practices

• github.com/digitalsamba/claude-code-video-toolkit — the audited source at commit 11df17db21da and every finding aboveObserved · 29 Oct 2026

Spotted something wrong? Report a correction · Methodology