Transcript

Transcripción de reuniones en español, en local y sin GPU. Captura el micrófono y el audio del sistema (altavoces) por separado, transcribe con faster-whisper medium int8 sobre CPU y te da el texto en una ventana editable, una API HTTP o una extensión de Chrome. Pensado para Ubuntu con PipeWire/PulseAudio.

El proyecto tiene cuatro piezas, cada una con su propia instalación:

Pieza	Qué es	Cómo se arranca
App de escritorio	Ventana Qt (PySide6) para grabar y editar transcripciones	./install.sh → menú de GNOME o .venv/bin/transcript
API HTTP	Servidor FastAPI local que graba/transcribe sin interfaz	make run o servicio systemd (make service-install)
Extensión de Chrome	Mando a distancia del navegador para la API	Cargar descomprimida en chrome://extensions
Script de reprocesado	Re-transcribe los WAV de una sesión, más rápido	.venv/bin/python scripts/reprocess_session.py

Las tres primeras comparten el mismo motor (src/transcript/) y el mismo modelo descargado; basta instalar las dependencias una vez.

---

Requisitos comunes del sistema

Necesarios para cualquier pieza (la captura de audio depende de las utilidades de PulseAudio/PipeWire):

• Ubuntu 24.04+ (PipeWire o PulseAudio)
• Python 3.12+
• pulseaudio-utils (parec, pactl)
• ffmpeg (opcional, para pruebas)
• uv recomendado (si no está, se usa python -m venv)

sudo apt install -y pulseaudio-utils ffmpeg

💡 Auriculares recomendados. Si los altavoces están abiertos, el micrófono captará también el audio del sistema y aparecerán líneas duplicadas (eco).

⚙️ CPU-only. torch/torchaudio se instalan desde el índice download.pytorch.org/whl/cpu (configurado en pyproject.toml), evitando ~1.5 GB de librerías CUDA inútiles en equipos sin GPU NVIDIA.

---

1. App de escritorio (Qt)

Instalador todo-en-uno: crea el venv, instala dependencias, descarga el modelo e integra el lanzador en el menú de aplicaciones.

./install.sh

El script:

1. Crea un venv en ./.venv con uv (si está) o python -m venv.
2. Instala dependencias (faster-whisper, PySide6, silero-vad, …) con pip install -e ..
3. Verifica/descarga el modelo faster-whisper-medium (~1.5 GB, una sola vez) a la caché de Hugging Face.
4. Instala transcript.desktop en ~/.local/share/applications/ para que aparezca en el menú de GNOME, con su icono.

Arranque: desde el menú de aplicaciones, o directamente:

.venv/bin/transcript      # ejecutable instalado por el venv
# o, con uv:
make app                  # uv run transcript

Desinstalar el lanzador (no borra el venv ni la caché):

./uninstall.sh

Uso

• Iniciar empieza a capturar y transcribir; el texto aparece en bloques [Yo] (mic) y [Sistema] (altavoces) con timestamps.
• El editor es editable mientras llegan líneas nuevas (el cursor se preserva al hacer append).
• Pausar (Ctrl+Space) detiene la captura para editar sin interrupciones; Reanudar la reactiva.
• Guardar (Ctrl+S) / Guardar como… (Ctrl+Shift+S) escriben en ~/Documentos/transcripciones/.
• Hay backup raw incremental en ~/.cache/transcript/sessions/<id>/raw.md, que sobrevive a crashes. Menú Archivo → Recuperar sesión… para abrir uno previo.

Identificación de speakers (opcional)

Botón "Identificar speakers" (toggle) en la toolbar. Etiqueta las líneas de la pista [Sistema] con un identificador estable por persona detectada:

[Sistema · Speaker_1]: Buenos días, ¿empezamos?
[Sistema · Speaker_2]: Sí, perfecto.

Usa embeddings ECAPA-TDNN (speechbrain) con asignación incremental por similitud coseno. La primera vez descarga el modelo (~80 MB) a ~/.cache/transcript/models/ecapa-tdnn/. El toggle se guarda en ~/.config/transcript/settings.json y se puede cambiar en caliente.

Limitaciones honestas:

• La pista [Yo] no se diariza (siempre eres tú).
• En habla solapada o tras silencios largos, un speaker puede saltar de ID. Sirve como ayuda al lector/LLM, no como verdad absoluta.
• El umbral por defecto (0.55) tiende a separar de más antes que mezclar.

---

2. API HTTP headless

Servidor FastAPI (transcript-api) que expone grabación, transcripción, resumen y compartido por Slack como API REST en 127.0.0.1:8765. No tiene interfaz: se controla por HTTP (p. ej. desde la extensión de Chrome).

Instalación de dependencias

make install        # uv sync   (crea/sincroniza el venv)

Si ya instalaste la app de escritorio con ./install.sh, las dependencias de la API ya están dentro del mismo venv.

Configuración (.env)

Copia la plantilla y rellena lo que necesites:

cp .env.example .env

Variable	Por defecto	Para qué
TRANSCRIPT_SLACK_WEBHOOK	—	Incoming Webhook de Slack para enviar resúmenes
TRANSCRIPT_API_HOST	127.0.0.1	Host de escucha
TRANSCRIPT_API_PORT	8765	Puerto de escucha
TRANSCRIPT_SUMMARY_MODEL	sonnet	Modelo del CLI claude para resúmenes
TRANSCRIPT_SUMMARY_TIMEOUT	300	Timeout (s) del resumen

Las variables ya exportadas en el entorno tienen prioridad sobre las del .env.

Arranque manual (primer plano)

make run            # uv run transcript-api

Espera al log «Modelo Whisper cargado. API lista.» (el modelo se precarga en el arranque para que el primer stop no pague la carga).

Arranque como servicio systemd (--user)

Se instala como unidad de usuario (systemctl --user) porque la captura de audio necesita la sesión de PipeWire/PulseAudio del usuario:

make service-install     # instala, habilita y arranca el servicio
make service-status      # systemctl --user status
make service-logs        # journalctl -f
make service-restart
make service-uninstall   # para y elimina la unidad
make service-print       # imprime la unidad sin instalar nada

Endpoints principales

Método	Ruta	Descripción
GET	/health	Estado y si el modelo está cargado
GET	/status	Estado del motor de grabación
POST	/recordings/start	Inicia la grabación
POST	/recordings/stop	Detiene y lanza la transcripción
GET	/transcriptions	Lista de transcripciones
GET	/transcriptions/{id}	Texto de una transcripción
PATCH	/transcriptions/{id}	Renombra una sesión
DELETE	/transcriptions/{id}	Borra una sesión
POST	/transcriptions/{id}/summary	Resumen con el CLI claude
POST	/transcriptions/{id}/share/slack	Envía el resumen a Slack

---

3. Extensión de Chrome

Mando a distancia para la API local. El botón Grabar dispara la grabación de mic + audio del sistema en tu máquina (vía PipeWire), no en el navegador; al Detener, la API transcribe con Whisper.

Requisito previo: la API arrancada (make run o el servicio systemd) y escuchando en http://127.0.0.1:8765.

Instalación

1. Abre chrome://extensions.
2. Activa Modo de desarrollador (arriba a la derecha).
3. Cargar descomprimida → selecciona la carpeta extension/.
4. (Opcional) Fija el icono en la barra.

Uso

• Pulsa el icono para abrir el popup.
• ● Grabar inicia la grabación (badge REC en el icono).
• ■ Detener y transcribir para y lanza la transcripción (badge …).
• Al terminar, la grabación aparece como done; clic para leer el texto.
• El icono ⚙ permite cambiar la URL de la API (útil si arrancas en otro puerto con TRANSCRIPT_API_PORT).

---

4. Script de reprocesado

Re-transcribe los WAV de una sesión usando el VAD interno de faster-whisper (procesa el WAV entero en chunks de 30s, mucho más rápido que el pipeline batch de la app). Ambas pistas se procesan en paralelo.

# Sesión más reciente en ~/.cache/transcript/sessions/
.venv/bin/python scripts/reprocess_session.py

# O una sesión concreta
.venv/bin/python scripts/reprocess_session.py ~/.cache/transcript/sessions/<id>

Escribe el resultado en <session>/reprocessed.md y a stdout.

---

Pruebas de humo

.venv/bin/python tests/smoke_capture.py   # captura de audio
.venv/bin/python tests/smoke_asr.py       # transcripción
.venv/bin/python tests/smoke_diar.py      # diarización

Rutas de datos

Ruta	Contenido
~/Documentos/transcripciones/	Transcripciones guardadas (editadas)
~/.cache/transcript/sessions/<id>/	WAV crudos, raw.md, backups
~/.cache/transcript/models/	Modelos descargados (ECAPA-TDNN)
~/.config/transcript/settings.json	Ajustes de la app (toggle de speakers, …)