# Transcript Forensics · Sprint backlog

**Producto**: Transcript Forensics (audio counterpart to Blocao).
**Stack**: misma plataforma que Blocao (router + Cell + hub + GitOps + Mosquitto). Lo distinto es el contenedor de procesamiento (Whisper + pyannote) y el panel forense del audio.

Las stories `WDM-T-XX.Y` corresponden 1:1 con la épica numerada. Muchas son **trivialmente reutilizables** desde el backlog Blocao — esas se identifican abajo y se delegan a `shared-stories.md`.

---

## Cómo se relaciona con Blocao

La gran mayoría de la infraestructura es la misma: monorepo, CI, image builder, balena fleet, MQTT contract, GitOps reconciler, hub, auth, network sovereignty, design tokens, console framework. Las épicas 0, 1, 2, 5, 6, 7 son **prácticamente idénticas** — solo cambia qué corre dentro del Cell y qué panel muestra la consola.

Las épicas que **sí son específicas** del transcript product:

- **Épica 3 — Audio onboarding** (en lugar de camera onboarding).
- **Épica 4 — Transcript operator plane** (en lugar de video operator plane).

Esto significa que ~70% del trabajo de Transcript Forensics ya está hecho cuando Blocao MVP esté en producción.

---

## ÉPICAS y mapping a Blocao

| Sprint | Épica | Mapping a Blocao |
|---|---|---|
| 0 | Foundation | Idéntico a Blocao Épica 0. Stories `SHARED-00.X`. |
| 1 | First boot | Idéntico a Blocao Épica 1. Stories `SHARED-01.X`. |
| 2 | Engineering plane | Idéntico a Blocao Épica 2. Stories `SHARED-02.X`. |
| 3 | **Audio onboarding** | NUEVO. Stories `WDM-T-03.X`. |
| 4 | **Transcript operator plane** | NUEVO. Stories `WDM-T-04.X`. |
| 5 | Health & ops | Idéntico a Blocao Épica 5 + algunos checks específicos de STT. Stories `SHARED-05.X` + `WDM-T-05.X`. |
| 6 | Hub & fleet | Idéntico a Blocao Épica 6. Stories `SHARED-06.X`. |
| 7 | Hardening | Idéntico a Blocao Épica 7 + manifest schema con campos audio-specific. Stories `SHARED-07.X` + `WDM-T-07.X`. |

---

# ÉPICA 3 — AUDIO ONBOARDING

Equivalente a la épica de camera onboarding pero para audio sources.

### `[WDM-T-03.1]` Audio source discovery — *M*

**Como** installer, **veo** las fuentes de audio disponibles: USB mic conectado, line-in, SIP gateway, file watcher, archivos subidos manualmente.

Backend en Cell: enumera devices ALSA/PulseAudio, comprueba SIP gateway si configurado, escanea carpetas watched.
**Tests de aceptación**: enchufar un USB mic se detecta en <5s; añadir un fichero a watched folder se detecta en <30s.
**Estimación**: M (3d).
**Depende de**: SHARED-02.1 (hai.uc base).

### `[WDM-T-03.2]` Audio source authentication — *S*

**Como** installer, para SIP gateways o cuentas de servicio, **introduzco** credenciales y se verifican.

Backend: SIP register-test, IMAP/POP3 test si fuente es email-attached audio.
**Estimación**: S (1d).
**Depende de**: WDM-T-03.1.

### `[WDM-T-03.3]` Test stream + transcripción de prueba — *M*

**Como** installer, **graban** 30s de audio y veo la transcripción aparecer.

Backend: el Cell recibe orden de capturar 30s, los pasa a Whisper, devuelve resultado al router.
**Tests de aceptación**: la transcripción aparece en <60s; speaker labels (SP-A, SP-B) aparecen si hay 2+ speakers.
**Estimación**: M (3d).
**Depende de**: WDM-T-03.2, WDM-T-04.1 (whisper container).

### `[WDM-T-03.4]` Configure form — name, language, retention, speakers expected — *S*

**Como** installer, **introduzco** datos: nombre del source, idioma esperado, retention (hereda regional), speakers esperados (lista o "auto").

UI: form similar al de cameras.
**Estimación**: S (1d).
**Depende de**: WDM-T-03.3.

### `[WDM-T-03.5]` Save — generate Whisper config + GitOps commit — *L*

**Como** installer, **al guardar**, se genera la config de Whisper para el source, se comitea, se reinicia el container, primer ciclo de prueba end-to-end.

Backend:
1. Generar la sección `sources:<id>` del whisper.yml.
2. Commit local al repo.
3. Push si configurado.
4. Trigger reconcile.
5. Esperar primer transcript end-to-end.

**Tests de aceptación**: tras "FINISH", primer evento `aud/<source_id>/transcript` llega al MQTT en <60s.
**Estimación**: L (5d).
**Depende de**: WDM-T-03.4, SHARED-02.8 (gitops).

### `[WDM-T-03.6]` Speaker library — initial enrollment — *M*

**Como** installer, **enrollo** voiceprints conocidos: subo audio o grabo en directo, etiqueto con nombre.

Backend: pyannote produce el embedding, se guarda en Qdrant collection `speakers/<customer_id>`.
**Tests de aceptación**: 5 speakers enrolados; en sesiones nuevas, esos speakers son identificados automáticamente con score >0.7.
**Estimación**: M (3d).
**Depende de**: WDM-T-03.5.

---

# ÉPICA 4 — TRANSCRIPT OPERATOR PLANE

El panel forense del audio. Equivalente al panel forense de video pero adaptado.

### `[WDM-T-04.1]` Whisper + pyannote container — *L*

**Como** team, **necesito** un contenedor Balena que corra Whisper + pyannote en el Cell, expuesto como API.

Stack:
- Whisper.cpp con quantized model (large-v3-q5).
- Pyannote para diarization.
- Wrapper FastAPI que orquesta: audio in → diarization → transcripción por segmento → match contra speaker library.

**Tests de aceptación**: 60min de audio se procesan en <15min en RK3588 con NPU; 95% accuracy en idioma claro (Spanish/English).
**Estimación**: L (1 sem).
**Depende de**: SHARED-00.4 (balena fleet provisioning).

### `[WDM-T-04.2]` Transcript chat UI con autocomplete — *M*

**Como** investigator, **escribo** consultas naturales sobre transcripts: "qué se dijo del contrato Acme y quién insistió más".

Reuso del componente chat del Blocao operator plane. Vocabulario adaptado: speakers conocidos, topics, time ranges.
**Tests de aceptación**: query en español devuelve hits relevantes; ghost text sugiere desde corpus de transcripts existente.
**Estimación**: M (3d).
**Depende de**: WDM-T-04.1, BL-04.5 (chat UI base — shared).

### `[WDM-T-04.3]` Transcript timeline con speaker bands — *L*

**Como** investigator, **veo** un waveform con bands coloreadas por speaker (uno por color), markers en hits, playhead.

UI: similar al timeline de video pero con waveform en vez de frames; swimlanes son speakers en lugar de cameras.
Backend: API devuelve segments `{start, end, speaker_id, confidence, text}`.
**Tests de aceptación**: 1h de transcript con 4 speakers se renderiza en <500ms; click en marker reproduce desde ese punto.
**Estimación**: L (5d).
**Depende de**: WDM-T-04.1.

### `[WDM-T-04.4]` Audio player con live caption — *M*

**Como** investigator, **reproduzco** el audio y **veo** la transcripción avanzar sincronizada con el playhead.

UI: player shell shared con video; visualización es waveform en lugar de frame.
Backend: streaming HTTP con range requests; transcript events sincronizados.
**Tests de aceptación**: scrubbing fluido; caption salta correctamente al cambiar speaker.
**Estimación**: M (3d).
**Depende de**: WDM-T-04.3.

### `[WDM-T-04.5]` Topic detection panel — *L*

**Como** investigator, **veo** los topics detectados en una sesión, ordenados por tiempo de discusión, click → hits relacionados.

Backend: NER (Named Entity Recognition) + clustering de spans; topics aparecen como entities (personas, organizaciones, fechas, lugares, montos económicos).
**Tests de aceptación**: en transcript de 1h con 5 topics distintos, se detectan al menos 4 con precisión.
**Estimación**: L (5d).
**Depende de**: WDM-T-04.1.

### `[WDM-T-04.6]` Speaker breakdown — quién habla cuánto — *M*

**Como** investigator, **veo** estadísticas por speaker: tiempo total, número de turnos, palabras, ratio de interrupción.

UI: panel lateral en transcript view.
Backend: estadísticas calculadas del array de segments.
**Estimación**: M (2d).
**Depende de**: WDM-T-04.3.

### `[WDM-T-04.7]` Insistence ranking por topic — *L*

**Como** investigator, **veo** quién insiste más en cada topic detectado: número de intervenciones, repetición de keywords, evolución temporal.

Backend: heurística sobre los segments + topic mapping. Score por (speaker, topic).
**Tests de aceptación**: en transcript con discusión clara de 2 partes sobre un topic, la heurística identifica correctamente quién insistió más.
**Estimación**: L (5d).
**Depende de**: WDM-T-04.5, WDM-T-04.6.

### `[WDM-T-04.8]` Pin to case (transcript) — *M*

**Como** investigator, **pino** un segmento o un transcript completo a un caso.

Backend: extiende el modelo de cases existente con tipo `transcript_segment`.
**Estimación**: M (2d).
**Depende de**: BL-04.8 (case model — shared).

### `[WDM-T-04.9]` Transcript export — bundle ZIP — *M*

**Como** investigator, **exporto** un caso con transcripts, audio, manifests.

Backend: extiende el exporter con tipos audio.
**Estimación**: M (3d).
**Depende de**: BL-04.10 (export base — shared).

---

# ÉPICA 5 — HEALTH & OPS (transcript-specific additions)

### `[WDM-T-05.1]` Selftest checks específicos de STT — *S*

**Como** ops, **el selftest** verifica que Whisper container está sano, que el audio device es accesible, que el speaker library responde.

Backend: tests adicionales en healthd.
**Estimación**: S (1d).
**Depende de**: BL-05.1 (selftest base).

### `[WDM-T-05.2]` Transcripción throughput metrics — *S*

**Como** ops, **veo** cuántos minutos de audio se procesan por hora, latencia desde grabación a transcript disponible.

Backend: métricas publicadas a TimescaleDB.
**Estimación**: S (1d).
**Depende de**: WDM-T-04.1.

---

# ÉPICA 7 — HARDENING (transcript-specific)

### `[WDM-T-07.1]` Manifest schema audio-specific — *S*

**Como** investigator, **el manifest** de cada transcript incluye: sha256_audio, sha256_transcript, ts_start, ts_end, model_sha, source_id, speaker_ids_present.

Backend: extiende el manifest schema base con campos audio.
**Estimación**: S (1d).
**Depende de**: BL-07.1 (manifest base).

### `[WDM-T-07.2]` Audio evidence verifier — *S*

**Como** investigator, **`blocao verify`** acepta también audio + transcript + manifest.

Backend: la CLI extiende su matching.
**Estimación**: S (1d).
**Depende de**: BL-07.2.

---

# Cross-references a stories shared

Para evitar duplicar trabajo, las stories de épicas 0, 1, 2, 5, 6, 7 que son comunes con Blocao están en [`shared-stories.md`](shared-stories.md):

- `SHARED-00.1` ↔ `BL-00.1` (monorepo)
- `SHARED-00.2` ↔ `BL-00.2` (CI/CD)
- `SHARED-00.3` ↔ `BL-00.3` (image builder)
- `SHARED-00.4` ↔ `BL-00.4` (balena fleet — extiende con whisper container)
- `SHARED-00.5` ↔ `BL-00.5` (MQTT schemas — extiende con namespace `aud/`)
- ... (sprints 1, 2, 5, 6, 7)

El equipo de transcript no escribe su propia versión de estas stories; trabaja sobre las shared y solo añade adaptaciones documentadas.

---

# Riesgos específicos del transcript product

1. **Whisper en RK3588** puede ser limitante si el audio tiene mucho ruido o múltiples lenguajes mezclados. Mitigación: ofrecer opción de fallback a Cell con Jetson para customers con audio difícil.
2. **Speaker library cross-session matching** depende de calidad de voiceprint enrollment. Mitigación: enrollment guidado en wizard, calidad mínima validada antes de aceptar.
3. **Privacy del audio** es aún más sensible que video — un whisper de transcripción puede capturar conversaciones íntimas. Mitigación: documentación clara de qué se graba y cuándo, signage equivalente a cámaras.
4. **Latencia transcripción → disponible para query**: en sitios con poca compute, puede ser >2x real-time. Mitigación: priorización por flag "investigation pending".

---

# Notas para sprint planning

El equipo transcript puede empezar **en el Sprint 4 de Blocao**, una vez que SHARED-00.X y SHARED-02.X estén estables. Antes, no hay sustrato sobre el que construir.

Demo viable de transcript: ~Sprint 4 desde el inicio del transcript track. Asumiendo que Blocao MVP cierra en su Sprint 4, el transcript MVP es Sprint 8 desde el inicio del proyecto global.

---

*Documento sujeto a revisión cuando el equipo transcript entre en planning.*