# 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`.

```bash
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:

```bash
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

```bash
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:

```typescript
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](OPERATIONS.md#durable-queued-work) 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.