---
name: video-generation
description: >
  Use this skill when working inside the video-generation repository and the task
  should go through its existing AI video pipelines instead of inventing a new
  workflow. Covers marketplace promo videos from Wildberries, Avito, or Ozon
  URLs; Telegram bot generation flows; direct runs through full_pipeline_v2.py;
  multi-scene microdrama and story adaptation with microdrama-v2; inspection of
  saved generations under /mnt/video; and provider-backed retry/debug tasks for
  Veo3, Kling, LaoZhang, and Pollo. Also use for запросы вроде "сделай ролик
  по карточке товара", "перегенерируй видео", "запусти микродраму", "найди
  удачные генерации", "подними видеобота".
---

# Video Generation

## Overview

This folder is a repo-specific AI video orchestration system with two main
production lanes:

- `scripts/` for short marketplace promo videos and Telegram bot delivery
- `microdrama-v2/` for staged multi-scene videos, sketches, and story adaptation

This repo does not contain one local video model that can be run offline. It
orchestrates external providers, stores prompts and logs on disk, and manages
generation state under `NFS_BASE` (usually `/mnt/video`).

Use this skill when the user wants video generation through the existing repo
implementation, not a fresh ad hoc pipeline.

## Use This Skill For

- generate a short product promo from a marketplace URL or product ID
- regenerate or inspect a previous generation from saved task artifacts
- run the main Telegram bot or the viewer/admin bot
- create a narrative multi-scene video, sketch, or episodic adaptation
- inspect provider fallback behavior, logs, or saved generations
- operate the repo's dev/prod services when the user asks for repo runtime work

## Do Not Use This Skill For

- generic mixed-asset montage work that does not need this repo's pipelines
- pure trimming, captioning, overlay, or reframing with no AI generation
- standalone voice synthesis
- generic scenario writing when the user only needs a scenario JSON

For those cases, hand off to sibling skills:

- scenario writing: [../story-gen/SKILL.md](../story-gen/SKILL.md)
- deterministic editing: [../ffmpeg-editing/SKILL.md](../ffmpeg-editing/SKILL.md)
- voiceover: [../voice/SKILL.md](../voice/SKILL.md)
- broad mixed-asset media work: [../SKILL.md](../SKILL.md)

## Preconditions

Before running generation flows, verify the environment instead of assuming it:

- `.env` exists or the needed env vars are set
- `LAOZHANG_KEY` is present for the main marketplace pipeline
- `POLLO_KEY` is present if provider fallback is expected
- `TELEGRAM_BOT_TOKEN` is present for `scripts/telegram_bot.py`
- `VIEWER_BOT_TOKEN` is present for `viewer/viewer_bot.py`
- `NFS_BASE` points to writable storage, default `/mnt/video`
- FFmpeg is available if you need validation or microdrama assembly

Optional but important:

- Sellematics tunnel improves marketplace data extraction quality
- Playwright/browser dependencies are needed for scraper fallback paths

## Choose The Lane

### 1. Marketplace Promo Video

Use this lane when the input is a Wildberries, Avito, or Ozon URL, or when the
user wants a short product commercial.

Primary files:

- `scripts/telegram_bot.py`
- `scripts/full_pipeline_v2.py`
- `scripts/url_detector.py`
- `scripts/generation_modes.py`

What this lane does:

1. Detect source and product ID from the URL.
2. Fetch product data through Sellematics when available, otherwise use scraper
   fallback.
3. Generate story vision, frame prompts, and the final motion prompt.
4. Generate video through LaoZhang Veo3 with fallbacks to Pollo Veo3, Pollo
   Kling, and then Kling Direct.
5. Save artifacts under `NFS_BASE/{source}_{product_id}/{task_id}/`.

Use the existing pipeline before inventing a custom prompt chain.

Direct command:

```bash
python3 scripts/full_pipeline_v2.py \
  --url "https://www.wildberries.ru/catalog/202372804/detail.aspx" \
  --output /mnt/video
```

Bot runtime:

```bash
python3 scripts/telegram_bot.py
```

Notes:

- The direct CLI is minimal and defaults to the standard pipeline path.
- Richer mode handling lives in code and the bot flow. If you need non-default
  behavior such as explicit mode selection or a custom wrapper around
  `run_pipeline_v2()`, prefer a short repo-local wrapper over rewriting the
  pipeline.
- Trust current code paths over stale README text. The core pipeline and bot
  support multiple marketplace sources even when some docs still say "WB only".

### 2. Microdrama / Story Adaptation

Use this lane when the user wants a multi-scene generated video, a sketch
channel workflow, or episodic adaptation from text.

Primary files:

- `microdrama-v2/scripts-v4/story_pipeline.py`
- `microdrama-v2/scripts-v4/orchestrator_v5.py`
- `microdrama-v2/scripts-v4/lib/video_providers.py`

Use `story_pipeline.py` for story-level setup:

- ingest source text
- build story bible
- define style
- create reference assets
- split into episodes
- prepare episodes

Use `orchestrator_v5.py` for episode-level production:

- scene and script stages
- frame generation and refinement
- per-scene video generation
- title cards
- captions
- final assembly

Minimal flow:

```bash
cd microdrama-v2/scripts-v4

python3 story_pipeline.py /mnt/video/microdrama-v3/my-project init /path/to/story.txt \
  --style "retro-futuristic cartoon"

python3 story_pipeline.py /mnt/video/microdrama-v3/my-project run
python3 story_pipeline.py /mnt/video/microdrama-v3/my-project run --accept
python3 story_pipeline.py /mnt/video/microdrama-v3/my-project prepare-episode 001

python3 orchestrator_v5.py /mnt/video/microdrama-v3/my-project --episode 001 run
```

Rules for this lane:

- Use story-level init/preparation before trying to brute-force episode work.
- Respect the iteration model. Create/select new iterations instead of
  overwriting prior outputs.
- Use microdrama for narrative or staged content; do not force it for simple
  marketplace commercials.

### 3. Existing Generation Inspection / Viewer / Admin

Use this lane when the user wants to browse past generations, search for good or
bad outputs, inspect errors, or manage tokens/showcase/admin tasks.

Primary files:

- `viewer/viewer_bot.py`
- `viewer/search.py`
- `viewer/data_reader.py`
- `scripts/database.py`
- `scripts/token_manager.py`

Viewer command:

```bash
python3 viewer/viewer_bot.py
```

Facts about this lane:

- Search is ripgrep-based over files under `NFS_BASE`.
- Product runs are read from saved generation folders and SQLite databases.
- Use this lane for repo-specific retrieval and admin work, not for generating
  new video concepts from scratch.

### 4. Service / Runtime Operations

Use this lane when the user asks to run, inspect, or troubleshoot the bot or
its supporting services.

Relevant files:

- `systemd/videobot-dev.service`
- `systemd/videobot-prod.service`
- `systemd/sellematics-tunnel.service`
- `systemd/nginx-videobot.conf`

Common commands:

```bash
systemctl --user status videobot-dev
systemctl --user restart videobot-dev
journalctl --user -u videobot-dev -f
sudo systemctl status videobot-prod
sudo systemctl status sellematics-tunnel
```

Only use this lane when the user actually needs repo runtime or deployment work.

## Data Layout

Marketplace pipeline outputs live under:

```text
NFS_BASE/{source}_{product_id}/{task_id}/
```

Typical files:

- `prompts/`
- `videos/video_generated.mp4`
- `videos/video.mp4`
- `generation.log`
- `pipeline.log`
- `metadata.json`

Microdrama projects keep state in the project directory:

- `story_pipeline.json`
- `continuity.json`
- episode directories like `001/`, `002/`
- per-episode `pipeline.json`
- stage folders with selected and historical iterations

Shared databases live under `NFS_BASE`:

- `videobot_dev.db`
- `videobot_prod.db`
- `showcase.db`

## Decision Rules

- Marketplace URL or product card request: use the marketplace pipeline.
- Narrative multi-scene or episodic request: use `microdrama-v2`.
- Pure retrieval, browsing, ratings, or token/admin question: use the viewer/admin lane.
- If the user needs a scenario first but not this repo's runtime, use
  [../story-gen/SKILL.md](../story-gen/SKILL.md) before this skill.
- If the user already has final clips and only needs deterministic editing, do
  not force this repo's AI generation flows.

## Verification

Before claiming success, gather repo-native evidence:

- confirm the expected output file exists
- inspect `generation.log`, `pipeline.log`, or stage metadata
- check recorded `errors` before saying the run succeeded
- use `ffprobe` on produced video when validating render outputs
- for microdrama, confirm the selected iteration or assembly state is written
- for service tasks, check process state or systemd status instead of assuming

## Known Constraints

- This repo depends on external AI providers. Treat network/API failures as
  normal operational cases, not surprises.
- Veo3 speech/audio is limited. Do not promise natural spoken dialogue.
- Sellematics requires a tunnel; scraper fallbacks can break or get blocked.
- Some docs describe earlier MVP behavior. Prefer current code entrypoints and
  logs over older README-era assumptions.
- `full_pipeline_v2.py` CLI is intentionally narrower than the underlying code.
  If the task needs richer control, extend with a small wrapper or use the bot
  flow instead of rewriting the pipeline.
