Skip to main content
Glama
deenesjakoruzh
Novia-RDI-Seafaring

transcriber-mcp

by Novia-RDI-Seafaring
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

dialogue-transcriber

대화를 전사하고 누가 무엇을 말했는지 알아보세요.

CI PyPI License: Apache-2.0 Python

인터뷰, 패널 토론, 회의 녹음 또는 YouTube URL을 지정하면 모든 줄에 화자가 표시된 전사본을 얻을 수 있습니다. 또한 화자 클러스터를 검사하고, 원하는 구간을 듣고, 라벨을 수동으로 수정할 수 있는 웹 UI도 제공됩니다.

리뷰 UI: 화자 클러스터, 파형, 타임라인, 검색 가능한 전사본

작동 방식

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: youtube-transcriber-mcp

빠른 시작

ffmpeg와 ffprobe가 PATH에 있어야 합니다 (macOS에서는 brew install ffmpeg).

# 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 다운로드, 웹 UI의 작업 상태. 삭제해도 안전하며, 다시 빌드됩니다.

  • 전사본: 입력 오디오 옆에 작성됨 (interview.txt), 또는 --output이 가리키는 위치에 작성됨. --output -는 stdout으로 출력합니다.

  • 모델 가중치 (로컬 백엔드): ~/.cache에 한 번 다운로드됨 (Hugging Face / NeMo). Whisper large-v3 다운로드는 약 3GB이므로 첫 로컬 실행은 시간이 걸립니다.

기본 로컬 백엔드를 사용하면 어떤 데이터도 머신 밖으로 나가지 않습니다. --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로 스트리밍하므로 출력을 깔끔하게 파이프할 수 있습니다.

웹 UI

transcriber serve는 FastAPI 백엔드를 실행하고 번들된 React 프론트엔드를 제공합니다. 제공되는 기능:

  • 각 점이 하나의 세그먼트이고 클러스터별로 색상이 지정된 UMAP 산점도 — 올가미로 클러스터를 선택하여 일괄 이름 변경 가능;

  • 세그먼트별 영역이 표시된 연속 파형 — 클릭하거나 스크러빙하여 어떤 구간이든 재생 가능;

  • Gantt 스타일 화자 타임라인;

  • 전체 텍스트 검색이 가능한 가상화된 전사본;

  • 인라인 이름 변경 가능한 화자 칩 (이름 변경은 서버 측에 영구 저장됨);

  • TXT / VTT / SRT 내보내기;

  • 키보드 탐색 (↑/↓ 세그먼트 이동, Space 재생/일시정지, / 검색).

여러 작업을 나란히 실행할 수 있으며, 사이드바에서 추가할 수 있습니다.

serve는 백엔드를 자동으로 선택합니다: OPENAI_API_KEY가 사용 가능하면 (환경 변수 또는 .env) openai, 그렇지 않으면 local. 명시적으로 선택하려면 --backend을 전달하세요. (레거시 단일 작업 Dash UI는 여전히 transcriber ui로 사용할 수 있습니다.)

AI 에이전트용

이 프로젝트는 인간뿐만 아니라 에이전트가 구동하도록 설계되었습니다.

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차원 UMAP입니다.

백엔드

항목

기본값

재정의 방법

전사

faster-whisper large-v3

--backend openai

임베딩

nvidia/speakerverification_en_titanet_large

run_pipeline에 embedder= 전달

클러스터링

UMAP(2) + KMeans + 실루엣

ClusterConfig 전달

YouTube

yt-dlp

YouTubeDownloader 교체

모든 백엔드는 Protocol입니다 — 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

프론트엔드 작업: 다른 셸에서 transcriber serve … --port 8000을 실행한 상태로 cd web && pnpm dev (http://127.0.0.1:5173, /api를 :8000으로 프록시).

릴리스: GitHub 릴리스를 게시하면 .github/workflows/release.yml이 트리거되어 프론트엔드를 빌드하고, 휠에 번들한 후 신뢰할 수 있는 게시(trusted publishing)를 통해 PyPI에 게시합니다.

라이선스

Apache-2.0 — LICENSE 참조.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers