C/C++ 음성-텍스트 변환 (Speech-to-Text, STT) 추론 라이브러리입니다. ggml 런타임 상에서 GGUF 모델을 통해 다양한 STT 모델 제품군을 실행하며, 빠른 GPU 추론을 위한 Metal, Vulkan, CUDA 백엔드와 tinyBLAS로 가속화된 CPU 경로를 지원합니다.

16개의 모델 제품군과 60개 이상의 변체(variants)를 지원하며, 스트리밍(streaming) 및 배치(batch) 방식을 모두 지원합니다. handy-computer 하에 게시되는 모든 모델은

참조 구현(reference implementation)을 대상으로 수치 검증 및 단어 오류율(Word Error Rate, WER) 테스트를 거쳤습니다.

지원 모델:

docs/models/granite-speech.md |
| Voxtral | voxtral-mini-3b-2507 , voxtral-small-24b-2507 (오디오-LLM; 전사 + 번역) |
docs/models/voxtral.md |
| Voxtral Realtime | voxtral-mini-4b-realtime-2602 (스트리밍 오디오-LLM) |
docs/models/voxtral-realtime.md |
| MedASR | medasr (Conformer + CTC, 영어 의료 받아쓰기, 게이티드) |
docs/models/medasr.md |
| MOSS Transcribe-Diarize | moss-transcribe-diarize (오디오-LLM; 영어 + 중국 ASR에 인라인 화자 분리 포함) |
docs/models/moss-transcribe-diarize.md |

각 변형별 모델 카드(model cards)는 docs/models/ 아래에서 확인할 수 있습니다.

cmake -B build
cmake --build build

Apple Silicon에서는 Metal이 자동으로 활성화됩니다. Vulkan (Linux/Windows)의 경우:

# Ubuntu/Debian
sudo apt install build-essential cmake libvulkan-dev glslc libopenblas-dev
cmake -B build -DTRANSCRIBE_VULKAN=ON
...

Windows에서는 Vulkan SDK 설정, Visual Studio 명령어 및 비정상적으로 깊은 체크아웃을 위한 short-build-root 폴백에 대한 전체 빌드 가이드를 참조하십시오.

CUDA (Linux + NVIDIA GPU)의 경우:

# CUDA 툴킷(nvcc)이 PATH에 필요함
cmake -B build -DTRANSCRIBE_CUDA=ON
cmake --build build

libopenblas-dev는 선택 사항이지만 권장됩니다. 호스트 측 디코더를 약 10~15배 가속화합니다. 이것이 없으면 빌드는 자동으로 스칼라 경로로 폴백됩니다.

tinyBLAS (Justine Tunney의 llamafile_sgemm 커널)는 기본적으로 활성화되어 있습니다.

양자화 도구(quantization tool)를 빌드하려면:

cmake -B build -DTRANSCRIBE_BUILD_TOOLS=ON
cmake --build build

지원되는 모든 모델의 사전 구축된 GGUF는 Hugging Face의 handy-computer에서 호스팅됩니다. 각 모델별 문서(위 표에 연결됨)에는 모든 양자화 버전에 대한 직접 다운로드 링크가 포함되어 있습니다. 다른 dtype이나 사전 구축되지 않은 체크포인트가 필요한 경우에만 소스에서 변환하십시오.

변환기는 ASRModel.from_pretrained를 통해 NVIDIA의 NeMo 체크포인트에서 직접 로드됩니다. uv가 필요합니다. parakeet 환경에는 NeMo와 그 의존성이 포함되어 있습니다.

uv run --project scripts/envs/parakeet \scripts/convert-parakeet.py nvidia/parakeet-tdt-0.6b-v2

이 명령은 llama.cpp 스타일의 <slug>-<QUANT>.gguf 명명 규칙 (naming convention)에 따라 models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf를 작성합니다. 오프라인 변환을 위해 로컬 .nemo 경로 또는 압축 해제된 디렉토리를 전달할 수 있습니다.

transcribe-quantize 도구는 참조용 GGUF로부터 더 작은 모델들을 생성합니다. 사용 가능한 프리셋 (presets): F16, Q8_0, Q6_K, Q5_K_M, Q4_K_M.

build/bin/transcribe-quantize \models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-Q4_K_M.gguf \...

build/bin/transcribe-cli -m models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf samples/jfk.wav

입력 파일은 반드시 16 kHz 모노 (mono) WAV 형식이어야 합니다. 다른 형식을 변환하려면 ffmpeg 또는 sox를 사용하세요:

ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav

공식 바인딩 (bindings)은 다른 언어를 위해 C API를 래핑 (wrap) 합니다:

바인딩이 어떻게 생성되고 헤더 (header)와 동기화되어 유지되는지에 대해서는 docs/bindings.md를 참조하세요.

cd build && ctest

일부 테스트는 실제 모델 파일이 필요합니다. 다음 명령으로 테스트를 활성화할 수 있습니다:

cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON
cmake --build build
TRANSCRIBE_PARAKEET_GGUF=path/to/model.gguf ctest --test-dir build

모델 제품군 스모크 테스트 (smoke-test), 수치 검증 (numerical-validation), 그리고 새로운 포트 (port)에 기대되는 벤치마크 패턴에 대해서는 docs/model-family-testing.md를 참조하세요.

Mozilla AI와 그들의 BiR 프로그램에 큰 감사를 표합니다. 이 프로젝트 전체는 구현 방향조차 정해지지 않은 하나의 아이디어로 시작되었습니다. 이는 가능한 한 쉽게 모든 플랫폼에서 전사 (transcription) 모델을 가속화하는 방법에 대한 연구 프로젝트였습니다. BiR 프로그램과 Davide는 연구를 지원하는 데 도움을 주었으며, 결과적으로 제가 ggml 기반의 추론 엔진 (inference engine)을 구현하기로 결정하는 데 기여했습니다. 또한 에이전틱 프로그래밍 (agentic programming) 도구를 사용한 자동화된 모델 포팅 (porting) 실험도 병행했습니다.

Hugging Face는 우리가 지원하는 모든 모델을 호스팅할 수 있도록 프로젝트에 추가 저장 공간을 제공했습니다. 우리는 합리적으로 가능한 한 많은 모델에 대해 표준 참조 (canonical references)를 제공하고자 하며, Hugging Face의 지원은 이를 가능하게 하는 데 도움이 됩니다.

Modal은 프로젝트의 구현 사항이 transformers 또는 nemo 참조 소스와 일치하는지 테스트하고 검증할 수 있도록 GPU 크레딧을 제공하는 데 도움을 주었습니다. 이는 어디에서나 작동하는 프로덕션 등급 (production grade)의 추론 엔진 (inference engine)에 최대한 가깝게 구축하는 것을 보장하는 데 매우 중요합니다. 우리는 정확한 전사 (transcription)를 확보하는 것이 필수적이라고 믿으며, 이를 보장할 수 있는 유일한 방법은 Modal이 제공하는 데 도움을 주는 장기 실행 WER (Word Error Rate) 체크를 통해서입니다. huggingface의 handy-computer 아래에 게시된 모든 모델은 WER 체크를 거쳤으므로, 결과를 신뢰하셔도 좋습니다. 그리고 만약 성능 저하 (regressions)가 발생한다면, 저희가 반드시 수정할 것입니다.

Blacksmith는 이 프로젝트를 위한 많은 CI 러너 (CI runners)를 제공합니다. 이는 transcribe.cpp가 잘 테스트되도록 유지하고 우리의 릴리스가 가능한 한 원활하게 이루어지도록 돕습니다. CI는 빠르며 표준 Github Actions 러너를 즉시 대체할 수 있습니다. 저는 표준 러너를 사용하면서 매우 빠르게 한계에 부딪혔는데, Blacksmith에 연락했을 때 그들이 프로젝트를 위한 러너를 제공해 줄 수 있어 매우 기뻤습니다.

include/transcribe.h Public C API (single header)
src/ Library internals (C++17)
src/arch/parakeet/ Parakeet family implementation
...

transcribe.cpp는 MIT 라이선스(MIT-licensed)를 따릅니다. 자세한 내용은 LICENSE를 참조하세요. 포함된 (Vendored) 제3자 구성 요소 (ggml, miniz — 둘 다 MIT)는 THIRD-PARTY-LICENSES.md에 명시되어 있습니다.