teqo-backup/docs/plans/reels-narracao.md
Francisco Solla 161c49a260
Some checks are pending
Deploy / preflight (push) Waiting to run
Deploy / verify (push) Blocked by required conditions
Deploy / deploy staging (teqo-staging) (push) Blocked by required conditions
Deploy / requeue when main advanced (push) Blocked by required conditions
Deploy / deploy production (teqo-1313) (push) Blocked by required conditions
docs(C193,C194,C195,C196,C197): planos + designs hi-fi — reels de tutoriais do site (skill + biblioteca privada)
Related #1152,#1153,#1154,#1155,#1156
2026-09-18 16:45:28 -03:00

89 lines
7.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Skill de reels: narração rascunho (TTS pt-BR) + transcrição sempre
Status: rascunho
Atualizado em: 2026-09-18
Issue: #1156
Priority: P2
Impeccable: A — N/A sem UI
Design UI: N/A — sem UI
Appetite: ~1 dia eng; um outcome verificável — pacote com transcrição sempre e áudio rascunho opcional
Responsável: —
## Intenção
O ranking de valor dado pelo humano é explícito: o vídeo sozinho já ajuda; o texto da narração ajuda; o áudio, mais sucesso ainda. Este item completa o motor de reels do C196 com **voz e transcrição**: todo pacote sai com a transcrição do roteiro (`.srt` + `roteiro.md`) para a assessoria **regravar o áudio** ou acrescentar o áudio que quiser, e, quando o humano pedir, sai também um rascunho de narração em TTS pt-BR (`narracao.mp3`) e a variante do MP4 com esse áudio muxado. O vídeo continua sendo o formato primário; o áudio é rascunho, nunca voz clonada, e a decisão final do áudio é humana.
## Persona e fluxo
- **Persona / contexto:** assessoria de comunicação do mandato, sem editor de vídeo; produz o reel pela skill e entrega/usa a mídia nos canais.
- **Job principal:** ter o roteiro falado em mãos (para regravar) e, quando quiser, um áudio de rascunho já pronto na duração certa.
- **Fluxo desejado:** roda a skill do C196 e chega ao gate de áudio → o gate pergunta **com ou sem áudio** (padrão: sem áudio) → sem áudio: o pacote sai com `reel.mp4` + `narracao.srt` + `roteiro.md`; com áudio: além disso, `narracao.mp3` + `reel-audio.mp4` (mesma trilha de vídeo, áudio muxado) → a assessoria publica o que quiser; se preferir a própria voz, regrava lendo o `roteiro.md`/`narracao.srt` e troca o áudio sem re-renderizar o vídeo.
- **Anti-goals de produto:** não clona voz; não embute música licenciada; não publica em rede social; não é editor de áudio; não substitui a decisão humana sobre a voz final.
## Objetivo e aceite
- Transcrição **sempre** no pacote: `narracao.srt` com timecodes por beat e `roteiro.md` legível (fala + marcação de beat/cena).
- Com áudio: `narracao.mp3` separado e `reel-audio.mp4` ao lado do `reel.mp4` sem áudio; a trilha de vídeo das duas variantes é idêntica.
- Voz 100% TTS pt-BR institucional/rascunho; nenhum áudio do Solla é usado como referência ou clonagem.
- O áudio rascunho cabe na duração do vídeo (a pessoa consegue trocar o áudio sem re-renderizar o vídeo).
- O manifesto do pacote lista todos os arquivos gerados; a biblioteca (C194) baixa mp3, `.srt` e transcrição no detalhe do reel.
- Nenhuma publicação automática em rede social; música licenciada não é embutida.
## Dados (intenção)
- **Vou apresentar dados?** Não — áudio e texto do roteiro, sem superfície de dados.
- **Decisões desbloqueadas:** a assessoria decide se aproveita o rascunho ou regrava com a voz que quiser; a coordenação decide o que vai ao ar.
- **Forma:** _adiada ao plano de implementação_ — aqui só restrições de produto: transcrição sempre, áudio opcional, sem clonagem, sem música.
## Dados da decisão (literais)
- Transcrição **sempre** no pacote: `narracao.srt` (timecodes por beat) + `roteiro.md` legível (o que a assessoria usa para regravar).
- Áudio quando houver: `narracao.mp3` + `reel-audio.mp4` (mesma trilha de vídeo com o áudio muxado), ao lado do `reel.mp4` sem áudio.
- Voz: TTS pt-BR **institucional/rascunho**; **jamais clonar a voz do Solla**; o áudio final é decisão humana (a assessoria regrava ou aproveita o rascunho).
- A skill pergunta no gate se o pacote sai **com ou sem áudio**; o padrão é **sem áudio + transcrição** (a maioria assiste no mudo; a legenda queimada é o formato primário).
- Música: não embutir trilha licenciada (a assessoria usa o áudio do próprio Instagram); sem publicação automática em rede social.
- O texto narrado é o roteiro aprovado no gate — a skill não parafraseia por conta própria.
## Direção no codebase (hipótese)
- **Áreas prováveis:** um módulo de narração dentro do mesmo diretório da skill C196 (o dono do motor de reels), atrás de um adapter fino de TTS (provider decidido na implementação); sem pipeline paralela.
- **Precedente a olhar:** padrão ffmpeg do repo — array de args (nunca string de shell), `execFile` com timeout, `FFMPEG_PATH` override (`src/lib/speechCut.ts:157-195`, `src/utilities/speech/speechMediaPipeline.ts:18,73-97`); fixtures `tests/fixtures/fake-ffmpeg.mjs` e `tests/int/speechCut.int.spec.ts` como molde de teste; mux com `-c:v copy` (sem re-encode) e `+faststart`.
- **Risco de acoplamento:** não existe TTS no repo hoje (o único áudio é STT, em `src/app/(campaign)/campanha/api/ai-transcribe/route.ts`); `edge-tts` é Python e a workstation tem Python 3.12 mas não `pip`/`pipx` — a instalação/fornecedor entra como decisão de implementação, fail-closed se o provider faltar.
## Dependências
- **C196 (duro):** motor de reels, estrutura do pacote/manifesto e o gate onde a pergunta "com ou sem áudio?" entra.
- **C194 (soft):** o detalhe do reel já prevê os downloads de mp3, `.srt` e transcrição; este item produz os arquivos.
- **ffmpeg real** no ambiente (pré-requisito herdado do C196).
- **Decisão de fornecedor/instalação do TTS** (ver questões em aberto).
## Fora de escopo
- Clonagem de voz (deepfake) ou uso de gravações do Solla no TTS.
- Embutir música/trilha licenciada.
- Publicação automática no Instagram ou em qualquer rede (inclusive marcar `is_ai_generated` — a declaração, se necessária, é humana).
- Edição de áudio (cortes, mixagem, loudness avançado) e interface de gravação.
- STT/legenda automática a partir de fala — o reel é roteirizado; transcrição vem do shot list.
## Rabbit holes de produto
- **Polir a naturalidade do TTS além do "rascunho publicável".** O áudio é draft; a assessoria regrava. **Corte neste item:** inteligibilidade na duração certa.
- **Normalização de loudness e drift de duração.** **Corte neste item:** se o par `reel.mp4`/`reel-audio.mp4` sai consistente, refino depois.
- **Quebra de linha/timestamps perfeitos no `.srt`.** **Corte neste item:** um bloco por beat, simples.
- **Múltiplas takes/variações de narração.** **Corte neste item:** uma por render.
- **Waveform/preview de áudio na biblioteca.** **Corte neste item:** player/download; preview é outro item.
## Questões em aberto (produto)
- **Provider TTS?** **Opções:** A) `edge-tts` (grátis, sem key, vozes neurais Microsoft) | B) Google Cloud TTS (1M chars/mês grátis, ~US$16/1M depois) | C) Azure (500k/mês grátis) | D) ElevenLabs (melhor pt-BR, caro). **Recomendação:** A como rascunho (custo zero e sem credencial), com B/C como upgrade se a qualidade incomodar. OpenAI está reservado ao design no Teqo. _(assumido — validar com produto)_
- **Como instalar o TTS na workstation sem `pip`/`pipx`?** **Opções:** A) venv Python dedicado | B) provider HTTP com key no env | C) binário empacotado. **Recomendação:** A para `edge-tts` (sem key, isolado no venv); B se o provider escolhido for cloud. _(assumido)_
- **O gate deve permitir edição humana da narração antes do TTS?** **Opções:** A) não — narra o roteiro aprovado | B) sim, editar o texto falado. **Recomendação:** A no primeiro ciclo; a edição é no shot list. _(assumido)_
- **Formato do mp3 e do mux?** **Opções:** A) mono ~96–128 kbps, AAC no mp4 com `+faststart`. **Recomendação:** A — suficiente para rascunho e leve para download.
## Referências
- C196 (motor de reels), C194 (biblioteca) e C195 (ingestão) — planos irmãos.
- `src/lib/speechCut.ts:157-195` e `src/utilities/speech/speechMediaPipeline.ts:18,73-97` — padrão ffmpeg.
- `tests/fixtures/fake-ffmpeg.mjs`, `tests/int/speechCut.int.spec.ts` — molde de teste.
- `src/app/(campaign)/campanha/api/ai-transcribe/route.ts` — precedente de áudio (STT).
- Pesquisa web 2026-09-18: TTS pt-BR (`edge-tts`, Google, Azure, ElevenLabs) e `is_ai_generated` do Instagram.