Python workflows and test environment

Basic CLI discovery and artifact management run on Node. Media helpers and specialist skills may also need Python, FFmpeg, fonts, model credentials or external tools. Check the selected skill's prerequisites before execution.

Contributor test environment

Use Python 3.12 or newer, matching the CI baseline. Some bundled rap-video helpers use Python 3.12 f-string syntax; the old 3.9/3.10 guidance does not cover the current suite. Exact dependency versions live in requirements-test.txt.

python3.12 -m venv .venv
npm run setup:test-python
npm run check:test-python

setup:test-python installs into the repository virtual environment, or an existing virtual environment selected by VCLAW_PYTHON_BIN. It refuses system Python and unsupported interpreters. It does not replace an existing environment. test:node uses the checked interpreter for its Python subprocesses too.

The full suite requires Pillow with RAQM text shaping for Devanagari and other combining scripts. Matching the Pillow version alone is insufficient. The preflight checks both. If the wheel on macOS lacks RAQM, this setup was verified during the September 2026 readiness review:

brew install libraqm
.venv/bin/python -m pip install --no-cache-dir --no-binary Pillow \
  --force-reinstall --config-settings raqm=enable Pillow==11.3.0
npm run check:test-python

Use the Pillow version pinned in requirements-test.txt if that pin changes. Other platforms need the corresponding development libraries when building Pillow from source. Missing script fonts are separate from missing shaping support. FFmpeg/ffprobe are also required for the full media test suite.

Legacy prompt pipeline (optional)

The skills/video-replicator/scripts/ directory ships an optional Python pipeline for Seedance-targeted prompt direction, character sheet generation, prompt critique, scene chaining via last-frame injection, and Omni Flash specific flows. It is not required for normal vclaw usage — the core CLI is pure Node/TypeScript. Use this pipeline when you want the deeper Seedance Prompt Director compose / chain / critique stack that originated in the legacy videoclaw repo.

Why it's opt-in

• The main vclaw binary is a Node 20.10+ CLI; basic discovery and artifact management do not need Python.
• Use Python 3.12+ for the current workflow tree. The legacy pipeline also depends on third-party packages (google-genai, requests, yt-dlp). Most users don't need these.
• Some files (notably seedance_prompt_db.py, 6.5k lines) carry forward the legacy curated-prompt database. Newer users should prefer the TypeScript surface (vclaw video prompt-lib-list / prompt-lib-show) documented in docs/CLI_REFERENCE.md.

Setup

cd skills/video-replicator/scripts
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Requirements (skills/video-replicator/scripts/requirements.txt):

• google-genai>=1.0.0 — Gemini API for video analysis
• requests>=2.31.0 — HTTP
• yt-dlp>=2024.1.0 — Video downloading

What's included

The following legacy modules are grouped by purpose; this is not a count of all current scripts or a claim that their external providers have been verified:

Seedance Prompt Director (core)

Module	Role
seedance_prompt_director.py	3-control-level prompt composer (foundation for the director workflow)
seedance_prompt_builder.py	Lower-level prompt assembly utilities
seedance_prompt_critique.py	Prompt critique with auto_fix_prompt rewrite suggestions
seedance_chain_manager.py	Multi-scene continuation via last-frame injection
seedance_reference_validator.py	Reference-image validation against scene needs
seedance_hooks.py	18 director hooks + 22 camera moves + 12 lighting presets + 4 timeline templates
seedance_consistency.py	Character-consistency scoring across scenes
seedance_material_library.py	Reusable material assets
seedance_platform_optimizer.py	Target-platform aspect/duration tuning
seedance_omni.py	Omni Flash specific T2V/R2V/V2V helpers
seedance_webhook.py	Webhook receiver for async generation
seedance_client.py	HTTP client + content-safety validators
seedance_prompt_db.py	Curated prompt library (legacy; see note above)

Character pipeline

Module	Role
character_sheet_generator.py	8-field character sheet generation from descriptions

Shared utilities

Module	Role
config.py	Centralized constants (timeouts, paths, model names)
exceptions.py	Shared exception types (SeedanceError, SeedanceTimeoutError, VideoProcessingError, MissingDependencyError)
logging_config.py	Logger initialization for the pipeline modules
ffmpeg_wrapper.py	Thin wrapper around ffmpeg / ffprobe subprocesses
audio_utils.py	Audio extraction, narration, mixing helpers
assembly_utils.py	Concat / encode / package helpers

Reference material

references/video/seedance-skills/ contains 15 genre-specific Seedance "skill" reference markdowns (cinematic, 3d-cgi, cartoon, comic-to-video, fight-scenes, motion-design-ad, ecommerce-ad, anime-action, product-360, music-video, social-hook, brand-story, fashion-lookbook, food-beverage, real-estate). These document compose / camera / lighting recipes per genre and are consumed by seedance_prompt_director.py.

Invoking from the TypeScript CLI

The pipeline runs as subprocesses; nothing in src/ imports Python. Typical pattern:

import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const exec = promisify(execFile);

const { stdout } = await exec(
  'python3',
  ['skills/video-replicator/scripts/seedance_prompt_director.py', '--compose', JSON.stringify(input)],
  { cwd: workspaceRoot, env: { ...process.env, PYTHONPATH: 'skills/video-replicator/scripts' } },
);
const result = JSON.parse(stdout);

These legacy modules can be invoked directly. Discover supported CLI commands with vclaw schema --json; director:compose is not a published command, and this guide makes no commitment to a future alias.

What this directory does NOT include

Everything from videoclaw/scripts/video/ that was either tightly coupled to the legacy orchestration layer (which v2 dropped) or duplicates functionality now in vclaw-cli/:

• db.py, db_unified.py, db_convex.py — legacy SQLite/Convex DB for the Python pipeline. Current queued production uses the Cinema task records; the optional Flow sidecar maintains its own provider/job state. See Operations for the supported queue.
• seedance_batch.py, seedance_backend.py — overlap with vclaw-cli backends.
• campaign_manifest.py, ugc_strategy.py, ugc_scripts.py — the legacy UGC scripts that the ugc skill rewrite explicitly moved away from (projects/<slug>/strategy/ directly + vclaw CLI now).
• ~80 other one-off .py files that didn't make the curated list.

If you need any of those, copy them in manually and add them here with a one-line note in this doc.

Tests

Current Python workflow behaviour is exercised through Node tests in src/tests/, including the rap planner, repair, timing and runner tests. Use the contributor environment above and the repository test commands. The presence of a test does not establish live provider readiness.

Legacy module validation

The original import-clean observation for this curated module set is historical. Recheck the modules and dependencies needed by your chosen workflow on the current interpreter. Do not treat that observation as current runtime or provider acceptance evidence.