Blog Audio -- 블로그 게시물을 위한 Gemini TTS 내레이션
Google Gemini TTS를 사용하여 블로그 콘텐츠의 전문 오디오 내레이션을 생성합니다. 세 가지 모드: 요약(200-300단어 음성 개요), 전체 기사 읽어주기, 또는 두 명의 스피커 팟캐스트 대화. 30개 음성, 80개 이상의 언어, HTML5 임베드 출력.
빠른 참조
| 명령어 | 설명 |
|---|---|
/blog audio generate <file> | 블로그 게시물의 오디오 내레이션 생성 |
/blog audio voices | 사용 가능한 음성과 특성 표시 |
/blog audio setup | Gemini TTS API 키 확인/설정 |
사전 요구 사항
- Python 3.11+ (
run.py가 가상 환경을 자동 관리) GOOGLE_AI_API_KEY환경 변수 (blog-image에서 사용하는 키와 동일)- FFmpeg (WAV-MP3 변환용; 없으면 WAV로 대체)
항상 run.py 래퍼 사용
# 올바른 사용법:
python3 scripts/run.py generate_audio.py --text "..." --voice Charon --json
# 잘못된 사용법:
python3 scripts/generate_audio.py --text "..." # 가상 환경 없이 실패
API 키 확인 (게이트 패턴)
오디오를 생성하기 전에 API 키를 확인하세요:
echo $GOOGLE_AI_API_KEY
- 설정된 경우: 생성 진행
- 설정되지 않은 경우: 사용자 안내:
"오디오 생성에는 Google AI API 키가 필요합니다. https://aistudio.google.com/apikey에서 무료로 받을 수 있습니다.
그런 다음 설정하세요:
export GOOGLE_AI_API_KEY=your-key이는/blog image에서 사용하는 키와 동일합니다. 이미지 생성이 작동하면 오디오도 작동합니다." - 내부적으로 호출될 때 (blog-write에서): 키가 없으면 조용히 반환합니다. 절대로 작성 워크플로를 차단하지 마십시오.
설정
/blog audio setup:
GOOGLE_AI_API_KEY가 환경에 설정되어 있는지 확인- blog-image가 설정된 경우 (
.mcp.json확인), 키를 이미 사용 가능 - 그렇지 않으면 사용자를 https://aistudio.google.com/apikey로 안내
- dry run으로 확인:
python3 scripts/run.py generate_audio.py --text "Test" --dry-run --json
음성 선택
/blog audio voices:
references/voices.md를 로드하고 음성 카탈로그를 사용자에게 표시합니다.
사용자에게 선호하는 음성을 묻거나 콘텐츠 유형에 따라 추천:
- 기사 내레이션: Charon (정보 전달) 또는 Sadaltager (지식 전달)
- 튜토리얼/방법: Achird (친근함) 또는 Sulafat (따뜻함)
- 뉴스/분석: Rasalgethi (정보 전달) 또는 Schedar (중립)
- 라이프스타일/웰빙: Aoede (가벼움) 또는 Vindemiatrix (부드러움)
- 대화 호스트: Puck (경쾌함) 또는 Laomedeia (경쾌함)
- 대화 전문가: Kore (확신) 또는 Charon (정보 전달)
생성 워크플로
/blog audio generate <file>:
1단계: 블로그 게시물 읽기
파일을 읽고 다음을 추출:
- 제목 (H1 또는 프론트매터에서)
- 전체 내용 (마크다운 본문)
- 대략적인 단어 수
2단계: 모드 선택
사용자에게 묻기 (또는 --mode를 지정한 경우 자동 선택):
| 모드 | 사용 시기 | 출력 |
|---|---|---|
| 요약 | 빠른 오디오 개요 (1-2분) | 200-300단어 음성 요약 |
| 전체 | 완전한 읽어주기 (5-15분) | 자연스러운 음성으로 전체 기사 |
| 대화 | 팟캐스트 스타일 (3-8분) | 기사에 대한 두 사람 대화 |
3단계: 텍스트 준비
중요: Claude가 텍스트를 준비합니다. 스크립트는 TTS만 수행합니다.
요약 모드: 기사에 대한 200-300단어 음성 요약을 작성합니다. 규칙:
- 글로 쓰는 것이 아니라 자연스러운 말로 작성
- 기사의 핵심 발견 또는 답변으로 시작
- 3-5가지 주요 내용 포함
- 실행 가능한 조언으로 마무리
- 마크다운 없음, "이 기사에서는..." 없음, 메타 논평 없음
- 대화형 전환 사용 ("여기서 중요한 것은...", "핵심 발견은...")
전체 모드: 마크다운 내용을 깨끗한 음성 텍스트로 변환:
- 제목을 자연스러운 전환으로 변경 ("다음으로, ...을 살펴보겠습니다")
- 링크를 일반 텍스트로 변경 (URL 제거, 앵커 텍스트 유지)
- 이미지 및 차트: 생략하거나 간략히 설명 ("데이터가 보여주듯이...")
- 코드 블록: 구두로 설명 ("코드는 for-loop을 사용하여...")
- 목록: 자연스러운 문장으로 변환
- 프론트매터, 스키마 마크업, HTML 태그 제거
- 간단한 소개 추가: "이것은 [제목], [날짜]에 게시되었습니다."
대화 모드: 기사에 대한 2인 대화 스크립트 작성:
- 화자1 = 호스트 (호기심 많고 좋은 질문을 함)
- 화자2 = 전문가 (지식이 풍부하고 명확한 답변을 제공)
- 각 줄 형식:
[화자1] 여기서 핵심은 무엇인가요? - 기사의 주요 내용을 대화 형식으로 다룸
- 15-25개의 교환 (약 3-8분 생성)
- 자연스럽고 어색하지 않게 ("정말 좋은 지적이네요" vs "실제로, 연구가 나타내듯이")
4단계: 음성 선택
사용자가 음성을 선택했으면 그 음성을 사용합니다. 그렇지 않으면 모드에 따라 추천:
- 요약/전체: 기본 Charon (정보 전달)
- 대화: 기본 Puck (호스트) + Kore (전문가)
5단계: 오디오 생성
준비된 텍스트를 임시 파일에 작성한 후 호출:
# 단일 음성 (요약 또는 전체 모드)
python3 scripts/run.py generate_audio.py \
--text-file /tmp/blog_audio_prepared.txt \
--voice Charon \
--model flash \
--output /path/to/audio/post-slug.mp3 \
--json
# 두 음성 (대화 모드)
python3 scripts/run.py generate_audio.py \
--text-file /tmp/blog_audio_dialogue.txt \
--voice Puck \
--voice2 Kore \
--model pro \
--output /path/to/audio/post-slug-dialogue.mp3 \
--json
모델 선택:
flash(기본값): 빠르고 저렴합니다. 요약 및 표준 내레이션에 적합.pro: 더 높은 품질. 대화 모드 또는 프리미엄 콘텐츠에 사용.
6단계: 제공
결과를 사용자에게 제시:
- 파일 경로 -- 오디오가 저장된 위치
- 길이 -- 사람이 읽을 수 있는 형식 (예: "3:42")
- 임베드 코드 -- 붙여넣기 가능한 HTML5 오디오 태그
- 비용 -- 예상 API 비용
- 배치 제안 -- 블로그 게시물에 임베드를 삽입할 위치
임베드 가이드
표준 HTML (Hugo, Jekyll, 정적 사이트)
<audio controls preload="metadata">
<source src="audio/post-slug.mp3" type="audio/mpeg">
브라우저가 오디오 요소를 지원하지 않습니다.
</audio>
MDX (Next.js, Gatsby)
<audio controls preload="metadata">
<source src="/audio/post-slug.mp3" type="audio/mpeg" />
</audio>
WordPress
[audio src="audio/post-slug.mp3"]
배치
오디오 플레이어를 소개 글 이후 (첫 번째 H2 아래) 또는 기사 최상단에 "이 기사 듣기" 또는 "오디오 버전" 레이블과 함께 배치합니다.
내부 API (blog-write용)
blog-write에서 내부적으로 호출될 때:
입력:
text: 준비된 텍스트 (Claude가 이미 정리함)voice: 음성 이름 (기본값: Charon)voice2: 대화용 두 번째 음성 (선택 사항)model: flash 또는 prooutput_path: 파일을 저장할 위치
출력:
### 오디오 내레이션
- **경로:** /path/to/audio/post-slug.mp3
- **길이:** 3:42
- **음성:** Charon
- **임베드:** `<audio controls preload="metadata"><source src="audio/post-slug.mp3" type="audio/mpeg"></audio>`
정상 대체: GOOGLE_AI_API_KEY가 설정되지 않은 경우 즉시 반환하고 오류 없음.
작성 워크플로는 오디오 없이 계속됩니다. 오디오 생성이 불가능하더라도
blog-write를 절대 차단하지 마십시오.
오류 처리
| 오류 | 해결 방법 |
|---|---|
| GOOGLE_AI_API_KEY 설정 안 됨 | https://aistudio.google.com/apikey에서 키 획득 |
| FFmpeg를 찾을 수 없음 | 설치: sudo apt install ffmpeg. WAV 출력으로 대체. |
| 속도 제한 | 대기 후 재시도. https://aistudio.google.com/rate-limit에서 제한 확인 |
| 텍스트가 너무 김 (>32k 토큰) | 섹션으로 분할하여 별도 생성 |
| 알 수 없는 음성 이름 | /blog audio voices 실행하여 유효한 옵션 확인 |
| API 오류 | 키 유효성, 모델 사용 가능 여부 (미리보기 모델) 확인 |
| API 키 없음 (내부 호출) | 조용히 반환 -- 작성 워크플로는 계속됨 |
참고 문서
요청 시 로드 -- 시작 시 모두 로드하지 마십시오:
references/voices.md-- 전체 30개 음성 카탈로그, 콘텐츠 유형별 추천, 대화 페어링