⚠ Translation out of date. See the English CLI reference for Nemotron 3 support.

⚠ 번역이 오래되었습니다

VoiceChat 도구 호출 및 성능에 대한 최신 내용은 영어 문서를 참조하세요.

CLI 레퍼런스

Breeze TTS 2 · BreezeTTS

영어·중국어 음성 합성, 음성 디자인, 참조 음성 복제 및 연출, 스트리밍 오디오 지원 (MLX BF16/8-bit, 24 kHz; 연구·비상업용 라이선스).

speech speak "The quick brown fox jumps over the lazy dog." --engine breeze \
  --instruct "A clear, calm English narrator." --stream -o design.wav

--breeze-model-id: aufklarer/Breeze-TTS-2-MLX-8bit
--breeze-bundle-dir
--breeze-cache-limit-mib: 프로세스 전체에 적용하는 재사용 MLX 캐시 한도(MiB, 선택 사항). 0은 캐싱을 비활성화합니다.
--breeze-reference-text
--breeze-temperature: 0.9
--breeze-top-k: 50
--breeze-top-p: 1
--breeze-cfg-scale: 4
--breeze-max-frames: 750
--breeze-seed: 42
--first-chunk-frames: 3
--chunk-frames: 25

Apple 네이티브 런타임 · PocketTTS

PocketTTS는 speech-swift에 네이티브 CoreML 음성 합성을 추가합니다. 모든 단계는 기본적으로 CPU만 사용합니다. 영어 Alba 프리셋은 24 kHz에서 프레임당 1,920개 샘플(80밀리초)을 스트리밍합니다.

Swift 및 CLI 사용법

speech speak "Hello world." --engine pocket --stream \
  --pocket-bundle-dir /path/to/bundle --pocket-seed 42 -o hello.wav
# --pocket-model-id, --pocket-max-frames, --list-speakers

speech 명령은 로컬 음성 처리의 진입점입니다.

Homebrew로 설치

macOS 15 이상을 실행하는 Apple Silicon Mac에서 Homebrew로 CLI를 설치하세요:

brew install speech
speech --help

기존 설치를 업데이트하려면 brew upgrade speech를 실행하세요.

대안: 소스에서 빌드

speech-swift 소스 디렉터리에서 make build를 실행한 다음 .build/release/speech를 사용하세요. 필수 환경과 소스 빌드 절차는 시작 가이드를 참고하세요.

transcribe

오디오 파일을 텍스트로 전사합니다.

speech transcribe <file> [options]

옵션	기본값	설명
`<file>`		전사할 오디오 파일 (WAV, M4A, MP3, CAF)
`--engine`	`qwen3`	ASR 엔진: `qwen3`, `qwen3-coreml`, `parakeet`, `nemotron`, `omnilingual`, `cohere`, `voxtral`, `moss`, `whisper`
`--model, -m`	`0.6B`	모델 변형: `0.6B`, `1.7B`, 또는 전체 HuggingFace 모델 ID (qwen3 전용) `[whisper]`: `default`, `turbo`, or full CoreML HuggingFace repo ID. `[cohere/voxtral]`: INT5(기본값), INT8, FP16, Hugging Face 모델 ID 또는 로컬 디렉터리. `[moss coreml]`: `int8`(기본값) 또는 `fp16`, `[moss mlx]`: `int5`(기본값) 또는 `int8`. 호환 Hugging Face 저장소 ID나 로컬 디렉터리도 사용할 수 있습니다.
`--max-tokens`	CoreML: `512` MLX: `5120`	`[moss]`가 생성할 최대 전사 토큰 수.
`--kv-cache`	`fp16`	`[moss mlx]` 동적 KV 캐시 정밀도: `fp16` 또는 `int8`.
`--language`		언어 힌트 (선택, omnilingual에서는 무시)
`--window`	`10`	`[omnilingual]` CoreML 윈도 크기(초): `5` 또는 `10`
`--backend`	`coreml`	`[omnilingual]` 백엔드: `coreml` (Neural Engine) 또는 `mlx` (Metal GPU) `[moss]` CoreML은 고정 1,024-token 상태를, MLX는 동적 131,072-token 컨텍스트를 사용합니다.
`--variant`	`300M`	`[omnilingual mlx]` 크기: `300M`, `1B`, `3B`, `7B`
`--bits`	`4`	`[omnilingual mlx]` 양자화 비트: `4` 또는 `8`
`--stream`		VAD를 활용한 스트리밍 전사 활성화
`--max-segment`	`10`	최대 세그먼트 길이(초, 스트리밍)
`--partial`		발화 중 부분 결과 출력 (스트리밍)

예시:

# 기본 전사
speech transcribe recording.wav

# 더 큰 모델 사용
speech transcribe recording.wav --model 1.7B

# CoreML 인코더 (Neural Engine + MLX 디코더)
speech transcribe recording.wav --engine qwen3-coreml

# Parakeet (CoreML) 엔진 사용
speech transcribe recording.wav --engine parakeet

# Omnilingual (CoreML, 1,672개 언어)
speech transcribe recording.wav --engine omnilingual                              # 10초 윈도
speech transcribe recording.wav --engine omnilingual --window 5                     # 5초 윈도

# Omnilingual (MLX, 최대 40초까지 임의의 길이)
speech transcribe recording.wav --engine omnilingual --backend mlx                              # 300M @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 1B                  # 1B @ 4-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 3B --bits 8         # 3B @ 8-bit
speech transcribe recording.wav --engine omnilingual --backend mlx --variant 7B                  # 7B @ 4-bit

# Cohere Transcribe 2B (MLX, 기본값 INT5)
speech transcribe recording.wav --engine cohere
speech transcribe recording.wav --engine cohere --model int8 --language de

# Voxtral Mini 3B (MLX, 기본값 INT5)
speech transcribe recording.wav --engine voxtral
speech transcribe recording.wav --engine voxtral --model int8 --language fr

# MOSS Transcribe Diarize(CoreML 단문)
speech transcribe recording.wav --engine moss
speech transcribe recording.wav --engine moss --model fp16

# MOSS Transcribe Diarize(MLX 128K 오프라인 컨텍스트, INT5 기본)
speech transcribe meeting.wav --engine moss --backend mlx
speech transcribe meeting.wav --engine moss --backend mlx --model int8 --kv-cache int8

# Whisper Large-v3 Turbo (CoreML)
speech transcribe recording.wav --engine whisper
speech transcribe recording.wav --engine whisper --model turbo --language de

# VAD 기반 스트리밍
speech transcribe recording.wav --stream --partial

align

단어 수준 강제 정렬 — 모든 단어에 대한 정확한 타임스탬프를 얻습니다.

speech align <file> [options]

옵션	기본값	설명
`<file>`		오디오 파일
`--text, -t`		정렬할 텍스트 (생략 시 먼저 전사)
`--model, -m`	`0.6B`	전사용 ASR 모델: `0.6B`, `1.7B`, 또는 전체 ID
`--aligner-model`		강제 정렬 모델 ID
`--language`		언어 힌트

예시:

# 자동 전사 후 정렬
speech align recording.wav

# 알려진 텍스트로 정렬
speech align recording.wav --text "Can you guarantee that the replacement part will be shipped tomorrow?"

speak

텍스트-음성 합성.

speech speak "<text>" [options]

옵션	기본값	설명
`<text>`		합성할 텍스트 (`--batch-file` 사용 시 선택)
`--engine`	`qwen3`	TTS 엔진: `qwen3`, `cosyvoice`, `voxcpm2`, `indextts2`, `f5`, `higgs`, `breeze`, `indic-mio`, `magpie` 또는 `magpie-coreml`, `moss-nano`, `fireredtts3`, `moss-voicegenerator`
`--output, -o`	`output.wav`	출력 WAV 파일 경로
`--language`	`english`	언어. `--speaker` 설정 시 생략하면 화자의 원어 방언 사용.
`--stream`		스트리밍 합성 활성화
`--voice-sample`		음성 복제용 참조 오디오 (`qwen3`, `cosyvoice`, `voxcpm2`, `f5`, `higgs`, `indextts2`에서 동작)
`--verbose`		상세한 타이밍 정보 표시

Qwen3-TTS 옵션

옵션	기본값	설명
`--model`	`base`	모델 변형: `base`, `customVoice`, 또는 전체 HF 모델 ID
`--speaker`		화자 음색 (`--model customVoice` 필요)
`--instruct`		스타일 지시 (CustomVoice 모델)
`--list-speakers`		사용 가능한 화자 목록 출력 후 종료
`--temperature`	`0.3`	샘플링 온도
`--top-k`	`50`	Top-k 샘플링
`--max-tokens`	`500`	최대 토큰 수 (500 = 약 40초 오디오)
`--batch-file`		배치 합성용 파일 (한 줄에 하나의 텍스트)
`--batch-size`	`4`	병렬 생성 최대 배치 크기
`--first-chunk-frames`	`3`	첫 스트리밍 chunk의 코덱 프레임 수
`--chunk-frames`	`25`	스트리밍 chunk당 코덱 프레임 수

CosyVoice3 옵션

옵션	기본값	설명
`--speakers`		다화자 대화용 화자 매핑: `s1=alice.wav,s2=bob.wav`
`--cosy-instruct`		스타일 지시 (기본값 재정의). CosyVoice3의 음성 스타일 제어.
`--turn-gap`	`0.2`	대화 턴 간 무음 간격(초)
`--crossfade`	`0.0`	턴 간 크로스페이드 오버랩(초)
`--model-id`		HuggingFace 모델 ID

IndexTTS2 옵션

IndexTTS2는 확장 MLX 번들을 사용하는 zero-shot 음성 복제 엔진입니다. --voice-sample이 필요하며 현재 배치 합성만 실행합니다.

옵션	기본값	설명
`--indextts2-model-id`	`aufklarer/IndexTTS2-MLX-fp16`	HuggingFace 모델 ID. 기본값은 `aufklarer/IndexTTS2-MLX-fp16`입니다.
`--indextts2-bundle-dir`		Hugging Face에서 다운로드하지 않고 로컬 확장 번들을 로드합니다.
`--indextts2-emotion-audio`		선택적 감정/스타일 참조 오디오. 기본값은 화자 참조입니다.
`--indextts2-emotion`		선택적 프리셋 또는 8값 감정 벡터. 프리셋에는 `eager`, `happy`, `excited`, `calm`이 포함됩니다.
`--indextts2-emotion-weight`	`1.0`	`--indextts2-emotion`을 스케일합니다. 화자 정체성이 중요하면 낮게 유지하세요.
`--indextts2-speaking-rate`	`1.0`	`0.5`에서 `1.5`까지의 말하기 속도 배율. `1.0`보다 크면 더 빠릅니다.
`--indextts2-max-pause`		긴 내부 저에너지 일시정지에 대한 선택적 상한(초).
`--indextts2-s2mel-steps`	`15`	S2Mel 플로 스텝(기본 15, 청감 검증; 25는 업스트림과 완전 일치)

F5-TTS 옵션

옵션	기본값	설명
`--f5-reference-text`		참조 전사: --voice-sample의 텍스트 내용(필수)
`--f5-steps`	`16`	플로 매칭 스텝(기본 16, 최고 충실도는 32)
`--f5-cfg-strength`	`2.0`	Classifier-free guidance 강도
`--f5-sway`	`-1.0`	Sway 샘플링 계수
`--f5-speed`	`1.0`	말속도 배율
`--f5-seed`	`0`	재현 가능한 출력을 위한 시드
`--f5-target-rms`	`0.1`	참조 RMS 정규화 목표
`--f5-model-id`		Hugging Face 모델 ID
`--f5-bundle-dir`		로컬 디렉터리에서 번들 로드

Higgs TTS 3 옵션

옵션	기본값	설명
`--higgs-ref-text`		참조 전사: --voice-sample의 텍스트 내용(클로닝 품질 향상)
`--higgs-temperature`	`0.8`	샘플링 온도(기본 0.8)
`--higgs-top-p`		Nucleus 샘플링 임계값(기본 꺼짐)
`--higgs-top-k`		Top-k 샘플링 컷오프(기본 꺼짐)
`--higgs-max-new-tokens`	`2048`	생성 오디오 프레임 상한(초당 25)
`--higgs-seed`	`0`	재현 가능한 출력을 위한 시드
`--higgs-model-id`		Hugging Face 모델 ID
`--higgs-bundle-dir`		로컬 디렉터리에서 번들 로드

예시:

# 기본 TTS
speech speak "Hello, world!" --output hello.wav

# 음성 복제 (Qwen3-TTS)
speech speak "Hello in your voice" --voice-sample reference.wav -o cloned.wav

# 음성 복제 (CosyVoice)
speech speak "Hello in your voice" --engine cosyvoice --voice-sample reference.wav -o cloned.wav

# CosyVoice 다국어
speech speak "Hallo Welt" --engine cosyvoice --language german -o hallo.wav

# 다화자 대화
speech speak "[S1] Hello there! [S2] Hey, how are you?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o dialogue.wav

# 인라인 감정/스타일 태그
speech speak "(excited) Wow, amazing! (sad) But I have to go..." \
    --engine cosyvoice -o emotion.wav

# 결합: 대화 + 감정 + 음성 복제
speech speak "[S1] (happy) Great news! [S2] (surprised) Really?" \
    --engine cosyvoice --speakers s1=alice.wav,s2=bob.wav -o combined.wav

# 커스텀 스타일 지시
speech speak "Hello world" --engine cosyvoice --cosy-instruct "Speak cheerfully" -o cheerful.wav

# 스트리밍 합성
speech speak "Long text here..." --stream

# 파일로부터 배치 합성
speech speak --batch-file texts.txt --batch-size 4

지시 TTS 옵션

실험적: 네이티브 SDK 지원은 main 소스에서 빌드하세요. Homebrew 등 미리 빌드된 CLI 릴리스에는 이 엔진들이 아직 포함되지 않았을 수 있습니다.

구현 (PR #541): main

공개된 MLX 번들: aufklarer/FireRedTTS3-Instruct-MLX-fp32 · aufklarer/MOSS-VoiceGenerator-MLX-bf16

텍스트 인수, --instruct, 번들 디렉터리 또는 호환 모델 ID 중 정확히 하나를 지정하세요. 참조 오디오, 고정 화자, 배치 입력은 지원하지 않습니다.

텍스트와 지시 필드는 각각 UTF-8 32,768바이트로 제한됩니다. 템플릿을 포함해 렌더링한 전체 입력 프롬프트는 4,096토큰 이하여야 합니다. 어느 한도든 넘으면 입력을 거부합니다.

FireRedTTS3-Instruct는 모델과 디코더의 Float32 가중치를 유지합니다. 완성된 오디오를 한 번에 반환하므로 --stream을 생략하세요. --language는 영어와 중국어 별칭을 허용합니다. 생성 한도에 도달하면 잘린 오디오를 성공으로 반환하지 않고 오류를 냅니다.

MOSS-VoiceGenerator는 BF16 언어 가중치와 FP32 합성 코덱을 유지합니다. 점진적 PCM에는 --stream을 사용하세요. --language를 생략하고 언어 요구사항을 --instruct에 넣으세요. 종료 전에 열여섯 코드북을 모두 비웁니다.

지시 준수 품질은 아직 채점하지 않았습니다. 짧은 대본 측정은 시험한 구성만 설명하며 기존 모델의 지연 회귀 검증은 결론을 내리지 못했습니다.

옵션	기본값	설명
`--fireredtts3-bundle-dir`	—	호환 로컬 내보내기 번들. 모델 ID와 둘 중 하나를 선택합니다.
`--fireredtts3-model-id`	—	공개된 호환 MLX 번들 ID. 로컬 디렉터리와 둘 중 하나를 선택합니다.
`--fireredtts3-flow-steps`	10	음향 패치당 흐름 단계 수.
`--fireredtts3-max-patches`	400	생성 한도. 완료 전에 도달하면 오류가 발생합니다.
`--moss-voicegenerator-bundle-dir`	—	호환 로컬 내보내기 번들. 모델 ID와 둘 중 하나를 선택합니다.
`--moss-voicegenerator-model-id`	—	공개된 호환 MLX 번들 ID. 로컬 디렉터리와 둘 중 하나를 선택합니다.
`--moss-voicegenerator-max-frames`	750	생성 한도. 완료 전에 도달하면 오류가 발생합니다.
`--moss-voicegenerator-chunk-frames`	3	PCM 청크당 완전한 코덱 프레임 수(1–32).
`--seed`	2 / 42	요청 시드: FireRedTTS3 기본값 2, MOSS-VoiceGenerator 기본값 42.

FireRedTTS3-Instruct · MOSS-VoiceGenerator

kokoro

Neural Engine(CoreML)의 Kokoro-82M을 이용한 경량 텍스트-음성 변환. Non-autoregressive — 단일 forward pass, 약 45ms 지연.

speech kokoro "<text>" [options]

옵션	기본값	설명
`<text>`		합성할 텍스트
`--voice`	`af_heart`	음색 프리셋 (10개 언어에 걸쳐 50개 제공)
`--language`	`en`	언어 코드: en, es, fr, hi, it, ja, pt, zh, ko, de
`--output, -o`	`kokoro_output.wav`	출력 WAV 파일 경로
`--list-voices`		사용 가능한 음색 전체 목록 출력 후 종료
`--model, -m`		HuggingFace 모델 ID

예시:

# 기본 Kokoro TTS
speech kokoro "Hello, world!" --voice af_heart -o hello.wav

# 프랑스어 음색
speech kokoro "Bonjour le monde" --voice ff_siwis --language fr -o bonjour.wav

# 50개 음색 모두 나열
speech kokoro --list-voices

respond

PersonaPlex 7B를 사용한 full-duplex 음성-음성 대화.

speech respond [options]

옵션	기본값	설명
`--input, -i`		입력 오디오 WAV 파일 (24kHz 모노) (필수)
`--output, -o`	`response.wav`	출력 응답 WAV 파일
`--voice`	`NATM0`	음색 프리셋 (예: NATM0, NATF1, VARF0)
`--system-prompt`	`assistant`	프리셋: `assistant`, `focused`, `customer-service`, `teacher`
`--system-prompt-text`		커스텀 시스템 프롬프트 텍스트 (프리셋 재정의)
`--max-steps`	`200`	12.5Hz에서 최대 생성 스텝 수 (약 16초)
`--stream`		생성 중 오디오 chunk 스트리밍 출력
`--compile`		컴파일된 transformer 활성화 (warmup + kernel fusion)
`--list-voices`		사용 가능한 음색 프리셋 나열
`--list-prompts`		사용 가능한 시스템 프롬프트 프리셋 나열
`--transcript`		모델의 inner monologue 텍스트 출력
`--json`		JSON으로 출력 (전사, 지연, 오디오 경로)
`--verbose`		상세 타이밍 정보 표시

샘플링 재정의

옵션	기본값	설명
`--audio-temp`	`0.8`	오디오 샘플링 온도
`--text-temp`	`0.7`	텍스트 샘플링 온도
`--audio-top-k`	`250`	오디오 top-k 후보
`--repetition-penalty`	`1.2`	오디오 반복 페널티 (1.0 = 비활성)
`--text-repetition-penalty`	`1.2`	텍스트 반복 페널티 (1.0 = 비활성)
`--repetition-window`	`30`	반복 페널티 윈도 (프레임)
`--silence-early-stop`	`15`	조기 종료 전 무음 프레임 수 (0 = 비활성)
`--entropy-threshold`	`0`	조기 종료용 텍스트 엔트로피 임계값 (0 = 비활성)
`--entropy-window`	`10`	조기 종료 전 연속 저엔트로피 스텝 수

예시:

# 기본 음성-음성
speech respond --input question.wav

# 컴파일된 transformer로 여성 음색 사용
speech respond -i question.wav --voice NATF1 --compile

# 응답 스트리밍 및 전사 표시
speech respond -i question.wav --stream --transcript --verbose

voice-chat

NVIDIA Nemotron VoiceChat 11B로 구동되는 Soniqo와 실시간 전이중 대화를 합니다. 기본 protected-head INT5 bundle은 처음 사용할 때 내려받으며, 마이크 모드는 Apple AEC, 스트리밍 RNN-T 자막, 이해하기 쉬운 실시간 지표, 적응형 8→2→1단계 음성 정제, 긴 무음 따라잡기를 막는 제한된 입력 재동기화를 제공합니다.

speech voice-chat [options]

옵션	기본값	설명
`--model, -m`	`aufklarer/VoiceChat-11B-Perception-MLX-int5`	Hugging Face 모델 ID 또는 완전한 로컬 bundle.
`--revision`	`main`	Hub revision.
`--system-prompt`		system prompt 재정의.
`--mcp-config`		MCP 도구 서버용 범용 JSON 설정.
`--mcp-server`	설정된 서버 전체	서버 하나 선택. 반복 지정 가능.
`--mcp-write-policy`	`allow`	쓰기 정책: 즉시 실행하는 `allow`, 모델 확인 `confirm`, 또는 `deny`.
`--mcp-timeout-seconds`	`15`	MCP tool call timeout이며 server startup은 최소 60초를 허용합니다.
`--greet`		모델이 먼저 인사하도록 설정.
`--no-aec`		Apple 음향 에코 제거 비활성화.
`--no-transcript`		실시간 RNN-T 사용자 자막 비활성화.
`--no-rnnt-turn-taking`		NVIDIA RNN-T 턴테이킹 안전 폴백을 비활성화합니다.
`--prebuffer-frames`	`3`	재생 전에 버퍼링할 80 ms 출력 프레임 수.
`--max-buffered-frames`	`8`	오래된 오디오를 버리기 전 대기할 수 있는 80 ms 마이크 프레임 수.
`--max-seconds`		지정한 초 후 실시간 캡처 중지.
`--input`		마이크 대신 오디오 파일 읽기.
`--output, -o`		전체 컨텍스트 22.05 kHz WAV 쓰기.
`--tail-seconds`	`6`	파일 입력 뒤에 붙일 무음 시간.
`--force-turn-at-end`		파일 끝에서 BOS 강제; 회귀 테스트 전용.
`--plain`		고정 재그리기 대시보드 대신 추가 전용 출력을 사용합니다.
`--debug-timeline`		발화와 생성된 발음 종료의 상대 타임스탬프 및 모델이 디코딩한 도구 호출 수명 주기 이벤트를 표시합니다.
`--terminal-width`	`120`	터미널 표시 너비.
`--temperature`	`0`	텍스트 temperature; 0은 greedy.
`--text-top-p`	`1`	텍스트 top-p.
`--guidance`	`0.2`	EAR-TTS guidance 강도.
`--speech-top-p`	`0.95`	EAR-TTS top-p.
`--speech-noise`	`0.001`	EAR-TTS sampling noise.
`--speech-iterations`	`8`	프레임당 EAR-TTS MaskGIT 반복 횟수.
`--realtime-speech-iterations`	`2`	실시간 속도를 보호하기 위해 임시로 사용하는 음성 정제 횟수.
`--live-speech-context-seconds`	`20`	라이브 모드에서 유지할 최근 EAR-TTS 기록입니다. 0은 전체 기록을 유지합니다.

예시:

speech voice-chat

speech voice-chat --model /path/to/complete-bundle --prebuffer-frames 3

speech voice-chat --input question.wav --output response.wav

speech voice-chat --mcp-config Examples/VoiceChatMCP/apple-reminders.json

파일 모드는 오디오 하드웨어 없이 재현할 수 있는 경로입니다. --force-turn-at-end는 제어된 회귀 테스트 전용이며 자연스러운 턴 전환 지연으로 보고하면 안 됩니다.

Apple Reminders 데모는 list_reminders, create_reminder, update_reminder만 공개하고 목록 탐색은 어댑터 내부에서 처리합니다. 한 번의 평탄화된 읽기가 모든 목록을 다루며, 업데이트는 말한 이름을 런타임에서 비공개 ID로 해석합니다. 대시보드는 함수 디코딩 시간, token step, token/s를 오디오 RTF와 별도로 표시합니다.

vad

Pyannote 세그먼테이션을 사용한 오프라인 음성 활동 감지.

speech vad <file> [options]

옵션	설명
`<file>`	분석할 오디오 파일
`--model, -m`	HuggingFace 모델 ID
`--onset`	Onset 임계값 (발화 시작)
`--offset`	Offset 임계값 (발화 종료)
`--min-speech`	최소 발화 길이(초)
`--min-silence`	최소 무음 길이(초)
`--json`	JSON으로 출력

vad-stream

Silero VAD v5를 사용한 스트리밍 음성 활동 감지. 32ms chunks로 오디오를 처리합니다.

speech vad-stream <file> [options]

옵션	설명
`<file>`	분석할 오디오 파일
`--engine`	VAD 엔진: `mlx` (기본) 또는 `coreml`
`--model, -m`	HuggingFace 모델 ID (엔진에 따라 자동 선택)
`--onset`	Onset 임계값
`--offset`	Offset 임계값
`--min-speech`	최소 발화 길이(초)
`--min-silence`	최소 무음 길이(초)
`--json`	JSON으로 출력
`--smart-turn`	세그먼트를 끝내기 전에 각 멈춤을 Smart Turn으로 확인. 문장 중간의 멈춤은 하나의 세그먼트로 합쳐짐
`--turn-threshold`	Smart Turn 완료 임계값(기본 `0.5`)
`--turn-max-silence`	거부된 멈춤 이후 어쨌든 세그먼트를 끝내는 침묵 초(기본 `2.0`)

turn

Smart Turn v3.2(8M 파라미터, CoreML, 23개 언어)로 발화 종료를 감지합니다. 녹음된 발화의 마지막 8초를 채점해 화자가 말을 끝냈을 확률, 완료/미완료 판정, 추론 시간을 출력합니다.

speech turn <file> [options]

옵션	설명
`<file>`	사용자 발화 하나가 담긴 오디오 파일(모든 샘플 레이트). 마지막 8초를 사용
`--threshold`	이 확률 이상이면 발화를 완료로 간주(기본 `0.5`)
`--model, -m`	HuggingFace 모델 ID. 기본값 `aufklarer/Smart-Turn-v3.2-CoreML`
`--model-dir`	`smart_turn.mlmodelc`와 `config.json`이 있는 로컬 디렉터리. 다운로드 건너뜀
`--json`	JSON으로 출력

# Probability, verdict and inference time for one utterance
speech turn utterance.wav

# Custom threshold, JSON output
speech turn utterance.wav --threshold 0.7 --json

# Streaming VAD with Smart Turn confirming each pause
speech vad-stream call.wav --smart-turn --turn-threshold 0.6 --turn-max-silence 1.5

wake

KWS Zipformer를 사용한 온디바이스 키워드 감지 (3.49M 매개변수, CoreML INT8, 실시간의 26배, 영어만 지원).

speech wake <file> [options]

옵션	설명
`<file>`	분석할 오디오 파일
`--keywords`	하나 이상의 키워드. 형식: `"hey soniqo"`, `"hey soniqo:0.15:0.5"` 또는 `"LIGHT UP\|▁ L IGHT ▁UP:0.25:2.0"` (명시적 BPE 조각이 있는 sherpa-onnx 스타일)
`--keywords-file`	키워드 파일, 한 줄에 한 항목
`--model, -m`	HuggingFace 모델 ID. 기본값: `aufklarer/KWS-Zipformer-3M-CoreML-INT8`
`--json`	JSON으로 출력

diarize

화자 분리 — 누가 언제 말했는지 식별합니다.

speech diarize <file> [options]

옵션	기본값	설명
`<file>`		분석할 오디오 파일
`--engine`	`pyannote`	화자 분리 엔진: `pyannote`, `community1`(CoreML + 네이티브 PLDA/VBx) 또는 `sortformer`
`--community1-compute-units`	`ane`	Community-1 CoreML 연산 장치: `ane`, `cpu`, `gpu`, `all`
`--num-speakers`		Community-1의 알려진 정확한 화자 수
`--min-speakers`	`1`	Community-1의 최소 화자 수
`--max-speakers`		Community-1의 최대 화자 수
`--target-speaker`		대상 화자 추출용 등록 오디오 (pyannote 전용)
`--embedding-engine`	`mlx`	화자 임베딩 엔진: `mlx` 또는 `coreml` (pyannote 전용)
`--vad-filter`		Silero VAD로 사전 필터링 (pyannote 전용)
`--rttm`		RTTM 형식으로 출력
`--json`		JSON으로 출력
`--score-against`		DER 계산용 참조 RTTM 파일

예시:

# 기본 화자 분리 (pyannote, 기본값)
speech diarize meeting.wav

# 엔드투엔드 Sortformer (CoreML, Neural Engine)
speech diarize meeting.wav --engine sortformer

# 평가용 RTTM 출력
speech diarize meeting.wav --rttm

# 대상 화자 추출 (pyannote 전용)
speech diarize meeting.wav --target-speaker enrollment.wav

# 참조와 비교 점수 계산
speech diarize meeting.wav --score-against reference.rttm

embed-speaker

오디오에서 화자 임베딩 벡터를 추출합니다.

speech embed-speaker <file> [options]

옵션	설명
`<file>`	화자 음성을 포함한 오디오 파일
`--engine`	WeSpeaker 256차원은 `mlx` (기본) 또는 `coreml`, 영구 화자 식별 CoreML 192차원은 `redimnet2`, CAM++ CoreML 192차원은 `camplusplus`
`--json`	JSON으로 출력

language-id

오디오 파일의 음성 언어를 식별합니다.

speech language-id <file> [options]

옵션	설명
`<file>`	분류할 오디오 파일
`--engine`	추론 엔진: mlx 또는 coreml
`--model`	Hugging Face 모델 ID 재정의
`--top`	표시할 언어 후보 수
`--json`	결과를 JSON으로 출력

speech language-id recording.wav --top 5
speech language-id recording.wav --engine coreml --json

denoise

Neural Engine에서 DeepFilterNet3를 사용해 배경 소음을 제거합니다.

speech denoise <file> [options]

옵션	기본값	설명
`<file>`		입력 오디오 파일
`--output, -o`	`input_clean.wav`	출력 파일 경로
`--model, -m`		HuggingFace 모델 ID

예시:

speech denoise noisy-recording.wav -o clean.wav

compose

Generate 30 s of music from a text prompt using MAGNeT on MLX.

speech compose <prompt> [options]

Option	Default	Description
`<prompt>`		Text prompt describing the music to generate (e.g. "happy rock")
`--output, -o`	`magnet.wav`	Output WAV path (32 kHz mono)
`--variant`	`small-int4`	Model variant: `small-int4`, `small-int8`, `medium-int4`, or `medium-int8`. Resolves to `aufklarer/MAGNeT-{Small,Medium}-30secs-MLX-{4,8}bit`.
`--temperature`	`3.0`	Sampling temperature, annealed linearly per stage.
`--top-p`	`0.9`	Nucleus sampling threshold.
`--cfg-max`	`10.0`	Max classifier-free guidance coefficient.
`--cfg-min`	`1.0`	Min CFG coefficient (annealed alongside the mask schedule).
`--steps`	`20,10,10,10`	Comma-separated decoding iterations per codebook (4 values).
`--seed`		Random seed for reproducible output.

Examples:

# Default: small-int4, ~10 s wall on M-series for a 30 s clip
speech compose "happy rock" -o happy_rock.wav

# Larger model — better prompt following, slower
speech compose "lo-fi hip hop with mellow piano" --variant medium-int4 -o lofi.wav

# Reproducible
speech compose "energetic EDM with synth lead" --seed 42 -o edm.wav

transcribe-batch

오디오 디렉터리를 일괄 전사합니다. 모델은 한 번만 로드됩니다.

speech transcribe-batch <input-dir> [options]

옵션	기본값	설명
`<input-dir>`		전사할 오디오 파일 디렉터리(WAV, FLAC 등)
`--output-dir`		전사 결과 출력 디렉터리
`--engine`	`qwen3`	ASR 엔진(transcribe와 동일한 값)
`--jsonl`		결과를 JSON lines로 출력(파일당 한 줄)

restore

Sidon으로 음성 복원(잡음 제거 + 잔향 제거) — CoreML, 48 kHz 출력.

speech restore <audio-file> [options]

옵션	기본값	설명
`--output, -o`	`input_restored.wav`	출력 WAV 파일 경로(48 kHz)
`--variant`	`fp16`	정밀도 / 번들 변형
`--compute-units`		두 단계의 Core ML 배치: ane, gpu, cpu, all (기본값: 보코더 gpu, 예측기 자동)

separate

음악을 스템으로 분리(vocals, drums, bass, other).

speech separate <input> [options]

옵션	기본값	설명
`--stems`	`vocals,drums,bass,other`	추출할 스템: vocals, drums, bass, other
`--engine`	`umx`	엔진: umx(기본) 또는 htdemucs(고품질)
`--output-dir`		전사 결과 출력 디렉터리

upsample

FlashSR로 오디오 초해상도 — 1스텝 증류 AudioSR, 48 kHz 출력.

speech upsample <audio-file> [options]

옵션	기본값	설명
`--output, -o`	`hr.wav`	출력 WAV 파일 경로(48 kHz)
`--variant`	`int4`	정밀도 / 번들 변형
`--seed`		재현 가능한 출력을 위한 시드

qwen3-tts-coreml

Swift는 0.6B/256 및 1.7B/1024 번들을 지원하며 기본값은 계속 0.6B입니다. 실험적인 1.7B 번들은 기본적으로 CPU를 사용하며, --speaker-embedding으로 미리 준비한 2048채널 Float32 .npy 화자 임베딩을 제공해야 합니다. GPU/ANE 및 iOS는 별도 검증이 필요합니다.

speech qwen3-tts-coreml "<text>" [options]

옵션	기본값	설명
`--output, -o`	`output.wav`	출력 WAV 파일 경로
`--language`	`english`	출력 언어
`--model`		Hugging Face 모델 ID
`--model-directory`	—	로컬 컴파일 모델 번들. `--model` 다운로드보다 우선합니다.
`--speaker-embedding`	—	모델 너비(1024 또는 2048)에 맞는 Float32 `.npy` 화자 임베딩.

vibevoice

Microsoft VibeVoice로 텍스트 음성 변환(MLX).

speech vibevoice "<text>" --voice-cache <cache> [options]

옵션	기본값	설명
`--voice-cache, -v`		vibevoice-encode-voice로 만든 보이스 캐시(필수)
`--steps`		DPM-Solver 추론 스텝 수(높을수록 고품질)
`--cfg`	`1.3`	Classifier-free guidance 강도
`--long-form`		긴 텍스트용 청크 분할 롱폼 합성

vibevoice-encode-voice

참조 녹음과 전사로 VibeVoice 보이스 캐시를 생성.

speech vibevoice-encode-voice <input> "<transcript>" [options]

옵션	기본값	설명
`<input>`		참조 오디오 파일
`<transcript>`		참조 오디오의 전사 텍스트(영어만)
`--output, -o`		출력 보이스 캐시(.safetensors)

translate

MADLAD-400으로 텍스트를 대상 언어로 번역(MLX).

speech translate "<text>" --to <lang> [options]

옵션	기본값	설명
`--to, -t`		대상 언어 코드(ISO 639-1, 예: es, zh, ja)
`--stream`		디코딩과 동시에 스트리밍 출력
`--model`		Hugging Face 모델 ID

⚠ Translation out of date — the Clef CLI section awaits translation. English reference.

clef

Choose from allowed answers using Clef-flash locally on Apple Silicon. Development preview.

speech clef decide request.json
speech clef decide request.json --model-dir /path/to/Clef-flash-9B-MLX-4bit
speech clef decide request.json --offline --max-tokens 4096

The request contains text in state and an ordered questions array. Each field has an id and a type: choice with a choices map, noul for true/false, or score with ordered levels. Output is JSON with probabilities, selected answers, token count, model-load time, and decision time.

By default, the command downloads aufklarer/Clef-flash-9B-MLX-4bit. Use --model-dir for existing files or --offline for the cache. The token limit defaults to 4096 and accepts 1–16384. See the Clef guide for a complete request and measured memory use.

gliner

GLiNER2.5-Decide(MLX)로 지정한 레이블에 따라 텍스트를 분류하고 엔터티 스팬을 추출합니다. 개발 프리뷰이며 아직 릴리스에 포함되지 않았습니다. 텍스트를 생략하면 stdin에서 읽습니다.

speech gliner classify "<text>" --labels <a,b,c> [options]
speech gliner extract "<text>" --labels <a,b,c> [options]

옵션	기본값	설명
`--variant`	int8	다운로드할 공개 가중치: fp32, fp16 또는 int8
`--model`		Hugging Face 저장소 재지정
`--model-dir`		다운로드 대신 로컬 모델 디렉터리 사용
`--labels`		쉼표로 구분한 후보 레이블(1~255개, 중복 불가)
`--description`		label=text 형식의 레이블 설명, 반복 지정 가능
`--task`	action	스키마 프롬프트에 넣을 작업 이름(classify 전용)
`--threshold`	0.5	스팬 최소 점수(extract 전용)
`--evaluate-layers`		인코더를 레이어별로 평가해 최대 메모리 사용량을 낮춤
`--json`		모든 레이블 확률 또는 UTF-16 오프셋 스팬과 처리 시간을 JSON으로 출력

avatar-motion

음성에서 NVIDIA Audio2Face-3D 아바타 모션 계수 프레임 생성.

speech avatar-motion <input> [options]

옵션	기본값	설명
`--output, -o`	`avatar-motion.jsonl`	출력 JSONL 파일 경로
`--model`	`…James-MLX`	아바타 아이덴티티 번들(기본 James, Claire·Mark 제공)
`--verbose`		소요 시간과 프레임 수 출력

MOSS-TTS-Nano

--voice-sample로 음성을 복제하며 참조 전사문은 필요하지 않습니다. 모노 참조는 스테레오로 복제하고 48 kHz로 리샘플링한 뒤 80 ms 경계까지 패딩합니다. 참조를 한 번 인코딩하면 여러 요청에서 코드를 재사용할 수 있습니다.

speech speak "Hello world." --engine moss-nano -o hello.wav
speech speak "The weather is nice today." --engine moss-nano \
  --voice-sample reference.wav --moss-nano-seed 1 -o cloned.wav
speech speak "Hello world." --engine moss-nano --stream --play -o streamed.wav

`--moss-nano-model`	aufklarer/MOSS-TTS-Nano-100M-CoreML	모델 저장소 또는 로컬 디렉터리
`--moss-nano-compute-units`	cpu	cpu 또는 gpu
`--moss-nano-max-frames`	300	최대 80 ms 프레임 수; 자연 종료 필수
`--moss-nano-seed`	0	재현 가능한 Swift 샘플링 시드

MOSS-TTS-Nano

Voxtral TTS

Voxtral 4B TTS 2603은 VoxtralTTS 모듈로 Apple Silicon에서 로컬 실행되며, 프리셋 음성 20개, 언어 9개, 24 kHz 모노 음성을 지원합니다.

speech speak "Hello, welcome to Voxtral." --engine voxtral --voxtral-voice casual_male --stream --voxtral-chunk-frames 3 -o hello.wav
speech speak --engine voxtral --list-speakers
speech speak "Bonjour." --engine voxtral --voxtral-voice fr_female --voxtral-max-frames 500 --voxtral-seed 0 -o bonjour.wav

사전 설정 음성만 지원하며 참조 오디오 복제는 지원하지 않습니다. SDK, CLI, WebSocket 및 HTTP PCM에서 생성 중인 오디오를 출력합니다. 입력 텍스트는 처음에 전체를 제공해야 합니다. 모델 가중치는 CC BY-NC 4.0 라이선스를 사용합니다.

Voxtral TTS 가이드 읽기

Fish Audio Drama 3

Drama 3의 실험적 네이티브 MLX 지원은 FishAudioDrama3Model로 제공됩니다. 350억 매개변수의 혼합 어텐션 MoE, 시간축 오디오 타워와 Fish DAC 코덱으로 44.1 kHz 모노 오디오를 생성합니다. 4비트 체크포인트는 Apple M5 Pro에서 텍스트 생성, 참조 음성 복제 및 CLI 출력의 파형과 독립 ASR 검증을 통과했습니다. 8비트와 BF16은 아직 검증되지 않았습니다.

기본 메모리 모드는 balanced입니다. 각 처리 단계가 끝날 때 유휴 MLX 캐시가 512 MiB를 초과하면 해제합니다. 전체 메모리 한도는 아니며 전역 할당자 한도는 변경하지 않습니다. --fish-drama3-memory-mode unrestricted 또는 memoryOptions: .unrestricted로 사전 로딩과 기존 캐시 동작을 선택할 수 있습니다.

텍스트만 생성할 때는 참조 인코더 가중치 794.4 MiB의 로딩을 지연합니다. 첫 참조 인코딩에서 로드한 후 유지하므로 그때까지 codec.safetensors 파일을 사용할 수 있어야 합니다. 미리 계산한 참조 코드에는 인코더가 필요하지 않습니다.

전체 입력 텍스트를 제공하세요. 음성 복제에는 참조 녹음과 정확한 전사가 필요합니다. 화자 태그 0–15와 인라인 감정 제어를 지원합니다. generateStreaming, generateStream, --stream으로 PCM 스트리밍을 지원합니다. 기본 청크는 코덱 프레임 3개로 약 139ms의 오디오입니다. 긴 텍스트 자동 분할과 스트리밍 텍스트 입력은 아직 지원하지 않습니다. 프레임 한도에 도달하면 오류가 발생합니다.

speech speak "Hello from Drama 3." --engine fish-drama3 --fish-drama3-bundle-dir /path/to/bundle -o hello.wav
speech speak "Hello from Drama 3." --engine fish-drama3 --stream --fish-drama3-chunk-frames 3 -o streamed.wav
speech speak "Hello in the reference voice." --engine fish-drama3 --voice-sample reference.wav --fish-drama3-reference-text "The exact reference transcript." --seed 42 -o cloned.wav

import FishAudioTTS
let model = try await FishAudioDrama3Model.fromBundle(bundleURL, memoryOptions: .balanced)
let pcm = try await model.generate(text: "Hello from Drama 3.", options: .init(seed: 42))

옵션	기본값
`--fish-drama3-model-id`	`mlx-community/fish-audio-drama-3-4bit`
`--fish-drama3-bundle-dir`	`—`
`--fish-drama3-reference-text`	`—`
`--fish-drama3-max-frames`	`2048`
`--fish-drama3-temperature`	`1`
`--fish-drama3-top-k`	`30`
`--fish-drama3-top-p`	`0.9`
`--voice-sample`	`—`
`--seed`	`0`
`--stream`	`false`
`--fish-drama3-chunk-frames`	`3`
`--fish-drama3-memory-mode`	`balanced`

Fish Audio로 제작되었습니다. 번들에 Community License와 NOTICE가 포함됩니다.

4비트 벤치마크