38 KiB
Impl: C200 — Separar falas por pessoa nas gravações enviadas
Status: aprovado Atualizado em: 2026-09-19 Issue: #1167 Intenção: docs/plans/acervo-separacao-por-pessoa.md Appetite restante: herdado (~2–3 dias eng; um outcome verificável — a assessoria identifica quem fala numa gravação enviada e filtra o acervo pelas falas de uma pessoa)
Leitura da intenção
- Outcome: gravações novas do acervo (fonte "Gravações enviadas", C199) passam a ter a transcrição dividida por agrupamento acústico ("Falante 1", "Falante 2", …); a assessoria ouve e usa "Identificar falante" para nomear um agrupamento, valendo para todas as falas dele naquela gravação; a lista ganha a faceta "Pessoa" que recorta as gravações onde aquele rótulo aparece. A busca geral continua cobrindo a transcrição inteira.
- O que NÃO negociar: agrupamento é acústico e a identificação é humana (nada de voiceprint, match voz↔pessoa, inferência ou sugestão automática); rótulo é texto por gravação, sem segundo cadastro de pessoa (
Contactintocado); rótulo não preenchido permanece "Falante N"; semConsentnovo (mídia interna de staff); sem score de confiança de "quem falou" na UI; gate fail-closed do acervo (communicator+coordinator/candidate;advisor/leadernegados); nada de backfill automático das gravações antigas; sem UI nova de reprocessar/diarizar fora do design aprovado. - O que reavaliar (hipóteses da intenção):
- "O import substitui os segmentos em bloco — um rótulo só sobrevive se o reprocessamento carregar/re-aplicar" (intenção): confirmado; a reconciliação é decisão desta impl (D6). Nota de realidade: hoje o lifecycle não tem caminho
ready → processing(retry sófailed, e falha não grava segmentos), então a reconciliação é um contrato do job testado no int, pronto para a ação futura de reprocessar/diarizar (§D8). - "A fonte enviadas já tem o padrão de chips/omnibox" (achado do explorador): não tem — hoje é só
CampaignSearchInput. A faceta nova reusa oCampaignHeaderFilterPopover(multi-seleção) com adaptação local, sem importar o omnibox da Câmara. - "Reusar o pipeline de transcrição por chunks para diarizar": não serve — chaves por chunk não se ligam entre chunks (ver D2).
- "Provedor de diarização" (questão em aberto da intenção): resolvido em D1/D2 (provedor externo, áudio inteiro numa passada) e registrado como GATE humano de custo/chave.
- "O import substitui os segmentos em bloco — um rótulo só sobrevive se o reprocessamento carregar/re-aplicar" (intenção): confirmado; a reconciliação é decisão desta impl (D6). Nota de realidade: hoje o lifecycle não tem caminho
Abordagem recomendada
flowchart TD
U[Upload C199] --> J[recordingJob]
J -->|"ffmpeg: mp3 mono 16k / chunks 20min"| W["Deep Infra Whisper<br/>deepInfraTranscribeSegments"]
W --> M[mergeChunkTranscriptions]
J -->|"se há provedor: full.mp3 numa passada ffmpeg"| D["AssemblyAI universal-2<br/>language_code=pt, speaker_labels"]
D -->|"utterances speaker/start/end"| A["assignSpeakerKeys<br/>alinhamento por sobreposicao"]
M --> A
A --> T[["tx: recordingSegment.speakerKey<br/>+ recording.speakerLabels reconciliadas"]]
D -.->|"falha, timeout ou sem chave"| F["fallback honesto:<br/>transcricao sem agrupamento"]
F --> T
T --> R[(recording / recordingSegment)]
L["Lista ?source=enviadas&person=..."] -->|"speakerNames contains"| R
P["Detalhe /gravacoes/id"] -->|"blocos por falante"| R
DLG["Dialogo Identificar falante"] -->|"POST /gravacoes/id/falantes"| AC[labelRecordingSpeakerForActor]
AC --> R
Opções consideradas: A | B | C em cada decisão abaixo.
Recomendação: manter o Whisper/Deep Infra como dono da transcrição e adicionar uma etapa opcional de diarização sobre o áudio inteiro (AssemblyAI, universal-2, speaker_labels), alinhando os turnos aos segmentos existentes por sobreposição de tempo; chave do agrupamento no recordingSegment, rótulos na recording com a faceta denormalizada em speakerNames (hasMany text + contains, precedente Speech.keywords); reconciliação conservadora de rótulos no job + aviso; sem provedor/chave, a transcrição sai sem agrupamento (nunca fingir separação).
Decisões de engenharia
D1 — Provedor de diarização (pesquisa web, números oficiais).
Opções: A) AssemblyAI | B) Deepgram | C) Gladia | D) Speechmatics | E) diarização local no homeserver | F) LLM de áudio | G) Deep Infra (atual)
Recomendação: A — AssemblyAI é o único com preço/hora mais baixo entre os verificados, aceita arquivos de até 10 h (cobre plenária inteira numa passada), tem pt com WER ≤10% declarado, diarização explícita no modelo universal-2 e fluxo assíncrono com polling (submit → poll), que é exatamente a forma do job C199 (heartbeat por atualização do updatedAt).
| Provedor | Diarização | Preço oficial (pré-gravado) | pt-BR | Limite por arquivo | Forma do fluxo |
|---|---|---|---|---|---|
| AssemblyAI | speaker_labels: true (universal-2, universal-3-5-pro) |
US$0,15/h (universal-2) + aditivo diarização standard +US$0,02/h = US$0,17/h ≈ US$0,0028/min |
pt com "high accuracy (≤10% WER)"; universal-3-5-pro cita dialeto pt-BR |
10 h por arquivo; 5 GB via URL/2,2 GB no /v2/upload |
POST /v2/upload → POST /v2/transcript → poll; utterances[] com speaker/start/end (ms) |
| Deepgram | diarize_model=latest |
Nova-3 pré-gravado US$0,0043/min = US$0,258/h (diarização incluída no pré-gravado) | pt-BR na lista do nova-3 |
não verificado nesta sessão | POST /v1/listen único e síncrono (ou callback) |
| Gladia | incluída (pyannoteAI Precision-2) | async US$0,61/h | 100+ idiomas | 135 min / 1 000 MB por request | upload → /v2/pre-recorded → poll |
| Speechmatics | incluída | Melia 1 batch a partir de US$0,129/h (em production preview oficial) | 55+ idiomas | batch, limites no portal | submit → poll |
| Deep Infra (atual) | não diariza — catálogo ASR verificado ao vivo (6 modelos, nenhum com diarização) | US$0,00045/min no Whisper large-v3 | pt | chunks de 20 min (C199) | já é o ASR do job |
| Local (pyannote/sherpa-onnx) | sim (montagem própria) | sem API; custo de ops/CPU/modelos | depende do modelo | — | processo/serviço Python no homeserver |
| LLM de áudio (Gemini/OpenAI) | não é diarização acústica | por token | sim | — | áudio inteiro ao LLM |
- A (recomendada):
utilities/ai/assemblyAiDiarize.tscomo dono do provedor (forma dedeepInfraTranscribe.ts),ASSEMBLYAI_API_KEYnova. A diarização roda só com chave; a política de delete do transcript remoto (DELETE /v2/transcript/{id}) é best-effort pós-leitura (higiene), e jamais se ligaspeech_understanding.speaker_identification(nome automático — proibido pelo guardrail). - Rejeitadas:
- B porque custa ~50% mais por hora (US$0,258 vs US$0,17) e é chamada síncrona de horas — sem o polling nativo que dá heartbeat barato ao job; qualidade comparável e pt-BR ok, então fica como alternativa de segunda escolha no gate.
- C porque o async aceita no máximo 135 min/1 000 MB por request (docs oficiais): uma plenária de horas exigiria fatiar e a numeração global entre fatias volta a ser um palpite (o problema que D2 elimina); além de ~3,6× o custo.
- D porque o modelo de menor preço (Melia 1) está em production preview oficial e o tier de maior acurácia (Enhanced) não publica um rate card único e estável nas fontes oficiais consultadas; sem vantagem decisiva sobre A.
- E porque o homeserver não tem GPU e montar pyannote/sherpa-onnx adiciona runtime Python, download de pesos e um domínio de falha de ops sem seam de teste; revisitar só com custo/volume material ou mudança de política de dados.
- F porque LLM de áudio atribui falante probabilisticamente (alucina atribuição e nome), não entrega turnos com timestamp confiável e colidiria com a regra OPS123 (provider
openai/*reservado a design no Teqo). - G porque capacidades verificadas: nenhum dos 6 modelos ASR do catálogo Deep Infra diariza; uma chave nova no mesmo provedor não resolve.
D2 — Escopo da diarização: áudio inteiro vs por chunk de 20 min.
Opções: A) uma passada no áudio inteiro | B) por chunk de 20 min com numeração global por ordem de primeira aparição | C) por chunk com re-associação por embedding entre chunks
Recomendação: A — o agrupamento é uma propriedade do áudio inteiro; diarizar por chunk gera chaves que não se ligam entre chunks e repetir "Falante 1" em cada chunk refere-se a pessoas diferentes (enganoso, contra o guardrail). O áudio extraído (mono 16 kHz, 32 kbps ≈ 14 MB/h) fica muito abaixo do limite de tamanho do provedor e dentro das 10 h de duração; acima de 10 h o job pula a diarização (fallback honesto).
- Rejeitadas: B porque "Falante N" por chunk com numeração global por ordem de aparição não garante a mesma pessoa (sem biometria não há re-associação) e mente para a assessoria; C porque re-associação por embedding é voiceprint — proibida pelo produto e pela intenção.
D3 — Papel do provedor: diarizar e alinhar vs substituir o ASR.
Opções: A) provedor só fornece turnos; alinhamento aos segmentos do Whisper | B) provedor passa a ser o ASR da gravação (utterances viram segmentos) | C) provedor só quando há chave; Whisper quando não há
Recomendação: A — o Whisper continua dono do texto, do searchText e dos timestamps por segmento (C199 pinado); o provedor entra apenas como camada de agrupamento. Falha do provedor não afeta a transcrição, e o alinhamento vira uma função pura testável sem rede.
- Rejeitadas: B porque troca o dono do texto, muda o custo do caminho feliz (~10× por minuto), reescreve a busca e faria a falha do provedor derrubar a transcrição inteira; C porque duas qualidades de transcrição no mesmo acervo sem o usuário saber, e dois donos do texto quebrando pinos C199.
D4 — Modelo de dados dos rótulos.
Opções: A) estado na recording (array speakerLabels) + speakerNames denormalizado (hasMany text) + chave no segmento | B) rótulo copiado em cada segmento | C) collection nova de rótulos | D) campo JSON
Recomendação: A — exatamente o que a tarefa fixou: recordingSegment.speakerKey (chave do agrupamento) + estado de rótulos na recording; a faceta "Pessoa" usa speakerNames (text hasMany → text[] no Postgres; precedente Activity.tags/Speech.keywords) com contains (ILIKE), funcionando no Payload 3.82.
- A:
speakerLabels: { speakerKey, label }[](readOnly no admin; uma linha por agrupamento identificado) e hookderiveSpeakerNamespreenchendospeakerNames(dedupe case-insensitive, ordem de aparição) — espelho deRecordingSegment.deriveSearchText.speakerLabelsDropped: booleanguarda o aviso de reconciliação (D6). Segmentos guardam só a chave. - Rejeitadas: B porque renomear um agrupamento tocaria N segmentos e a faceta viraria um join caro; C é collection nova para um estado 1:N simples (custo de access/index/migration sem ganho) e foge da direção da tarefa; D não tem validação/índice nem precedente de query de faceta.
D5 — Semântica da faceta "Pessoa".
Opções: A) { speakerNames: { contains: valor } }OR entre valores selecionados | B){ speakerNames: { in: valores } } exato | C) normalizar rótulo em slug na gravação
Recomendação: A — o precedente da casa (speechListFilters.ts:70, Speech.keywords contains) é case-insensitive e tolera variação ("Solla" casa "Dep. Jorge Solla"); a URL guarda o texto literal, a curadoria varia o rótulo e o recorte não fragmenta.
- Rejeitadas: B porque a variante livre ("Solla" vs "Dep. Jorge Solla") fragmentaria a faceta (anti-goal de curadoria acidental); C porque cria uma segunda representação do rótulo e um merge implícito que a intenção cortou.
D6 — Preservação de rótulos ao reprocessar.
Opções: A) reconciliação por sobreposição de tempo, conservadora 1:1, com flag + aviso | B) casar por igualdade de speakerKey | C) aceitar a perda silenciosa | D) bloquear o reprocessamento quando há rótulo
Recomendação: A — sem biometria não há re-associação entre execuções; carregar um rótulo só quando um agrupamento novo casa 1:1 por tempo com um antigo é o contrato honesto. Quem não casa fica sem nome e o job liga speakerLabelsDropped, que rende o aviso no detalhe.
- A: o job lê labels + segmentos antigos antes de apagar, computa
reconcileSpeakerLabels(puro: sobreposição acumulada por par, 1:1, ordenado por primeira aparição) dentro da mesma transação e gravaspeakerLabelsreconciliadas +speakerLabelsDropped. O aviso vive dentro do banner âmbar da Cena 4 (uma linha condicional — ver §UI). - Rejeitadas: B porque a chave é por execução e a mesma chave pode referir outra pessoa (o aceite manda re-vincular com aviso, não fingir); C viola o aceite; D porque o reprocessamento de hoje só existe para
failed(que não tem rótulo) e, na ação futura, bloquear sem alternativa é pior que reconciliar e avisar.
D7 — Fallback sem provedor/chave/timeout.
Opções: A) transcrição sem agrupamento (estado C199, sem "Falante") | B) falhar a gravação | C) criar um "Falante 1" único
Recomendação: A — o acervo continua útil e a ausência de blocos não afirma nada; é exatamente o detalhe C199 já aprovado, sem markup novo.
- Rejeitadas: B porque faz a transcrição (que não depende do provedor) depender de um custo humano ainda não aprovado; C porque sugere um falante único onde há vários — fingir separação, proibido.
D8 — Reprocessar/diarizar gravações antigas.
Opções: A) ação explícita por gravação agora | B) backfill automático | C) sem ação agora; follow-up com gatilho | D) UI de reprocessar junto com este item
Recomendação: C — a tarefa veta UI nova de reprocessar fora do design e a intenção veta backfill. A reconciliação (D6) fica pronta no job para quando a ação existir.
- Gatilho do follow-up: chave do provedor ativa em produção e (pedido operacional de diarizar o acervo antigo ou passarem ~30 gravações novas sem diarização). Aí o designer estende o artefato antes do markup (trigger a). Débito absorvido pelo D8 (triagem do /simplify): quando a ação de reprocessar existir, a semântica de limpar
speakerLabelsDroppedno rótulo precisa considerar rótulos ainda perdidos (hoje inalcançável: não háready → processing). - Débito absorvido pelo C202: a action de rótulo gateia no action-level com
canReadCommunicationCatalog(a collection já exigecanUploadRecording); a troca pelo predicado de escrita do dono foi adicionada ao planodocs/plans/gates-gravacoes-predicados.md(#1186). - Rejeitadas: B porque o custo e o risco de mexer em rótulos não justificam varrer tudo; A/D porque contrariam a restrição de superfície do item.
Componentes / mudanças
src/lib/recordingDiarization.ts(novo, puro/client-safe):DiarizedTurn,assignSpeakerKeys(sobreposição máxima; empate pelo ponto médio; sem sobreposição → turno mais próximo; numeração globalspeaker-1…por primeira aparição),reconcileSpeakerLabels(D6),speakerNamesFromLabels,recordingSpeakerDefaultLabel(n)→Falante ${n},RECORDING_DIARIZATION_MAX_SECONDS = 10h(limite do provedor citado em comentário). Mesmo padrão de dono dos puros delib/recordingTranscription.ts.src/lib/recordingTranscription.ts(editar):buildRecordingFullAudioFfmpegArgs(mp3 mono 16k/32k sem segmentação) ao lado do args de chunks; merge/searchText intocados.src/lib/recording.ts(editar):RECORDING_SPEAKER_LABEL_MAX_LENGTH = 120, mensagens pt-BR do diálogo/action, nada de status novo.src/utilities/ai/assemblyAiDiarize.ts(novo,server-only): dono do provedor (moldedeepInfraTranscribe.ts:98-137) — upload → transcript (language_code: 'pt',speaker_labels: true, sem identificação automática) → poll com deadline de 60 min e intervalo de 5 s; normalização ms→s; nunca lança ({ ok, turns }/{ ok:false, error, status });DELETEbest-effort do transcript; chave ausente → 503. ExportaassemblyAiDiarizeeconfiguredSpeakerDiarizer()(null sem chave).src/utilities/recordings/recordingJob.ts(editar):runRecordingJob(payload, id, transcribe = deepInfraTranscribeSegments, diarize = configuredSpeakerDiarizer()); extraifull.mp3só quandodiarizeexiste e a duração ≤ 10 h, chama o provedor (heartbeatstep:'transcribing'), alinha comassignSpeakerKeys, e na transação já existente (recordingJob.ts:191-227) lê o estado antigo, apaga/recria segmentos comspeakerKeye gravaspeakerLabels/speakerLabelsDropped. Falha/timeout do provedor não marcafailed.src/collections/Recording.ts(editar):speakerLabels(array{ speakerKey, label }, readOnly),speakerNames(texthasMany, readOnly),speakerLabelsDropped(checkbox, readOnly) + hookderiveSpeakerNames(fallbackoriginalDoccomoderiveSearchText).src/collections/RecordingSegment.ts(editar):speakerKey(text, opcional, readOnly).src/utilities/recordings/recordingListUrl.ts(editar): paramperson(repetível) noRecordingListState, parse comallParamValues+ trim + cap 120 + dedupe, serialize comappend,toggleRecordingPerson/removeRecordingPersonpuros (page reset) — o "adapter" da faceta mora aqui em vez de um módulo espelho despeechOmnibox.ts(depth check).src/utilities/recordings/recordingListFilters.ts(editar):buildRecordingListWhereAND-esearchText like+{ or: persons.map(p => ({ speakerNames: { contains: p } })) }.src/utilities/recordings/recordingViewModels.ts(editar):RecordingSpeakerGroupViewModel(key,index,defaultLabel,label,isIdentified,segments),RecordingDetailViewModel.speakerGroups+speakerLabelsDropped;RecordingListItemViewModel.matchedPersons; agrupamento por primeira aparição; caminho sem chave renderiza a lista plana C199.src/utilities/recordings/recordingPageData.ts(editar): selects (speakerNames,speakerLabels,speakerLabelsDropped,speakerKey),loadRecordingFilterOptions(select despeakerNamescompagination:false, dedupe e sort pt-BR — moldespeechPageData.ts:85-121),matchedPersonspor linha (purocontainscase-insensitive espelhando o where).src/app/(campaign)/campanha/actions/recording.ts(editar):labelRecordingSpeakerForActor({ recordingId, speakerKey, label })— gate pelo predicado de escrita do dono (C202, §Dependências), valida que a chave existe em algum segmento da gravação, faz read-modify-write do arrayspeakerLabelse limpaspeakerLabelsDropped(o ato humano reconhece/revisa); 1 collection → sem transação.src/lib/schemas/recording.ts(editar):recordingSpeakerLabelRequestSchema(id,speakerKey^speaker-\d{1,3}$, label 1..120 trim) + mensagens seguras.- Rotas (
.../acervo/gravacoes/[id]/falantes/route.ts, novo):POSTviacampaignJsonMutationRoute(sem allowlist de conventions — rota wrapper, não crua), molde de[id]/retry/route.ts;types.tsganhaRecordingSpeakerLabelResponse;lib/campaignPaths.tsganhacampaignRecordingSpeakersHref. - UI (
src/components/campaign/recording/):RecordingSpeakerTranscript.tsx(novo, client; blocos + banner âmbar + botões),RecordingSpeakerDialog.tsx(novo, client; moldeSpeechCutDeleteDialog+postCampaignJson),RecordingPersonFilter.tsx(novo, client;CampaignHeaderFilterPopover+useCampaignListFilterNavigation), edições emRecordingDetailPlayer.tsx(renderiza grupos quando existem; senão o<ol>atual),RecordingResultCard.tsx(chip de pessoa) eacervo/page.tsx(hidden inputs depersonno form de busca, linha da faceta, vazio com filtro). - Manifest e2e (
scripts/lib/e2e-affected-manifest.mjs): sem mudanças esperadas —src/utilities/ai(linhas 261-265) já mapeiacampaignSpeechAcervo, esrc/utilities/recordings/src/components/campaign/recording/src/lib/recording(322-336) já cobrem os arquivos novos; confirmar no gate. - Migration:
add_recording_speakers(abaixo). - Access / Consent: sem
Consentnovo;utilities/access/recordings.tsintocado neste item (C202 é o dono da ampliação de gate); a action de rótulo é a única superfície nova e usa o predicado de escrita do dono. - UI: Impeccable C — port do artefato + shells (
CampaignHeaderFilterPopover,CampaignListPendingBoundary,CampaignListEmptyState,CampaignListFooter,Dialog,Alert,Spinner); shape→craft→critique→polish no ciclo.
Dados → forma (se aplicável)
- N/A por decisão da intenção (
acervo-separacao-por-pessoa.md:59): filtro por pessoa é recorte de conteúdo, não métrica/agregado; nenhuma confiança numérica é exposta (o produto proíbe score de "quem falou"). Nada a apresentar; nenhuma forma nova.
UI e port do design (fonte de verdade: acervo-separacao-por-pessoa-ui-design.html)
Coberto pelo artefato — port classe-a-classe:
- Cena 1 (detalhe desktop, agrupado): grid
grid-cols-[minmax(0,1.05fr)_minmax(430px,.95fr)], mídia à esquerda (player +Baixar+ banner informativo literal "Os falantes são agrupados automaticamente pelo áudio. A identificação de cada pessoa é feita pela equipe.") e coluna direita com heading uppercase "Transcrição por falante", hint "Clique para posicionar" earticle.speaker-blockpor grupo: head (size-7avatar,Falante N/rótulo, sub "Agrupamento sem identificação"/"Identificação feita pela equipe", botão outline "Identificar falante"/"Editar identificação") e linhasseg(grid3.25rem 1fr,data-start-seconds, ativo combg-muted, hora emtext-primaryquando ativo, texto comSpeechHighlightParts). - Cena 2 (diálogo):
Dialogcom título "Identificar falante", descriçãoDê um nome ao agrupamento “Falante N”.(sempre o rótulo default), caixa informativa "Ouça um trecho e informe quem é a pessoa. O acervo não sugere nem identifica pessoas automaticamente.", label "Nome do falante", placeholder "Digite o nome do falante", helper "O nome será aplicado a todas as falas deste agrupamento nesta gravação.", botões "Cancelar"/"Salvar identificação"; erro inline (molde retry/delete),router.refresh()no sucesso. - Cena 3 (lista com faceta): mantém
RecordingsSearchForm(CampaignSearchInput, C199) com hidden inputs dospersonativos (submeter a busca não pode perder o filtro) e adiciona a linha de chips (botão outline "Pessoa: {rótulo}" com X) viaCampaignHeaderFilterPopovermulti-seleção; card com o chip{rótulo}+ "aparece nesta gravação" sob o excerpt. - Cena 4 (aviso de imprecisão): banner âmbar com título "A separação por falante pode estar imprecisa" e corpo "O agrupamento é automático e aproximado. Ruído e falas sobrepostas podem colocar trechos no agrupamento errado. A equipe continua responsável por identificar cada falante." — sempre visível no detalhe agrupado (sem score de qualidade, D1/anti-goal; o artefato não define gatilho). A linha condicional de reconciliação (D6) entra dentro desse mesmo banner quando
speakerLabelsDropped: "Esta gravação foi reprocessada e algumas identificações não puderam ser mantidas. Confira os falantes." — uma frase, sem componente/superfície nova. - Cena 5 (mobile 390 px): mesmo detalhe em coluna única, head compacto do bloco (avatar + nome + botão "Identificar"/ícone de edição com
aria-label"Editar identificação"), banner informativo curto literal "Agrupamento automático e aproximado. A identificação é feita pela equipe." e hint "Toque para posicionar".
Decisões de port fora do literal (baratas, revisáveis):
- Subtítulo da página na Cena 3 ("Gravações enviadas"): mantém o subtítulo aprovado do C199 ("Busque nas falas da Câmara ou nas gravações da equipe.") + alternador; a Cena 3 é shorthand do estado da fonte e mudar o chrome regride o pin do C199 sem ganho de produto.
- Vazio com filtro de pessoa: reusa
CampaignListEmptyStatecom a copy da casa ("Tente outro termo, remova filtros ou limpe a busca.") — estado não desenhado, shell aprovada. - Fallback sem agrupamento: renderiza o detalhe C199 como está (sem copy nova de "não diarizado"). A tarefa manda disparar o designer se precisarmos de superfície nova — não precisamos; se surgir demanda de explicar a ausência, é trigger a (designer antes do markup), registrado como follow-up (§D8).
- Dialog sobre grupo já identificado reusa a copy da Cena 2 com o rótulo default; o trigger é que muda ("Editar identificação").
role="tablist"inexistente aqui; o alternador C199 fica intocado.
Migration
- Nome:
pnpm migrate:create add_recording_speakers→ gera colunarecording_segment.speaker_key(text), tabelarecording_speaker_labels(id,_order,_parent_idFKrecordingcascade,speaker_key,label), colunarecording.speaker_names(text[]) erecording.speaker_labels_dropped(boolean). Revisar o SQL; sem índices novos (a faceta écontainssobretext[]em tabela pequena e oSpeech.keywordsnão tem índice dedicado). Referência de forma:20260715_163458_initial(arrays) e20260918_201009_add_reel. - HARD-STOP de aprovação humana explícita, mesmo em sessão
--auto, e local-only: criar/aplicar a migração apenas no banco local do worktree (pnpm migrate), nunca tocar banco remoto/prod e nunca editar migração antiga. Parar, apresentar o SQL gerado e aguardar aprovação antes de seguir para o job/UI.
Invariantes
- Local API em contexto de usuário sempre com
overrideAccess: false+user(lista, detalhe, action de rótulo); bypass admin só no pipeline que é dono do row, com comentário (formarecordingJob.ts:54-56). - Escrita multi-collection em transação com
req: { transactionID }(withPayloadTransaction): substituição de segmentos + estado de rótulos +searchText/status na mesma transação; a action de rótulo é 1 collection. - Sem
Consentnovo; semContact; rótulo é texto; nenhuma URL pública;/arquivoe matriz de papéis intocados. - Gate fail-closed do acervo; a escrita nova usa o predicado de escrita do dono (C202) — nunca
canReadCommunicationCataloggateando escrita;advisor/leadernegados (matriz no int/e2e). - Sem biometria/voiceprint/unificação entre gravações; sem score/confiança na UI; sem inferência de identidade.
- "Edit the owner, don't twin": puros no
libdono da pipeline, provedor noutilities/aidono, where/estado norecordings/, sem módulo top-level novo emsrc/utilities/. - Identificadores em inglês; copy/labels pt-BR; valores de URL em pt-BR só os existentes (
source=enviadas,falantes). pnpm generate:typesapós o schema;pnpm gate:fastdurante;pnpm pushcomo entrega; este plano edocs/changelog/2026-09-19-c200.mdentram no commit da entrega.
Fases verificáveis
- Puros + schema + migration (HARD-STOP) (~1 dia).
lib/recordingDiarization.ts,lib/recordingTranscription.ts(+full),recordings/recordingListUrl|Filters|ViewModels|PageData,lib/recording.ts, collections + hook;pnpm generate:types.- Unit: alinhamento (sobreposição, empate, sem sobreposição→mais próximo, vazio), numeração global por primeira aparição, reconciliação (1:1 carrega; split/merge/orfão dropa + flag),
speakerNamesderivado, guard de 10 h, ffmpeg args do full, parse/serializeperson(multi/dedupe/cap), wherecontains+q AND,matchedPersons. - Int: matriz de papéis e persistência das três colunas novas; validação da query da faceta
containsemtext[]no Payload 3.82 (precedenteSpeech.keywordseActivity.tags). - Migration
add_recording_speakers— HARD-STOP humano, local-only.
- Provedor + job + ação (~1 dia).
assemblyAiDiarize(seam injetável na assinatura do job), job com reconciliação na transação, action/rota/schema/paths.- Int: job com diarizador fake (feliz multi-chunk →
speakerKeypor segmento + labels preservadas; falha do provedor →readysem agrupamento; reconciliação com fixtures antigas; chave inexistente → fallback),labelRecordingSpeakerForActor(papéis; chave desconhecida; label vazio/longo; limpaspeakerLabelsDropped), sem chamada real de rede.
- UI (~1 dia).
- Cenas 1–5 + hidden inputs + faceta + cards; ação de rótulo no diálogo.
- Unit: view models dos grupos (ordem,
Falante N, rótulo aplicado, flag), cena/copy constants; e2e cobre o markup.
- Gates + GATE humano (~0.5 dia).
- Estender
tests/e2e/campaignSpeechAcervo.e2e.spec.ts(describe C199): fixturereadycom segmentos comspeakerKey+speakerLabels; detalhe renderiza blocos/"Falante N"/rótulo/aviso; lista?person=recorta e o card mostra o chip; fallback semspeakerKeymantémdata-start-secondsdo C199; advisor negado na rota nova. pnpm gate:fast;pnpm test:e2e:affected; manifest/conventions (confirmar sem mudança); smoke manual do provedor com 1 gravação real (chave aprovada); changelog; push.
- Estender
Quota: ~3–3,5 dias eng, dentro do appetite herdado; se apertar, o corte é o polish do port (a estrutura das cenas 1/2/3 fica antes do acabamento).
Rabbit holes / Não escopo (engenharia)
- Voiceprint/embedding para re-associar falantes entre execuções/gravações; unificação automática de "mesma pessoa".
- Cadastro/diretório de pessoas ou vozes; qualquer uso de
Contact. - Edição/correção de transcrição, alinhamento por palavra, refino de sobreposição.
- Backfill de diarização do acervo antigo e UI de "Diarizar" (follow-up com gatilho, §D8).
- Multi-provedor/adapter genérico de diarização (uma interface, um provedor — sem volatilidade que justifique mais).
- Webhook/callback do provedor (o poll do job basta; callback criaria superfície pública nova).
- Score/confiança de falante na UI (proibido); detecção automática de "qualidade ruim".
- Fila/worker, tempo real, streaming, cortes por falante, busca semântica (C192) e merge de fontes.
Riscos e mitigação
- Custo/chave do provedor não aprovados (GATE). Sem chave, tudo degrada para a transcrição sem agrupamento (D7); a feature nova só liga após a aprovação — nenhum teste depende de rede.
speaker_labelsnão suportado paraptna conta real. Os docs oficiais da AssemblyAI listamptcom alta acurácia nouniversal-2e diarização nos modelosuniversal-2/universal-3-5-pro, mas a matriz feature×idioma não é pública: smoke manual na fase 4 antes do rollout; falha honesta = fallback.- Qualidade do agrupamento em plenária ruidosa/sobreposta. Banner da Cena 4 sempre visível + identificação humana + nenhum claim automático; a copy do provedor recomenda ≥30 s de fala por pessoa (citada nos docs).
- Diarização > 10 h ou timeout de poll. Guard de duração + deadline de 60 min com heartbeat; resultado = fallback sem agrupamento, nunca
failed. - Alinhamento errado na fronteira de turnos. Atribuição por sobreposição máxima com desempate pelo ponto médio; unidade cobre; aviso de imprecisão cobre o resto.
- Reconciliação conservadora demais (rótulo perdido). Só perde quando não há mapeamento 1:1;
speakerLabelsDroppeddispara o aviso; teste int garante carregar no caso trivial (mesmos tempos). - Corrida no read-modify-write de
speakerLabels. Aceita para ferramenta interna de equipe única (uma gravação editada por vez na prática); se doer, collection dedicada de rótulos é o follow-up. - Faceta cara conforme o catálogo cresce. Select de
speakerNames+ dedupe é O(n) com n pequeno; gatilho: acervo > ~2 000 gravações ou opções > ~200 (pré-computar opções/distinct). - Regressão do C199. O caminho sem
speakerKeymantém o markup exato do<ol>atual; os testes C199 (unit/int/e2e) continuam a rede. - Vazamento de dados ao provedor externo. Áudio de eventos públicos da equipe, sem PII de terceiros; delete best-effort do transcript remoto; política de retenção validada no gate.
GATE humano — provedor, custo e chave (assumido; validar antes do rollout)
- Assumido: provedor AssemblyAI (
universal-2+speaker_labels), custo US$0,17/h de áudio (US$0,0028/min) — fonte oficial: pricing AssemblyAI (Universal-2 US$0,15/h; diarização async standard +US$0,02/h) e docs de Speaker Diarization/limites (10 h, 5 GB; upload 2,2 GB). - Custo projetado: 10 h/mês ≈ US$1,70; 50 h/mês ≈ US$8,50; 200 h/mês ≈ US$34,00.
- Pendente de aprovação humana (mesmo com
--auto): criar conta/chave na AssemblyAI, definirASSEMBLYAI_API_KEYno env de produção (e staging se desejado), aceitar o envio do áudio a terceiro e o orçamento acima; rodar o smoke real. Nada disso bloqueia a implementação (seam injetável + testes sem rede); bloqueia só o rollout. - Alternativa registrada no gate: Deepgram (US$0,0043/min = US$0,258/h, diarização incluída, pt-BR) — se a aprovação preferir chamada síncrona única; a troca exige só um novo dono em
utilities/ai/(a interface do seam não muda).
Aceite de engenharia
- Aceite de produto da intenção coberto: transcrição dividida por "Falante N" nas gravações novas com provedor; "Identificar falante" vale para todo o agrupamento; faceta "Pessoa" recorta a fonte enviadas; busca geral intocada; rótulo vazio permanece "Falante N"; nunca sugere/infere identidade; reprocessar não perde rótulo sem re-vinculação avisada; antigas não são reprocessadas automaticamente.
- Invariantes AGENTS/engineering-standards:
overrideAccess:false+user; transação multi-collection; semConsent/Contact;advisor/leaderfail-closed; sem biometria/score; sem módulo top-level novo emutilities/; migração nova sem editar antigas; plano + changelog no commit;pnpm push. - Testes de domínio onde access/write paths mudam: puros da diarização/reconciliação/URL/where/view models no unit; job com seam injetado + action de rótulo com matriz de papéis + query da faceta no int; markup do detalhe/liste no e2e existente.
Self-score de decision-quality
4,5/5. As decisões caras têm alternativas honestas e rejeições ancoradas: provedor com número oficial de quatro candidatos + limitações reais (135 min da Gladia, preview da Melia, 10 h/5 GB da AssemblyAI), escopo da diarização (áudio inteiro vs chunk — o modo chunk mente e foi rejeitado), papel do provedor (não substitui o ASR dono), modelo dos rótulos com precedente de query validado (hasMany + contains no Payload 3.82), semântica da faceta, reconciliação conservadora com aviso e fallback honesto. Cabe no appetite herdado (fases somam ~3–3,5 dias, tracer nos puros+schema cedo) e reusa shells/donos existentes (CampaignHeaderFilterPopover, withPayloadTransaction, campaignJsonMutationRoute, moldes de deepInfraTranscribe, SpeechCutDeleteDialog, speechListFilters). Perde 0,5 porque duas coisas ficam fora do código e viram parada dura/validação: a migração (HARD-STOP explícito, local-only) e o custo/chave do provedor (assumido; gate humano com smoke real), além de duas escolhas de port que dependem de ratificação no gate (banner da Cena 4 sempre visível sem score; subtítulo do C199 mantido na Cena 3).