dialogue-transcriber

Расшифровывайте разговоры и узнавайте, кто что сказал.

Укажите интервью, панельную дискуссию, запись встречи или URL на YouTube — и получите транскрипт, где каждая реплика приписана конкретному говорящему — плюс веб-интерфейс для просмотра кластеров говорящих, прослушивания любого фрагмента и ручного исправления меток.

Как это работает

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

Whisper выдаёт посекундные таймстампы; слова группируются в предложения; аудио каждого сегмента эмбедится с помощью NVIDIA NeMo TitaNet; эмбеддинги кластеризуются на UMAP-проекции; на выходе получается транскрипт с метками Speaker 1, Speaker 2, … Каждый этап кэшируется по хэшу содержимого, поэтому повторные запуски и правки конфигурации обходятся дёшево.

Related MCP server: AssemblyAI MCP Server

Быстрый старт

ffmpeg и ffprobe должны быть в PATH (brew install ffmpeg на 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

Бэкенд по умолчанию запускает faster-whisper локально; --backend openai использует OpenAI Whisper API (требуется OPENAI_API_KEY, работает значительно быстрее на машинах без GPU). Ключ можно задать через переменную окружения или хранить в файле .env в вашем проекте — CLI загружает .env из рабочей директории (или ближайшей родительской), а переменные окружения всегда имеют приоритет над файлом.

Куда сохраняются данные?

• Кэш пайплайна: ./.transcriber-cache/ в директории, откуда вы запускаете (переопределяется через --work-dir) — чанки, клипы по сегментам, эмбеддинги, загрузки с YouTube и состояние задач веб-интерфейса. Можно безопасно удалить; он будет пересоздан.

• Транскрипты: записываются рядом с входным аудио (interview.txt) или туда, куда указывает --output; --output - выводит в stdout.

• Веса моделей (локальный бэкенд): загружаются один раз в ~/.cache (Hugging Face / NeMo). Загрузка Whisper large-v3 занимает ~3 ГБ, поэтому первый локальный запуск займёт время.

С локальным бэкендом по умолчанию ничего не покидает вашу машину; --backend openai отправляет аудио в OpenAI API.

Выбор дополнительных компонентов

[all] — это кнопка «просто». Для более компактных установок:

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

Форматы: txt (объединённые реплики говорящих), vtt, srt, json. Передайте --context "имена, жаргон", чтобы заранее задать Whisper словарь, который он должен ожидать. --output - выводит транскрипт в stdout, а сводку в stderr, так что вывод чисто передаётся дальше.

Веб-интерфейс

transcriber serve запускает FastAPI-бэкенд и раздаёт встроенный React фронтенд. Вы получаете:

• UMAP-диаграмму рассеяния, где каждая точка — один сегмент, окрашенный по кластеру — выделите кластер лассо, чтобы переименовать его массово;

• непрерывную осциллограмму с одной областью на сегмент — кликните или прокрутите, чтобы воспроизвести что угодно;

• таймлайн говорящих в стиле Ганта;

• виртуализированный транскрипт с полнотекстовым поиском;

• переименовываемые прямо в строке чипы говорящих (переименования сохраняются на сервере);

• экспорт в TXT / VTT / SRT;

• навигацию с клавиатуры (↑/↓ — сегменты, Space — воспроизведение/пауза, / — поиск).

Несколько задач могут выполняться параллельно; добавляйте новые через боковую панель.

serve выбирает бэкенд автоматически: openai, если доступен OPENAI_API_KEY (из окружения или .env), иначе local. Передайте --backend, чтобы выбрать явно. (Устаревший однозадачный Dash-интерфейс по-прежнему доступен как transcriber ui.)

Для ИИ-агентов

Этот проект создан, чтобы им могли управлять как агенты, так и люди.

Навык Claude Code — репозиторий также служит маркетплейсом плагинов. Установите навык, и Claude Code будет знать, как транскрибировать и диаризировать аудио по запросу:

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

Структурированный вывод — --format json --output - выдаёт стабильную структуру в 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 — пакет является Open Ingestion Protocol продюсером, поэтому транскрипты могут быть приняты любым потребителем, поддерживающим OIP (например, Anchor), без изменений на стороне потребителя:

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)

Пространство имён инструментов: transcribe. Тип региона: transcript_segment. source_ref.kind: audio-timestamp.

Использование как библиотеки

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 — это список записей SpeakerSegment с текстом предложения, временным диапазоном, клипом на диске и назначенным говорящим. PipelineResult.cluster.projection — это 2-D UMAP для построения графиков.

Бэкенды

Все бэкенды — это протоколы — см. transcriber/transcribe/base.py и transcriber/embed/base.py. В тестах используются фейки в памяти, поэтому тяжёлые модели не требуются для запуска набора тестов.

Разработка

См. CONTRIBUTING.md для рекомендаций и CHANGELOG.md для истории релизов.

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

Для работы с фронтендом: cd web && pnpm dev (http://127.0.0.1:5173, проксирует /api на :8000) вместе с transcriber serve … --port 8000 в другой консоли.

Релизы: публикация GitHub-релиза запускает .github/workflows/release.yml, который собирает фронтенд, упаковывает его в wheel и публикует на PyPI через trusted publishing.

Лицензия

Apache-2.0 — см. LICENSE.