Audio Intelligence: Como Construímos um QA Loop Determinístico com FFmpeg e LangGraph

Quando decidimos construir o QuickerSpot — uma plataforma SaaS de sonorização comercial inteligente e rádio indoor —, sabíamos que apenas conectar uma API de LLM a um motor de síntese de voz (TTS) não seria suficiente. No mundo real do varejo, áudios com volume descalibrado, músicas que engolem a voz do locutor ou vinhetas dessincronizadas arruinam a experiência de compra no ponto de venda.

Neste artigo técnico de Building in Public, compartilhamos a arquitetura do nosso motor de Audio Intelligence, detalhando como orquestramos grafos de estado no LangGraph, aplicamos Human-in-the-Loop (HITL) para blindar custos de API, utilizamos FFmpeg em pipeline assíncrono para mixagem com ducking dinâmico e implementamos um QA Loop Determinístico que valida decibéis (LUFS, SNR e gaps) antes que o áudio chegue ao alto-falante.

1. O Desafio: Por que IA Pura Falha na Produção de Áudio

Muitos pipelines modernos de inteligência artificial sofrem do que chamamos de "ilusão da inferência pura": a crença de que um único modelo generativo pode cuidar de ponta a ponta da redação, do casting de voz, dos efeitos sonoros e da masterização acústica.

Em nossos testes com centenas de peças comerciais reais geradas em produção, identificamos três gargalos críticos:

• Mascaramento Acústico: Trilhas de fundo competindo na mesma faixa de frequência da voz humana (1 kHz a 4 kHz), tornando o anúncio ininteligível.
• Gaps de Silêncio e Colisão de Efeitos: Efeitos sonoros (caixa registradora, moedas, sinos) disparados sobre a fala de preços ou posicionados com atrasos imprevisíveis.
• Inconsistência de Volume (Loudness Wars): Comerciais soando ora muito baixos, ora estourando nos sistemas de som das lojas físicas.

2. A Topologia do Grafo no LangGraph com HITL

Para resolver a orquestração multi-etapas com previsibilidade e controle de custos (FinOps de IA), construímos nosso backend em FastAPI sobre uma StateGraph do LangGraph:

[Input Sanitization] ➔ [generate_scripts] ➔ [Guardrails & HITL Pause]
                                                      │
                                          (Aprovação /resume)
                                                      ▼
[insert_effects] ➔ [select_track] ➔ [generate_audio (TTS)] ➔ [audio_mixer (FFmpeg)]
                                                                   │
                                                                   ▼
                                                         [validate_audio (QA Loop)]
                                                          ├── Score ≥ 0.80 ➔ [update_database] ➔ END
                                                          └── Score < 0.80 ➔ [audio_mixer] (Retry ≤ 2)

Human-in-the-Loop (HITL) para Economia de Créditos

A geração de áudio neural de alta fidelidade com provedores como a ElevenLabs representa o maior custo variável de uma plataforma de sonorização. Sintetizar o áudio antes da revisão humana geraria um desperdício massivo de créditos a cada ajuste textual.

Com o LangGraph, pausamos o grafo imediatamente após a etapa de roteirização usando um checkpointer SQLite persistente (MemorySaver). O estado da campanha fica salvo como PROCESSING. Quando o cliente revisa ou edita o roteiro na interface e clica em aprovar, o endpoint /resume acorda o grafo exatamente do ponto onde parou, executando o TTS apenas sobre o texto definitivo.

3. Regionalização Cultural Prompt-Driven (Sem Dicionários Rígidos)

Em vez de criar tabelas estáticas de palavras-chave ("se contiver peão ➔ sertanejo"), adotamos uma abordagem 100% prompt-driven com templates Jinja2 e modelos Gemini 2.5 Flash.

O agente de roteirização recebe super-prompts instruídos a analisar nuances culturais brasileiras e internacionais:

• Festas Juninas / São João: Injeção espontânea de bordões populares como "Olha a chuva! É mentira!", "Chegou o arraiá!" e menções a quentão, milho verde e forró.
• Festivais Sertanejos & Agro: Entonação caipira enérgica, termos como "Segura, peão!", "Queima do alho" e ritmo focado em churrasco e carnes.
• Carnaval & Verão: Ritmo acelerado com clima de micareta e celebração.

Essa mesma identificação semântica guia o nó select_track a escolher a trilha instrumental adequada dentro do nosso catálogo de 14 faixas de alta fidelidade ou orquestrar o Servidor MCP do QuickerSpot.

4. Processamento Acústico com FFmpeg & Ducking Dinâmico

A masterização do áudio ocorre em subprocessos assíncronos não-bloqueantes via FFmpeg. O pipeline aplica três etapas fundamentais:

1. Equalização & Compressão Vocal: Realce de presença vocal em 3 kHz e corte de frequências subsônicas, com limitador de pico em -1.5 dBFS.
2. Ducking Dinâmico com Sidechain: A música de fundo passa pelo filtro sidechaincompress, sendo atenuada suavemente (threshold: 0.15 a 0.20, ratio: 2.0 a 3.0) assim que a locução vocal é detectada.
3. Posicionamento Preciso de Efeitos (adelay): Os efeitos sonoros pontuais são inseridos nos timestamps exatos (com granularidade de milissegundos) extraídos dos metadados de alinhamento fonético do TTS.

5. O QA Loop Determinístico: Validando LUFS, SNR e Gaps

A grande inovação de engenharia introduzida na versão v1.4.0 é o nó validate_audio. Antes de salvar a peça final no Firebase Storage e no banco de dados, o áudio mixado passa por um sensor determinístico que executa três filtros do FFmpeg:

O sensor gera um relatório estruturado no modelo Pydantic AudioQualityReport com um Score Composto de 0.0 a 1.0:

• Score ≥ 0.80: O áudio é aprovado instantaneamente e salvo na nuvem.
• Score < 0.80: O relatório calcula automaticamente correções acústicas sugeridas (ex: aumentar o ducking ratio, elevar o ganho vocal) e devolve o estado para o nó audio_mixer, que re-mixa a peça aplicando os ajustes (com teto de 2 retentativas).

6. Resultados Práticos em Produção

Com a entrada em produção do Audio Intelligence:

Conclusão: Construindo Sistemas de IA Resilientes

Construir aplicações com Inteligência Artificial para o mundo real exige ir além da simples chamada de API. A combinação de **orquestração de agentes via LangGraph**, **sensores determinísticos via FFmpeg** e **resiliência com fallback de modelos** é o que transforma uma demonstração interessante em um produto de missão crítica escalável.

Se você é desenvolvedor, arquiteto de software ou varejista, convidamos você a testar a plataforma e integrar com nosso ecossistema.