Tutorial de la bitácora de escucha

1. Para qué sirve

La bitácora es el sitio donde una persona escucha y valora las muestras que produce el motor de voces de Finaz (frases financieras habladas por el ancla en español de España: compuestas a partir de piezas o leídas enteras, pruebas A/B de personas de voz, comparativas de proveedores, etc.). Cada entrega es una hoja: un conjunto de muestras con una pregunta concreta («¿qué persona suena más natural?», «¿se notan las costuras?»).

• Tus valoraciones mandan. El detector automático y el juez IA son modelos que intentan predecir lo que dice el oyente humano; con tus veredictos se miden sus aciertos y falsas alarmas (ProjectPlan3 §8.4).
• Deciden el plan. Las valoraciones eligen la persona de voz, la granularidad del montaje (frase completa o piezas) y qué piezas o costuras se descartan: un «Mal» con un instante marcado se atribuye a la pieza o unión que suena en ese segundo.
• Quedan registradas con trazabilidad. Cada valoración guarda revisor, hora, sesión, modo ciego, familias de defecto, instantes y el SHA-256 del audio exacto que escuchaste (lo calcula el servidor sobre el archivo servido). Después se incorporan al repositorio (qa/decisions_history.jsonl, qa/current_decisions.json y LogDecisionesQA.md).

2. Cómo usarla paso a paso

1. Entra en voces.finaz.com. No hace falta registrarse ni identificarse: el acceso es libre. La sesión dura 24 h; si caduca a mitad de una escucha, recarga la página.
2. Comprueba el revisor en la casilla «Juez / Revisor» de la barra lateral (por defecto mmiguez). Solo cuentan como escucha humana los identificadores de qa/human_reviewers.yaml; con cualquier otro, la valoración se guarda como automática y el visor avisa («no es un revisor humano registrado»).
3. Elige una hoja en el índice (tarjetas de la más reciente a la más antigua) o en la barra lateral, que indica cuántas muestras tiene cada una.
4. Lee «Qué valorar en esta entrega», el recuadro con las preguntas de la hoja. Las muestras se agrupan por caso: las opciones que se comparan (p. ej. «Opción X» y «Opción Y») aparecen juntas, una debajo de otra. Las entregas anteriores de la misma hoja están plegadas al final, con sus fechas y valoraciones originales.
5. Escucha primero de corrido, sin abrir nada más. Los botones -5s y -2s retroceden y siguen reproduciendo (y pausan cualquier otra muestra que esté sonando).
6. Vuelve a los puntos dudosos. El desplegable «Ver detalles técnicos…» contiene:
   • el gráfico de volumen con los silencios internos sombreados y las costuras marcadas como líneas verticales (un clic en el gráfico salta a ese punto);
   • los botones «🔗 Unión a→b», que empiezan 0,45 s antes de cada costura para oír la transición;
   • las piezas sueltas (a, b, c…) con su texto, los stems si los hay, y el auditor automático con sus hallazgos («▶ Escuchar» salta al instante).
   Con el modo ciego activo, la nota del detector y la nota de diferencias de cada opción permanecen ocultas hasta que valores.
7. Valora con uno de los cuatro botones (escala abajo). Se guarda al momento; el indicador cambia a «✓ Guardado».
8. Marca los defectos pulsando las familias (VOZ, PAUSA, COMIDA…); otro clic las desmarca. Mientras suena el audio, «⏱️ Marcar instante» guarda el segundo exacto donde oyes el defecto: aparece como 📍 (clic para volver a oírlo, × para quitarlo). Si marcas una familia antes de elegir veredicto, la muestra queda provisionalmente como «Mal»; si marcas un instante, como «Regular». Ajusta el veredicto después.
9. Escribe notas en el comentario: qué oyes y dónde («se come la -s de euros», «prefiero X»). Se guarda solo al dejar de escribir 1,5 s o al salir del campo. Si no marcas familias, se deducen de las notas con un léxico fijo; es mejor marcarlas.
10. Revisa el progreso con los contadores (Total, Excelente, Bien, Regular, Mal, Pendientes) y los filtros (p. ej. «Pendientes» para ver lo que falta).

3. Escala y familias de defecto

Una muestra puede tener varias familias. Si dudas entre dos veredictos, elige el peor y explícalo en notas.

4. Reglas de escucha (ProjectPlan3 §8.2)

• A ciegas por defecto. «🙈 Modo Ciego: ON» oculta la nota del detector y la explicación de cada opción hasta que valoras. No lo desactives antes de valorar: cada valoración registra si se hizo a ciegas, y el detector solo se puede medir con escuchas que no lo vieron.
• Repeticiones ocultas. Alrededor de un 10 % de las muestras se repite sin aviso para medir tu consistencia (acuerdo test-retest). Valora cada muestra como si fuera nueva; no intentes averiguar cuáles son ni compararlas.
• No abras las claves ciegas. Los experimentos A/B guardan qué opción es cada persona en archivos aparte (p. ej. blind_key.json dentro de output/experiments/…). No se publican en esta web; en el repositorio no los abras hasta que el experimento esté cerrado y valorado.
• Sesiones cortas: 30 minutos como máximo. Si hay referencia M (lectura continua de la persona), úsala para comparar.
• Cada sample_id es único y no se reutiliza: si una muestra cambia, llega como muestra nueva.
• Usa auriculares, el mismo volumen durante toda la sesión y un entorno silencioso.

5. Cómo se publican entregas nuevas (equipo técnico)

1. Generar las muestras y añadir su hoja a output/qa_showcase_catalog.json con el publicador de la entrega (p. ej. tools/prepare_qa_showcase_assets.py o los publish_*.py de cada experimento). Cada hoja es una sección con slug, sheet_serial, evaluation_protocol e items (WAV bajo output/).
2. Comprobarla en local: uv run uvicorn finaz_sound.api.app:app --port 8080 y abrir /qa/<slug>.
3. Publicarla:

   uv run finaz-sound publish-qa --dry-run   # qué WAV se subirían (solo nuevos o cambiados, por SHA-256)
   uv run finaz-sound publish-qa             # trae valoraciones, sube audio a R2, regenera el sitio y despliega

4. Traer las valoraciones hechas aquí al repositorio (también lo hace publish-qa antes de publicar) y versionarlas:

   uv run finaz-sound sync-qa
   git add qa/ LogDecisionesQA.md && git commit -m "QA: valoraciones de voces.finaz.com"

Detalles técnicos en docs/Bitacora_Cloudflare.md del repositorio.