dialogue-transcriber

Transcribe conversaciones y descubre quién dijo qué.

Apunta a una entrevista, mesa redonda, grabación de reunión o URL de YouTube y obtén una transcripción en la que cada línea se atribuye a un hablante, además de una interfaz web para inspeccionar los grupos de hablantes, escuchar cualquier segmento y corregir etiquetas manualmente.

Cómo funciona

audio  ──►  transcribe  ──►  segment  ──►  extract_clips  ──►  embed  ──►  cluster
              (Whisper)        (sentence-       (ffmpeg)       (TitaNet)    (UMAP +
                               level)                                       KMeans +
                                                                            silhouette)

Whisper genera marcas de tiempo a nivel de palabra; las palabras se agrupan en segmentos de frases; el audio de cada segmento se incrusta con NVIDIA NeMo TitaNet; los embeddings se agrupan en una proyección UMAP; y la transcripción sale etiquetada como Speaker 1, Speaker 2, … Cada etapa se guarda en caché mediante hash de contenido, por lo que las repeticiones y los ajustes de configuración son baratos.

Related MCP server: AssemblyAI MCP Server

Inicio rápido

ffmpeg y ffprobe deben estar en PATH (brew install ffmpeg en macOS).

# No install needed:
uvx --from "dialogue-transcriber[all]" transcriber transcribe interview.mp3

# Or install the tool:
uv tool install "dialogue-transcriber[all]"

transcriber transcribe interview.mp3 --participants 2
transcriber transcribe "https://www.youtube.com/watch?v=..." --backend openai
transcriber serve interview.mp3        # review UI on http://127.0.0.1:8000

El backend predeterminado ejecuta faster-whisper localmente; --backend openai usa la API de OpenAI Whisper en su lugar (requiere OPENAI_API_KEY, mucho más rápido en máquinas sin GPU). La clave se puede exportar en el entorno o guardarse en un archivo .env en tu proyecto: la CLI carga .env desde el directorio de trabajo (o el padre más cercano), y las variables exportadas siempre tienen prioridad sobre el archivo.

¿Dónde van los datos?

• Caché del pipeline: ./.transcriber-cache/ en el directorio desde el que ejecutas (anula con --work-dir): fragmentos, clips por segmento, embeddings, descargas de YouTube y el estado de trabajos de la interfaz web. Se puede eliminar sin problema; se reconstruirá.

• Transcripciones: se escriben junto al audio de entrada (interview.txt), o donde apunte --output; --output - imprime en stdout.

• Pesos del modelo (backend local): se descargan una vez en ~/.cache (Hugging Face / NeMo). La descarga de Whisper large-v3 es de ~3 GB, por lo que la primera ejecución local tarda un poco.

Nada sale de tu máquina con el backend local predeterminado; --backend openai envía audio a la API de OpenAI.

Cómo elegir tus extras

[all] es el botón fácil. Para instalaciones más pequeñas:

uv pip install dialogue-transcriber              # core only
uv pip install "dialogue-transcriber[local]"     # + faster-whisper backend
uv pip install "dialogue-transcriber[openai]"    # + OpenAI Whisper API backend
uv pip install "dialogue-transcriber[cluster]"   # + scikit-learn / UMAP
uv pip install "dialogue-transcriber[embed]"     # + NeMo TitaNet speaker embedder
uv pip install "dialogue-transcriber[api]"       # + FastAPI backend (powers the web UI)
uv pip install "dialogue-transcriber[youtube]"   # + yt-dlp downloader
uv pip install "dialogue-transcriber[oip]"       # + MCP server for OIP consumers

CLI

# Full pipeline; writes a speaker-labeled transcript next to the audio
transcriber transcribe path/to/audio.mp3

# Speakers, language, format
transcriber transcribe interview.mp3 --participants 3 --language sv --format vtt

# Machine-readable output on stdout (see "For AI agents" below)
transcriber transcribe interview.mp3 --format json --output -

# Pull audio from YouTube
transcriber download "https://www.youtube.com/watch?v=..."

# Pipeline + web UI
transcriber serve interview.mp3 --participants 3

Formatos: txt (turnos de hablante combinados), vtt, srt, json. Pasa --context "nombres, jerga" para preparar a Whisper con el vocabulario que debe esperar. --output - transmite la transcripción a stdout y el resumen a stderr, para que la salida se canalice limpiamente.

Interfaz web

transcriber serve ejecuta un backend FastAPI y sirve el frontend React incluido. Obtienes:

• un diagrama de dispersión UMAP donde cada punto es un segmento, coloreado por grupo: selecciona un grupo para renombrarlo en bloque;

• una forma de onda continua con una región por segmento: haz clic o arrastra para reproducir cualquier cosa;

• una línea de tiempo de hablantes estilo Gantt;

• una transcripción virtualizada con búsqueda de texto completo;

• chips de hablante renombrables en línea (los cambios persisten en el servidor);

• exportación TXT / VTT / SRT;

• navegación por teclado (↑/↓ segmentos, Espacio reproducir/pausar, / buscar).

Varios trabajos pueden ejecutarse en paralelo; añade más desde la barra lateral.

serve elige su backend automáticamente: openai cuando hay una OPENAI_API_KEY disponible (entorno o .env), de lo contrario local. Pasa --backend para elegir explícitamente. (Una interfaz Dash heredada de un solo trabajo sigue disponible como transcriber ui).

Para agentes de IA

Este proyecto está diseñado para ser manejado tanto por agentes como por humanos.

Habilidad de Claude Code: el repositorio funciona también como mercado de complementos. Instala la habilidad y Claude Code sabrá cómo transcribir y diarizar audio bajo demanda:

/plugin marketplace add Novia-RDI-Seafaring/transcriber
/plugin install dialogue-transcriber@dialogue-transcriber

Salida estructurada: --format json --output - emite una forma estable en stdout:

{
  "speakers": ["Speaker 1", "Speaker 2"],
  "n_segments": 42,
  "duration": 512.3,
  "segments": [
    {"speaker": "Speaker 1", "start": 0.0, "end": 4.2, "text": "..."}
  ]
}

MCP / OIP: el paquete es un productor de Open Ingestion Protocol, por lo que cualquier consumidor compatible con OIP (p. ej. Anchor) puede ingerir las transcripciones sin cambios en el lado del consumidor:

transcriber oip install --data-dir ~/transcripts     # register the producer
transcriber oip ingest audio.mp3 --data-dir ~/transcripts
transcriber oip serve                                # MCP server (also: transcriber-mcp)

Espacio de nombres de la herramienta: transcribe. Tipo de región: transcript_segment. source_ref.kind: audio-timestamp.

Uso como biblioteca

from transcriber.config import ClusterConfig, PipelineConfig, TranscribeConfig
from transcriber.pipeline import run_pipeline
from transcriber.render import render_txt

cfg = PipelineConfig(
    transcribe=TranscribeConfig(backend="local", language="en"),
    cluster=ClusterConfig(participants=2),
)
result = run_pipeline("interview.mp3", config=cfg)
print(render_txt(result.segments))

PipelineResult.segments es una lista de registros SpeakerSegment con el texto de la frase, el rango de tiempo, el clip en disco y el hablante asignado. PipelineResult.cluster.projection es el UMAP 2-D para graficar.

Backends

Todos los backends son Protocolos; consulta transcriber/transcribe/base.py y transcriber/embed/base.py. Las pruebas usan simulacros en memoria, por lo que no se necesitan los modelos pesados para ejecutar la suite.

Desarrollo

Consulta CONTRIBUTING.md para las pautas y CHANGELOG.md para el historial de versiones.

git clone https://github.com/Novia-RDI-Seafaring/transcriber
cd transcriber
uv venv
uv pip install -e ".[dev,cluster,api,openai,embed,youtube]"
(cd web && pnpm install && pnpm build)   # so `transcriber serve` can serve the UI

pytest                  # core + clustering + api tests
pytest -m "not slow"    # skip heavy/network tests
ruff check src tests

Para el frontend: cd web && pnpm dev (http://127.0.0.1:5173, proxy /api a :8000) con transcriber serve … --port 8000 en otra terminal.

Lanzamientos: publicar un release de GitHub activa .github/workflows/release.yml, que compila el frontend, lo empaqueta en la rueda y publica en PyPI mediante publicación de confianza.

Licencia

Apache-2.0: consulta LICENSE.