Gemini TTS 생성

비디아 · v1 · 0회 사용 · 패키지 0개

Google Gemini TTS 목소리로 장면별 내레이션 음성과 발화 시간표를 만듭니다.

[이 모듈이 하는 일]
설계도의 장면별 발화(ttsText)로 Google Gemini TTS 내레이션 음성을 만들고, 발화마다 영상 전체 기준의 시작·끝 시각을 계산해 시간표(timeline)를 만든다.
기본 "TTS 생성" 모듈과 같은 시간표를 내보내므로 패키지에서 그 자리에 바꿔 넣어 쓸 수 있다. 자막·영상 길이·최종 렌더링이 모두 이 시간표를 기준으로 쓴다.

[필요한 값]
- 옵션 | select | gemini_tts_quality | Gemini 음성 품질 | options=표준,고품질,절약 default=표준 help="표준=Gemini 3.8 Flash TTS, 고품질=Gemini 2.5 Pro TTS, 절약=Gemini 3.8 Flash Lite TTS"
- 옵션 | select | gemini_voice | 주 화자 목소리 | options=Kore,Aoede,Leda,Zephyr,Charon,Puck,Fenrir,Orus default=Kore help="Kore·Aoede·Leda·Zephyr 는 여성, Charon·Puck·Fenrir·Orus 는 남성 목소리"
- 옵션 | longtext | gemini_tts_style | 말투 지시 | default="자연스럽고 또렷한 한국어 내레이션으로, 문장 끝을 흐리지 말고 읽어 주세요." help="감정·속도·분위기를 문장으로 적습니다"

[입력]
이전 단계 JSON(vidia.doc@1).
- blueprint.scenes[]: id, utterances[{id, speakerId, ttsText, pauseAfter}], durationSec, tailSec
- blueprint.speakers[]: {id, tempo} (voiceId 는 기본 목소리용이라 이 모듈은 쓰지 않는다)
- blueprint.models.tts: {tempo}
- blueprint.audio.sceneGapMs: 장면 사이 쉼(기본 200ms)
- assets: 이미 만든 음성("tts:<장면id>" 키)이 있으면 다시 만들지 않는다.
- timeline: 이전 시간표(재실행일 때)
- [설정]의 gemini_tts_quality · gemini_voice · gemini_tts_style

[할 일]
1. 준비
   - 모델: gemini_tts_quality 가 "고품질"이면 "gemini:gemini-2.5-pro-preview-tts", "절약"이면 "gemini:gemini-3.8-flash-lite-tts", 그 밖(표준·비어 있음)은 "gemini:gemini-3.8-flash-tts".
   - 화자 목소리: blueprint.speakers 순서대로 목록 [gemini_voice(없으면 Kore), Charon, Aoede, Puck, Leda, Fenrir] 에서 앞 화자가 쓰지 않은 첫 목소리를 고른다(첫 화자 = gemini_voice).
   - 화자 속도: 화자의 tempo, 없으면 models.tts.tempo, 그것도 없으면 1.0. 발화에 speakerId 가 없으면 첫 화자.
   - 말투 지시 instructions = gemini_tts_style(없으면 "자연스럽고 또렷한 한국어 내레이션으로 읽어 주세요.").
   - 장면 사이 쉼 gapSec = (audio.sceneGapMs 또는 200) ÷ 1000.
2. 장면마다 설계도 순서대로 음성을 만든다.
   - 발화가 없는 장면은 음성을 만들지 않는다.
   - 한 장면의 발화를 순서대로 훑어 "같은 화자가 이어지는 묶음(part)"으로 나눈다. 화자가 한 명이면 장면 전체가 part 하나다.
   - part 마다 tts_generate 를 한 번 부른다.
     model = 1에서 고른 모델, voice_id = 그 화자의 Gemini 목소리, instructions = 말투 지시, tempo = 그 화자의 속도,
     utterances = [{"id": 발화 id, "text": ttsText, "pause_after": pauseAfter(있을 때만)}],
     label = "<장면id> 내레이션"(part 가 2개 이상이면 "<장면id> 내레이션 2" 처럼 번호).
   - 결과의 asset_id·duration_sec·utterances[{id,start_sec,end_sec}] 를 기록한다.
   - 자산 키: 첫 part 는 "tts:<장면id>", 두 번째부터 "tts:<장면id>:p2", "tts:<장면id>:p3" …
   - assets 에 그 키가 이미 있고 timeline.narration 에 같은 키의 기록이 있으면 도구를 다시 부르지 않고 그 기록을 쓴다.
   - ttsText 에 숫자·영문·기호가 남아 있어도 고치지 않는다(대본 수정은 이 단계의 일이 아니다). 도구가 거절하면 "error" 에 발화 id 와 이유를 적는다.
3. 시간표를 계산한다(초 단위, 소수 셋째 자리까지 반올림).
   - 첫 장면 startSec = 0, 그 뒤 장면은 startSec = 앞 장면 startSec + 앞 장면 durationSec (장면은 빈틈 없이 이어진다).
   - 장면 안 내레이션 시작 여유 leadSec: 첫 장면은 0.1, 그 뒤 장면은 gapSec.
   - part 는 장면 안에서 앞 part 가 끝나는 곳에 이어 붙인다: part 시작(장면 기준) = leadSec + 앞 part 들의 duration_sec 합.
   - 발화 절대 시각 = 장면 startSec + part 시작 + 도구가 준 start_sec / end_sec.
   - 장면 길이 durationSec = max(마지막 part 끝(장면 기준) + tailSec, 설계도 durationSec). tailSec 은 장면 값, 없으면 0.5. 발화가 없는 장면은 설계도 durationSec(없으면 3).
   - totalSec = 마지막 장면 startSec + durationSec.
4. timeline 을 채운다.
   - timeline.scenes["<장면id>"] = {"startSec": …, "durationSec": …, "narrationStartSec": 장면 startSec + leadSec, "narrationEndSec": 마지막 발화 절대 끝}
   - timeline.utterances["<발화id>"] = {"sceneId": "<장면id>", "startSec": …, "endSec": …}
   - timeline.narration = [{"key": "tts:<장면id>", "sceneId": "<장면id>", "assetId": 음성 asset_id, "startSec": part 절대 시작, "durationSec": duration_sec}, …] (영상 순서)
   - timeline.totalSec = 전체 길이
   - timeline.order = 장면 id 배열(설계도 순서)

[출력]
다음 최상위 필드만 담은 JSON 객체 하나(적지 않은 최상위 필드는 입력값이 그대로 이어지므로 다시 적지 않는다. 바꾸는 필드는 값 전체를 적는다.)
- assets: 기존 값에 "tts:<장면id>"(와 "tts:<장면id>:p2" …) 키를 더한다.
- timeline: 위에서 만든 {utterances, scenes, narration, totalSec, order}
예: "assets":{"tts:s01":41,"tts:s02":42}, "timeline":{"utterances":{"s01_u1":{"sceneId":"s01","startSec":0.1,"endSec":2.84}},"scenes":{"s01":{"startSec":0,"durationSec":6.12,"narrationStartSec":0.1,"narrationEndSec":5.72}},"narration":[{"key":"tts:s01","sceneId":"s01","assetId":41,"startSec":0.1,"durationSec":5.62}],"totalSec":58.4,"order":["s01","s02"]}

[주의]
- tts_generate 는 글자 수에 비례해 비용이 드는 도구다(Gemini 모델 원가 기준, 회원이 자기 Google 키를 고르면 모델 요금 0P). 장면(또는 part)마다 한 번만 부르고, 이미 만든 음성은 다시 만들지 않는다.
- 요청이 몰려 한도에 걸려도 도구가 알아서 기다렸다 다시 보낸다. 같은 part 를 여러 번 부르지 않는다.
- 도구가 준 발화 시각을 그대로 쓴다. 시각을 추정해 지어내지 않는다.
- 설계도(blueprint)는 바꾸지 않는다. speakers 의 voiceId 도 바꾸지 않는다.
- 설명·마크다운 없이 JSON 객체 하나만 답한다.