Python Pipeline (opt-in)

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+ CLI with zero runtime Python dependencies.
• The Python pipeline targets Python 3.10+ and 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 -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

20 .py modules organized into four clusters:

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);

A future Phase will surface this as a first-class vclaw video director:compose subcommand. For now the modules are scriptable end-to-end and can be invoked directly.

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. The vclaw-cli SQLite store (vclaw-cli.db) is the single source of truth for batch/job tracking.
• 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

A focused subset of the original Python test harness will be ported in a follow-up pass — the v2 plan defers scripts/video/tests/ import to a phase-specific commit once we've decided which tests still apply.

Status

• All 20 modules: import-clean (verified with python3 -c "import <module>" for each).
• No runtime smoke yet — that requires real provider credentials.
• Subject to future cleanup: seedance_prompt_db.py will likely be retired in favor of the TypeScript vclaw video prompt-lib-* surface.