Playbook: Talking Head → Short

Objetivo: un vídeo talking-head (face-cam / monólogo) → Short vertical con captions y pack descargable, solo por API.

Prerrequisitos

• pnpm dev (Next en http://127.0.0.1:3000)
• pnpm worker (cola FFmpeg / ASR)
• STUDIO_API_TOKEN configurado
• Fichero de vídeo local (p. ej. .mp4)

export TOKEN="$STUDIO_API_TOKEN"
export BASE="http://127.0.0.1:3000"
export VIDEO="/path/to/talking-head.mp4"

1. Subir media (crea proyecto)

UPLOAD=$(curl -sS -X POST "$BASE/api/assets" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@${VIDEO}")

echo "$UPLOAD" | jq '{projectId: .project.id, assetId: .asset.id}'
PROJECT_ID=$(echo "$UPLOAD" | jq -r '.project.id')

Sin projectId en el form, el servidor crea proyecto + asset y devuelve { asset, project }.

2. Lanzar preset

Preset recomendado: talking-head-short (pack completo). Alternativa más corta: talking-head-short-mvp.

JOB=$(curl -sS -X POST "$BASE/api/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"projectId\":\"$PROJECT_ID\",\"presetId\":\"talking-head-short\",\"type\":\"pipeline\",\"bedMusicEnabled\":false}")

JOB_ID=$(echo "$JOB" | jq -r '.job.id')
echo "job=$JOB_ID status=$(echo "$JOB" | jq -r '.job.status')"

3. Poll hasta terminal

Estados útiles: queued → running → completed | failed | cancelled.
Algunos presets de highlights usan awaiting_review (no este playbook).

while true; do
  J=$(curl -sS -H "Authorization: Bearer $TOKEN" "$BASE/api/jobs/$JOB_ID")
  STATUS=$(echo "$J" | jq -r '.job.status')
  PROG=$(echo "$J" | jq -r '.job.progress')
  echo "status=$STATUS progress=$PROG"
  case "$STATUS" in
    completed|failed|cancelled) break ;;
  esac
  sleep 2
done

echo "$J" | jq '.job | {status, error, steps: [.steps[] | {key, status, progress}]}'

Si failed, mira el step con status: "failed" y usa retry.

4. Descargar artefactos

Allowlist típica del pack talking-head:

for f in output.mp4 captions.srt cover.jpg copy.json; do
  curl -fsS -H "Authorization: Bearer $TOKEN" \
    -o "$f" "$BASE/api/exports/$JOB_ID/$f" || echo "skip $f"
done

También vale ?token=$TOKEN en la URL si no puedes enviar Authorization.

5. Abrir en el editor (opcional)

UI: http://127.0.0.1:3000/edit/$PROJECT_ID — el timeline ya refleja mutaciones del pipeline.

Checklist de éxito

• Job completed sin steps failed
• output.mp4 descargable
• Worker estaba vivo durante el job (pnpm worker)

Qué no hacer

• No automatizar clics en Automate / timeline como camino principal.
• No inventar steps FFmpeg fuera de presetId / steps documentados.
• No asumir cloud ASR: el happy path es local (ver docs de ingeniería docs/ai/providers.md).