Narración segura del tutorial P6¶

Este pipeline agrega narración en español argentino y subtítulos al MP4 real del tutorial. El video, el plan, los audios temporales y las salidas permanecen fuera del repositorio. No instala paquetes ni copia el video fuente al checkout.

Requisitos externos¶

ffmpeg y ffprobe con encoders libx264, aac y mov_text.
edge-tts instalado fuera del repo. La voz está fijada en es-AR-ElenaNeural.
Un MP4 ya anonimizado y un plan JSON o SRT con narración exclusivamente operativa.

El binario de Edge TTS se pasa con --edge-tts-bin o EDGE_TTS_BIN. Por ejemplo, puede estar dentro de un virtualenv temporal o de usuario; no debe estar dentro del checkout.

Plan JSON¶

Guardá este contenido en una ubicación externa, por ejemplo /private/tmp/eppa-tutorial-plan.json. Los tiempos están expresados en segundos y los cues no pueden superponerse.

{
  "version": 1,
  "language": "es-AR",
  "voice": "es-AR-ElenaNeural",
  "cues": [
    {
      "id": "inicio",
      "start": 0.5,
      "end": 4.5,
      "text": "Iniciá sesión con la cuenta de demostración."
    },
    {
      "id": "carga",
      "start": 5.0,
      "end": 9.5,
      "text": "Abrí la vista anterior y cargá la imagen preparada."
    },
    {
      "id": "zoom",
      "start": 10.0,
      "end": 15.5,
      "text": "Acercá la imagen antes de ubicar cada marcador anatómico."
    },
    {
      "id": "calibracion",
      "start": 16.0,
      "end": 22.0,
      "text": "Marcá los dos extremos de la referencia horizontal de diez centímetros."
    }
  ]
}

También se acepta SRT UTF-8. En ese formato cada intervalo se usa como ventana de narración y subtítulo.

El validador rechaza rutas locales, correos, teléfonos, credenciales, identificadores de caso y datos clínicos evidentes. No incluyas nombres, números de paciente, diagnósticos ni resultados. Los textos deben explicar acciones genéricas de la interfaz.

Preflight sin generar archivos¶

python3 fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION.py \
  --input-mp4 /ruta/externa/tutorial-sin-narrar.mp4 \
  --plan /ruta/externa/tutorial-plan.json \
  --output-dir /ruta/externa/tutorial-final \
  --edge-tts-bin /ruta/externa/bin/edge-tts \
  --preflight-only

El preflight valida privacidad estructural, existencia y ubicación de entradas, codecs disponibles, duración del video, límites de cues y versiones de herramientas. Su salida no contiene paths ni texto narrado. Las sondas de herramientas fallan a los 30 segundos y cada síntesis tiene un límite de 180 segundos para no dejar el proceso colgado.

Generación¶

Ejecutá el mismo comando sin --preflight-only:

python3 fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION.py \
  --input-mp4 /ruta/externa/tutorial-sin-narrar.mp4 \
  --plan /ruta/externa/tutorial-plan.json \
  --output-dir /ruta/externa/tutorial-final \
  --edge-tts-bin /ruta/externa/bin/edge-tts

Genera, de forma atómica:

eppa-tutorial-narrated.mp4: H.264, AAC y subtítulos mov_text embebidos.
eppa-tutorial.es-AR.srt: subtítulos UTF-8 externos.
eppa-tutorial.metadata.json: hashes SHA-256, bytes, duración, codecs, versiones y alineación por cue. No incluye rutas, nombres de archivos fuente ni el texto de narración.

Si el audio original existe, se conserva al 12 % bajo la voz. Se puede ajustar entre cero y uno con --source-volume. Un cue que exceda su ventana se acelera como máximo 1,30x; si necesita más, el proceso falla para evitar cortar o volver ininteligible la locución. Usá --overwrite únicamente para reemplazar las tres salidas conocidas.

Gate focal offline¶

python3 fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION-TEST.py
python3 -m py_compile \
  fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION.py \
  fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION-TEST.py
git diff --check -- \
  fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION.py \
  fronts/eppa/scripts/PATIENT-6-TUTORIAL-NARRATION-TEST.py \
  fronts/eppa/docs/testing/PATIENT-6-TUTORIAL-NARRATION.md

La prueba final debe ejecutarse con el MP4 externo real y el binario Edge TTS disponible. El pipeline no sustituye la revisión visual y auditiva del video terminado.