THE BLACKCAT Montage Studio

# THE BLACKCAT Montage Studio

## Purpose

Turn a plain-language brief into a documentary-style montage: Pexels stock
footage + edge-tts voice-over (free) + a synthesized music bed + a branded end
card, composed with FFmpeg. Write a brief, pick a duration, press one button,
get a verified MP4.

## Clean-room note (license)

This is a **clean-room build**. It reuses only the validated *pattern* from the
private Montage Studio handoff (staged pipeline, JSON artifacts, per-slot
retrieval, output verification). It contains **no AGPL OpenMontage code,
schemas or prompts**. The four pipeline scripts in `scripts/` are the handoff's
own clean-room code, copied verbatim (Pexels retrieval, VO timeline, end card,
FFmpeg assembler).

## Pipeline (stages)

1. **Guion** - the brief is turned into narration beats (with start times) and
   stock slots (with queries + holds) by a template, no LLM call.
2. **Voz en off** - each beat is synthesized with edge-tts (free) and placed on
   a single timeline track.
3. **Clips** - `scripts/clip_search.py` downloads Pexels footage per slot; one
   clip per slot is auto-picked.
4. **Musica** - a soft ambient bed is synthesized with FFmpeg ($0, no key).
5. **Placa final** - `scripts/endcard.py` renders a branded PNG (BLACKCAT).
6. **Compose** - `scripts/assemble.py` grades, concatenates and mixes into the
   final MP4.
7. **Verificar** - ffprobe duration + video/audio streams + a non-black frame
   check before the job is marked done.

## Lesson L-OM-1 (the critical one)

The pilot's upstream render once reported `success=True` and delivered a black
30s MP4. This Studio **never trusts a success flag**: the compose stage runs
ffprobe (duration + streams) and extracts frames to confirm the video is not
black. If verification fails, the job fails honestly with the reason.

## Setup

Clips come from Pexels (free API). Connect a key once, from the Studio
(**Avanzado -> Conectar Pexels**). The key is read from `PEXELS_API_KEY` or a
local git-ignored file (`studios/montage-studio/.pexels-key`), validated
against the Pexels API before saving, and never committed. Without a key the
**Crear montage** button stays disabled.

## Launch

```bash
scripts/open-montage-studio.command
```

Then open `http://127.0.0.1:8780`.

## Usage

1. Write a brief (topic, what to tell).
2. Pick a duration: 30 / 60 / 90 seconds.
3. (Optional, Avanzado) tone, voice, output name, end-card text/hashtag.
4. Press **"Crear montage"**. Watch the stages, then play the video inline,
   download the MP4, or open the folder.

## Notes

- Output and intermediate media live in `output/` and `cache/` (git-ignored,
  local only). Never committed (`tests/test_no_media_leak.py` enforces it).
- v1 is Pexels-only stock and template-generated queries; curation is coarser
  than the hand-picked pilot. Better retrieval (LLM picks) is a v2 target.
- Cost per run: $0 (Pexels free tier + edge-tts + FFmpeg).