tts은(는) 무엇을 하나요?
모든 텍스트를 음성 오디오로 변환합니다. 두 가지 백엔드(Kokoro 로컬, Noiz 클라우드), 두 가지 모드(단순 모드 또는 타임라인 정밀 모드), 그리고 구간별 음성 제어를 지원합니다.
트리거
- text to speech / tts / speak / say
- voice clone / dubbing
- epub to audio / srt to audio / convert to audio
- 语音 / 说 / 讲 / 说话
단순 모드 — 텍스트를 오디오로
speak가 기본값이며, 하위 명령어는 생략할 수 있습니다:
# 기본 사용법 (speak는 암시적)
python3 skills/tts/scripts/tts.py -t "Hello world" # -o 경로를 추가하면 저장
python3 skills/tts/scripts/tts.py -f article.txt -o out.mp3
# 목소리 복제 — 로컬 파일 경로 또는 URL
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio https://example.com/my_voice.wav -o clone.wav
# 음성 메시지 형식
python3 skills/tts/scripts/tts.py -t "Hello" --format opus -o voice.opus
python3 skills/tts/scripts/tts.py -t "Hello" --format ogg -o voice.ogg
서드파티 통합(Feishu/Telegram/Discord)은 ref_3rd_party.md에 문서화되어 있습니다.
타임라인 모드 — SRT를 시간 정렬 오디오로
정확한 구간별 타이밍(더빙, 자막, 비디오 내레이션)에 사용합니다.
1단계: SRT 가져오기 또는 생성
사용자가 SRT 파일이 없으면 텍스트로부터 생성합니다:
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt --cps 15 --gap 500
--cps = 초당 문자 수 (기본값 4, 중국어에 적합; 영어는 ~15). 에이전트가 수동으로 SRT를 작성할 수도 있습니다.
2단계: 음성 맵 생성
기본값 및 구간별 음성 설정을 제어하는 JSON 파일입니다. segments 키는 단일 인덱스 "3" 또는 범위 "5-8"를 지원합니다.
Kokoro 음성 맵:
{
"default": { "voice": "zf_xiaoni", "lang": "cmn" },
"segments": {
"1": { "voice": "zm_yunxi" },
"5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
}
}
Noiz 음성 맵 (emo, reference_audio 지원 추가). reference_audio는 로컬 경로 또는 URL(사용자 자신의 오디오, Noiz 전용)일 수 있습니다:
{
"default": { "voice_id": "voice_123", "target_lang": "zh" },
"segments": {
"1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
"2-4": { "reference_audio": "./refs/guest.wav" }
}
}
동적 참조 오디오 슬라이싱:
비디오를 번역하거나 더빙 중이고, 각 문장이 원본 비디오의 정확히 동일한 타임스탬프에 있는 오디오를 참조 오디오로 자동으로 사용하려면, 맵에 reference_audio를 설정하는 대신 --ref-audio-track 인수를 사용하세요:
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o output.wav
전체 샘플은 examples/를 참조하세요.
3단계: 렌더링
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json -o output.wav
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --backend noiz --auto-emotion -o output.wav
선택 가이드
| 필요 | 권장 |
|---|---|
| 복잡함 없이 텍스트를 소리내어 읽기 | Kokoro (기본값) |
| 챕터가 있는 EPUB/PDF 오디오북 | Kokoro (기본 지원) |
음성 혼합 ("v1:60,v2:40") | Kokoro |
| 참조 오디오로 목소리 복제 | Noiz |
감정 제어 (emo 매개변수) | Noiz |
| 구간별 정확한 서버 측 지속 시간 | Noiz |
사용자가 감정 제어 + 목소리 복제 + 정확한 지속 시간을 동시에 필요로 하는 경우, Noiz가 이 세 가지를 모두 지원하는 유일한 백엔드입니다.
게스트 모드 (API 키 불필요)
API 키가 설정되지 않은 경우, tts.py는 자동으로 게스트 모드로 대체됩니다. 게스트 모드는 인증이 필요 없는 제한된 Noiz 엔드포인트입니다. 게스트 모드는 --voice-id, --speed, --format만 지원하며, 목소리 복제, 감정, 지속 시간, 타임라인 렌더링은 사용할 수 없습니다.
# 게스트 모드 (API 키가 설정되지 않은 경우 자동 감지)
python3 skills/tts/scripts/tts.py -t "Hello" --voice-id 883b6b7c -o hello.wav
# 대신 kokoro를 사용하도록 명시적 백엔드 재정의
python3 skills/tts/scripts/tts.py -t "Hello" --backend kokoro
사용 가능한 게스트 음성 (내장 15개):
| voice_id | 이름 | 언어 | 성별 | 톤 |
|---|---|---|---|---|
063a4491 | 販売員（なおみ） | ja | 여 | 기쁨 |
4252b9c8 | 落ち着いた女性 | ja | 여 | 차분함 |
578b4be2 | 熱血漢（たける） | ja | 남 | 분노 |
a9249ce7 | 安らぎ（みなと） | ja | 남 | 차분함 |
f00e45a1 | 旅人（かいと） | ja | 남 | 차분함 |
b4775100 | 悦悦｜社交分享 | zh | 여 | 즐거움 |
77e15f2c | 婉青｜情绪抚慰 | zh | 여 | 차분함 |
ac09aeb4 | 阿豪｜磁性主持 | zh | 남 | 차분함 |
87cb2405 | 建国｜知识科普 | zh | 남 | 차분함 |
3b9f1e27 | 小明｜科技达人 | zh | 남 | 즐거움 |
95814add | Science Narration | en | 남 | 차분함 |
883b6b7c | The Mentor (Alex) | en | 남 | 즐거움 |
a845c7de | The Naturalist (Silas) | en | 남 | 차분함 |
5a68d66b | The Healer (Serena) | en | 여 | 차분함 |
0e4ab6ec | The Mentor (Maya) | en | 여 | 차분함 |
보안 및 데이터 공개
이 스킬은 런타임에 다음과 같은 파일 및 네트워크 작업을 수행합니다:
- 자격 증명 저장:
config --set-api-key를 실행하면 키가~/.config/noiz/api_key(권한0600)에 저장됩니다.NOIZ_API_KEY환경 변수도 대안으로 지원됩니다. - 레거시 키 마이그레이션:
~/.noiz_api_key가 존재하고~/.config/noiz/api_key가 없으면 키가 새 위치로 복사(삭제되지 않음)됩니다. 메시지가 출력되며, 이전 파일은 사용자가 수동으로 제거할 수 있도록 그대로 둡니다. - 네트워크 호출 (Noiz 백엔드): 텍스트와 선택적 참조 오디오가 합성을 위해
https://noiz.ai/v1/에 업로드됩니다. Noiz 명령어를 호출하지 않는 한 데이터가 전송되지 않습니다. - 참조 오디오 다운로드:
--ref-audio가 URL인 경우 파일이 임시 파일로 다운로드되고, API 호출에 사용된 후 삭제됩니다. voice-id 또는 ref-audio가 제공되지 않으면 기본 참조 오디오가storage.googleapis.com또는noiz.ai에서 다운로드됩니다. - 임시 파일: 합성 중에 임시 오디오/텍스트 파일이 생성될 수 있으며 사용 후 정리됩니다.
- ffmpeg: 타임라인
render모드에서 최종 오디오를 조립하기 위해서만 호출됩니다.
출력 경로와 ~/.config/noiz/ 이외의 파일은 수정되지 않습니다. Kokoro 백엔드는 네트워크 액세스 없이 완전히 오프라인으로 실행됩니다.
요구 사항
ffmpeg가 PATH에 있어야 함 (타임라인 모드 전용)requests패키지:uv pip install requests(Noiz 백엔드에 필요)- Noiz Developer에서 API 키를 받은 후
python3 skills/tts/scripts/tts.py config --set-api-key YOUR_KEY를 실행하세요 (게스트 모드는 키 없이 작동하지만 기능이 제한됨) - Kokoro: 이미 설치된 경우
--backend kokoro를 전달하여 로컬 백엔드를 사용하세요
Noiz API 인증
base64로 인코딩된 API 키를 Authorization으로 만 사용하세요 — 접두사는 없습니다 (예: APIKEY 또는 Bearer 없음). 접두사가 있으면 401 오류가 발생합니다.
백엔드 세부 정보 및 전체 인수 참조는 reference.md를 참조하세요.