Gemini 텍스트 음성 변환
Google Gemini TTS를 사용하여 텍스트에서 자연스럽고 표현력 있는 음성을 생성합니다. 70개 이상의 언어, 30개의 사전 제작된 음성, 자연어 프롬프트 및 오디오 태그를 통한 스타일 제어를 지원합니다.
요구 사항: Node.js 18+, ffmpeg,
@google/genainpm 패키지,GEMINI_API_KEY환경 변수.
사용 가능한 스크립트
scripts/generate-tts.mjs— 단일 요청 일관성, 무음 기반 분할, 자동 트리밍을 지원하는 올인원 TTS 생성기입니다.
빠른 시작
단일 텍스트 음성 변환
npm install @google/genai
GEMINI_API_KEY=your-key node scripts/generate-tts.mjs \
--text "안녕하세요, 저희 제품에 오신 것을 환영합니다!" \
--output-dir public/vo \
--voice Kore
여러 세그먼트 음성 해설 (일관된 음성)
segments.json 파일을 생성합니다:
[
{ "id": "intro", "text": "저희 제품 출시에 오신 것을 환영합니다." },
{ "id": "features", "text": "여러분이 좋아하실 세 가지 기능을 소개합니다." },
{ "id": "close", "text": "지금 저희 웹사이트에서 시작해보세요." }
]
실행:
GEMINI_API_KEY=your-key node scripts/generate-tts.mjs \
--segments segments.json \
--output-dir public/vo \
--voice Kore \
--director-notes "톤: 따뜻함, 자신감, 영감. 스타일: 보컬 미소를 머금은 전문 내레이터. 억양: 중립 미국 영어. 속도: 적당함."
출력 (JSON to stdout):
{
"success": true,
"segments": [
{ "id": "intro", "file": "public/vo/vo-intro.mp3", "duration": 3.25 },
{ "id": "features", "file": "public/vo/vo-features.mp3", "duration": 4.10 },
{ "id": "close", "file": "public/vo/vo-close.mp3", "duration": 2.80 }
],
"totalDuration": 10.15,
"fullAudioFile": "public/vo/vo-full.wav"
}
스크립트 옵션
| 플래그 | 기본값 | 설명 |
|---|---|---|
--segments FILE | — | [{id, text}] 세그먼트 정의가 포함된 JSON 파일 |
--text TEXT | — | 생성할 단일 텍스트 (--segments 대안) |
--output-dir DIR | — | 오디오 파일 출력 디렉토리 (필수) |
--voice NAME | Kore | 사전 제작된 음성 이름 (Voices 표 참조) |
--model NAME | gemini-3.1-flash-tts-preview | Gemini TTS 모델 ID |
--director-notes TEXT | — | 연기 가이드: 스타일, 속도, 억양, 호흡, 발음. 성별/연령은 제어하지 않습니다 (--voice 사용). |
--retries N | 3 | API 오류 시 최대 재시도 횟수 |
--trim / --no-trim | --trim | 세그먼트 경계에서 무음 제거 |
--format FORMAT | mp3 | 출력 형식: mp3 또는 wav |
종료 코드
| 코드 | 의미 |
|---|---|
| 0 | 성공 |
| 1 | 필수 인수 또는 환경 변수 누락 |
| 2 | 재시도 소진 후 API 오류 |
| 3 | ffmpeg 미설치 또는 처리 실패 |
| 4 | 파일 I/O 오류 |
작동 방식 (다중 세그먼트)
Gemini TTS는 별도의 API 요청 간에 음성 일관성을 보장하지 않습니다. 스크립트는 다음 방법으로 이 문제를 해결합니다:
- 모든 세그먼트를
[3초 일시 정지]마커가 포함된 하나의 프롬프트로 결합 - 단일 API 호출로 하나의 연속 오디오 파일 생성
- 적응형 임계값(시작: noise=-35dB, d=1.5s, 점진적으로 완화)을 사용하여 ffmpeg
silencedetect로 무음 간격 감지. 정확히 일치하는 항목이 있으면 직접 사용합니다. 임계값 점프가 발생하면(너무 적음 → 너무 많음) 더 빠른 말하기 속도로 오디오를 재생성하여 세그먼트 간 무음을 더 뚜렷하게 만든 후 감지를 재시도합니다. - 무음 중간 지점에서 분할하여 개별 세그먼트 파일 생성
- 각 세그먼트에서 잔여 무음 패딩(~1.5s/측면)을 제거하고 0.15s의 호흡 공간 유지
모델
| 모델 | 최적 용도 |
|---|---|
gemini-3.1-flash-tts-preview | 최신, 가장 제어 가능, 200개 이상의 오디오 태그 (기본값) |
gemini-2.5-flash-preview-tts | 빠름, 우수한 품질, 일반 용도 |
gemini-2.5-pro-preview-tts | 최고 품질, 복잡한 연기 |
음성
30개의 사전 제작된 음성:
| 음성 | 성별 | 특성 | 음높이 |
|---|---|---|---|
| Achernar | 여성 | 부드러움 | 높음 |
| Achird | 남성 | 친근함 | 중저음 |
| Algenib | 남성 | 거친 | 낮음 |
| Algieba | 남성 | 매끄러움 | 낮음 |
| Alnilam | 남성 | 단호함 | 중저음 |
| Aoede | 여성 | 경쾌함 | 중간 |
| Autonoe | 여성 | 밝음 | 중간 |
| Callirrhoe | 여성 | 편안함 | 중간 |
| Charon | 남성 | 정보 전달 | 낮음 |
| Despina | 여성 | 매끄러움 | 중간 |
| Enceladus | 남성 | 숨 쉬는 듯한 | 낮음 |
| Erinome | 여성 | 또렷함 | 중간 |
| Fenrir | 남성 | 흥분됨 | 중저음 |
| Gacrux | 여성 | 성숙함 | 중간 |
| Iapetus | 남성 | 또렷함 | 중저음 |
| Kore | 여성 | 단호함 | 중간 |
| Laomedeia | 여성 | 경쾌함 | 높음 |
| Leda | 여성 | 젊음 | 높음 |
| Orus | 남성 | 단호함 | 중저음 |
| Puck | 남성 | 경쾌함 | 중간 |
| Pulcherrima | 남성 | 적극적 | 중간 |
| Rasalgethi | 남성 | 정보 전달 | 중간 |
| Sadachbia | 남성 | 활기참 | 낮음 |
| Sadaltager | 남성 | 지식이 풍부함 | 중간 |
| Schedar | 남성 | 고름 | 중저음 |
| Sulafat | 여성 | 따뜻함 | 중간 |
| Umbriel | 남성 | 편안함 | 중저음 |
| Vindemiatrix | 여성 | 부드러움 | 중간 |
| Zephyr | 여성 | 밝음 | 높음 |
| Zubenelgenubi | 남성 | 캐주얼 | 중저음 |
감독의 노트 (--director-notes)
선택한 음성에 대한 연기 가이드입니다. 중요한 것만 정의하세요. 과도한 지정은 모델의 창의성을 제한하고 결과를 악화시킬 수 있습니다.
가장 일반적인 세 가지 지시 사항은 스타일, 속도, 억양이지만, 연기와 관련된 모든 사용자 지정 지시 사항을 포함할 수 있습니다.
- 스타일 — 감정적 특성과 전달 특성. 설명적으로 작성하세요:
"전염성 있는 열정 — 듣는 사람이 신나는 일에 참여하고 있다고 느껴야 함"이 단순히"energetic"보다 더 효과적입니다. 특성을 계층화하고 "보컬 미소"와 같은 음성 해설 업계 용어를 사용할 수 있습니다. - 속도 — 전반적인 속도와 리듬 변화.
"가능한 한 빠르게 말하기"부터"매우 느리고 유연하게, 단어가 서로 번지며, 긴급함이 전혀 없음"까지 다양할 수 있습니다. - 억양 — 구체적으로 지정하세요.
"영국 크로이던에서 들을 수 있는 영국 영어"가"영국 억양"보다 훨씬 효과적입니다.
--director-notes "스타일: 열정적이고 건방진 GenZ 뷰티 유튜버. 속도: 매우 빠름, 숏폼 비디오 인플루언서처럼 빠른 전달. 억양: 라구나 비치 출신의 사우스 캘리포니아 밸리 걸."
오디오 태그
세그먼트 텍스트에 인라인 [대괄호]를 사용하여 단어별 제어를 할 수 있습니다. 감독의 노트를 로컬에서 재정의합니다.
[whispers] [shouting] [excited] [serious] [short pause] [laughs] [very fast] [very slow] [sarcastic] [curious]
창의적인 태그도 작동합니다: [like dracula], [whispering conspiratorially]
예시: "[excited] 이것이 모든 것을 바꿉니다! [short pause] 어떻게 하는지 보여드리겠습니다."
참고 자료
- 프롬프팅 가이드 — 스타일, 감정 및 억양을 위한 고급 프롬프트 엔지니어링