---
name: video-factory-v5
description: >-
  Professional video editing pipeline implementing 20 classic + 10 modern (2026)
  editing rules. Rhythmic montage, beat-sync, audio ducking, Ken Burns,
  sound-first editing. Generates vertical 720x1280 shorts with AI music sync.
category: media
activation: >-
  Activate when user wants to create/edit/montage a video, especially short
  vertical format (Reels/TikTok/Shorts) with music sync.
---

# Video Factory v5 — Professional Video Editing Agent

## Overview

Full-stack video editing pipeline that implements **20 classic editing rules** (Eisenstein, Kuleshov, Scorsese, Edgar Wright, Fincher, Tarkovsky, etc.) and **10 modern 2026 rules** (Sound-First, Zero-Buffer, AI-assisted, Vertical-First).

Creates professional 30-60s vertical videos from raw clips with AI-synced music.

## Requirements

- `ffmpeg` with libx264, aac, drawtext (fontconfig)
- Python 3.8+
- Optional: Suno AI API proxy for music generation

## Quick Start

```bash
# 1. Put video clips in Input/
# 2. Put music in Music/ (or use Suno API to generate)
# 3. Configure NARRATIVE in the script (which clips tell what story)
# 4. Run:
python3 edit_montage_v5.py
```

## Script Location

The full script is at `edit_montage_v5.py` in the VideoFactory project directory (typically `~/Desktop/VideoFactory/`).

To deploy to a new location, copy the entire `edit_montage_v5.py` file and adjust the `INPUT`/`WORK`/`OUTPUT` paths.

## Implemented Editing Rules

### Classic Rules (implemented in code)
| # | Rule | Implementation |
|---|------|---------------|
| 1 | **Кулешов** — context from juxtaposition | `NARRATIVE` array defines clip order that creates meaning arc |
| 2 | **Пудовкин** — constructive editing (detail→action→conclusion) | 4-act narrative structure in code |
| 3 | **Скорсезе** — rhythmic editing to music | `analyse_music_energy()` finds BPM/peaks, aligns scene changes |
| 4 | **Эдгар Райт** — visual-music sync | `peak_frame` parameter tags clips on music drops |
| 5 | **Финчер** — invisible continuity | Ken Burns zoom + fade in/out smooth transitions |
| 6 | **Тарковский** — temporal flow | Long enough takes (2.5-4s) with slow zoom |
| 7 | **Вертов** — kino-glaz | Smart-select picks best motion moments from raw clips |
| 8 | **Гриффит** — parallel montage | Ready for multi-track (future: PIP split-screen) |

### Modern 2026 Rules
| # | Rule | Implementation |
|---|------|---------------|
| 1 | **Vertical-First** | Output 720×1280 portrait |
| 2 | **Sound-First** | Cuts timed to audio RMS energy peaks |
| 3 | **Zero-Buffer** | 2.5-4s per clip, no dead air |
| 4 | **Audio Ducking** | Music at 35%, ambient at 10%, dynamic mix |
| 5 | **AI-Assisted** | Suno API generates custom music per brief |
| 6 | **Smart Select** | ffmpeg scene-detection picks best clip segment |
| 7 | **Ken Burns** | Slow zoom from 1.0→1.03 over each clip |

## Structure

```
VideoFactory/
├── Input/          # Raw video clips (mp4, mov)
├── Work/           # Temporary seg_*.mp4 files
├── Output/         # Final montage_*.mp4 files
├── Music/          # Audio tracks (mp3)
└── edit_montage_v5.py  # The pipeline script
```

## Configuration

Edit these constants at the top of the script:

```python
W, H = 720, 1280        # Output resolution
CLIP_DUR = 2.5           # Seconds per clip
FADE = 0.3               # Crossfade duration
TOTAL_DUR = 30           # Total video length (seconds)

NARRATIVE = [            # Story structure: (act, theme, emotion, [filenames])
    ("Деталь", "В пути", "волнение", ["clip1.mp4", "clip2.mp4"]),
    ("Действие", "Море", "свобода", ["clip3.mp4"]),
    ("Вывод", "Дом", "тепло", ["clip4.mp4", "clip5.mp4"]),
]
```

## Music Integration

1. Place MP3 in `Music/` (name starts with `family_` for auto-detection)
2. Or use Suno API via proxy:

```bash
curl -X POST 'http://your-proxy:18999/api/v1/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "V3_5",
    "customMode": true,
    "prompt": "your music description",
    "instrumental": false,
    "style": "genre description",
    "customPrompt": "[Verse] lyrics here [Chorus] chorus here",
    "callBackUrl": "https://your-callback-server/suno-callback"
  }'
```

## For Other Agents (Kirill's setup)

- Copy `edit_montage_v5.py` to `~/Desktop/VideoFactory/`
- Adjust `INPUT`/`WORK`/`OUTPUT` paths if needed
- Ensure ffmpeg is installed
- If using Suno: set up the callback server (see `suno_callback_v2.py` as systemd service)

## Pitfalls

- `boxborder_w` not available in older ffmpeg — use `borderw` instead
- Russian characters in drawtext need escaping: `"'"` → `"\\'"`, `":"` → `"\\\\:"`
- zoompan filter must come BEFORE scale filter
- ffmpeg scene detection (gt=scene) is unreliable on crossfaded footage — use lower threshold
