# 대본 작성·장면 배치·AI 음성·JSON 복사와 붙여넣기

> 기준일: 2026-09-19
> 대상: 영상 대본과 내레이션을 만드는 회원, AI 상담 답변 작성자, selvi.web 도움말 담당자
> 검증 범위: 현재 UI와 대본·음성·JSON 처리 소스를 대조했다. 유료 공급자 요청, 실제 발음·억양·재생 품질은 이번 문서 작업에서 시험하지 않았다.

## KB-SCRIPT-001 · 대본·음성 단계의 역할

프로젝트의 **2단계 대본·음성**은 문장과 읽는 목소리를 연결하는 곳이다. 각 문장은 문장 내용, 자막 시작·종료, 음성 상태, 배치된 원본 장면을 가진다. 문장 목록을 기준으로 음성과 장면이 이어지므로 대본을 수정했다면 음성과 렌더 상태도 다시 확인해야 한다.

사용 방식은 조합할 수 있다.

- AI 대본을 만들고 Fish Audio 또는 Gemini TTS로 읽는다.
- 직접 작성한 대본을 AI 목소리로 읽는다.
- 직접 작성하거나 AI로 만든 대본에 전체를 읽은 내 음성 파일을 연결한다.

AI 대본에는 원본 영상과 Gemini 계열 인증이 필요하다. AI 목소리에는 선택한 엔진의 인증·목소리 설정이 필요하다. 파일 기반 음성은 TTS 합성을 호출하지 않으며, 파일 준비와 자막 시간 조절을 사용자가 담당한다.

## KB-SCRIPT-002 · AI 대본 만들기 순서

1. **영상 준비**에서 원본과 사용할 구간, 상품명을 확인한다.
2. **대본·음성** 오른쪽 **대본 생성**에서 **대본 모드**와 **대본 언어**를 선택한다.
3. 필요한 경우 **시작 후킹**, **구매 안내 문구(CTA)**를 설정한다.
4. **추가 지시 → 작성 방향(선택)**에 대상 시청자, 확인된 장점, 원하는 말투를 1,000자 이내로 적는다.
5. **대본 만들기** 또는 **AI로 대본 만들기**를 누른다. 이미 문장이 있으면 **새 대본 만들기**로 표시된다.
6. 생성 결과를 읽고 사실·표현·상품명·문장 순서를 검토한다.
7. 수정한 뒤 음성을 만들고 들어본다.

Gemini API Key와 Google Vertex Key를 모두 등록해 공용 선택을 사용하는 경우에는 대본 생성 영역에서 이번 작업의 인증 경로를 선택할 수 있다. 공급자에 요청하는 내용과 비용은 연결한 공급자 계정의 조건을 따른다.

생성에 성공하면 기존 본문 대본을 새 결과로 바꾼다. 다만 후킹·CTA로 고정한 문장은 별도로 유지하는 경로가 있으므로 모든 문장이 무조건 초기화된다고 설명하지 않는다. 새로운 대본을 여러 번 시도하기 전에 **JSON 복사**로 현재 구성을 남겨둘 수 있다.

## KB-SCRIPT-003 · AI는 무엇을 보고 대본을 쓰나요?

현재 구현은 원본의 사용 구간에서 장면 프레임을 추출하고, 원본 음성·화면 자막의 텍스트 추출도 시도한다. 이 결과와 상품명·작성 방향·모드·언어를 활용해 대본을 생성한다. 원본 텍스트 추출만 실패하면 장면 시트로 대본 생성을 이어갈 수 있다. 따라서 원본 대사나 작은 화면 글자를 항상 정확히 이해했다고 보장하지 않는다.

생성 결과는 길이·문장 등 규칙을 검사하며 필요하면 보정 요청을 한다. 보정 시도가 있어도 유효한 결과를 얻지 못하면 오류가 표시될 수 있다. 실패를 그대로 성공으로 설명하거나 임의의 대본이 저장됐다고 안내하지 않는다.

자동 배치가 가능한 장면 정보도 결과에 연결된다. 문장 카드의 `SOURCE 01` 같은 표시는 어떤 원본의 어느 시간대를 연결했는지 보여준다. 정확한 연출·제품 일치 여부는 사용자가 확인한다.

## KB-SCRIPT-004 · 대본 모드 7종

현재 **대본 모드**는 썰형 계열의 일곱 가지 전개다. 과거 문서에 다른 모드가 있더라도 현재 드롭다운을 기준으로 답한다.

- **썰형**: 일상에서 물건을 발견한 일을 친구에게 들려주는 전개.
- **고백형**: 작은 고민을 먼저 털어놓고 화면의 쓰임으로 연결하는 전개.
- **타인반응형**: 주변인의 한마디를 계기로 시작하는 전개.
- **반전형**: 처음의 의심과 화면에서 확인하는 결과를 대비하는 전개.
- **질문훅형**: 공감할 질문으로 시작하는 전개.
- **비교형**: 기존 방식의 번거로움과 화면의 차이를 나란히 보여주는 전개.
- **시간압축형**: 짧은 시간 안의 변화를 전달하는 전개.

모드는 문장 전개 방향이다. 사용자가 실제로 하지 않은 체험, 주변인이 하지 않은 말, 검증하지 않은 성능을 사실로 주장할 수 있는 허가가 아니다. AI 초안에서 그런 표현이 나오면 확인 가능한 내용으로 고친다.

## KB-SCRIPT-005 · 언어와 길이

**대본 언어**는 한국어·영어·일본어를 지원한다. 대본 언어를 바꾸는 설정이며 앱의 메뉴 언어를 바꾸는 기능은 아니다. 영어·일본어는 해당 언어를 읽을 수 있는 목소리를 선택하고 발음을 직접 확인한다. 일본어 자막은 가나·한자 표시가 가능한 글꼴도 확인한다.

AI 생성 화면의 기준은 **후킹·CTA 포함 3~7문장**, **생성 문장당 최대 5초 분량**, **완성본 최대 45초**다. 원본이 짧으면 길이 예산도 줄인다. 원본이 여러 개면 준비 순서대로 모두 활용하고 반복을 줄이도록 생성한다. 원본 수에 따라 안내하는 최소 문장 수도 달라질 수 있다.

이는 AI 생성의 길이 예산과 안내다. 사람이 입력한 모든 문장이 자동으로 정확히 5초가 된다는 의미가 아니다. 직접 수정한 구매 안내 문구는 5초를 넘길 수 있다. 실제 말하기 시간은 목소리·속도·문장에 따라 달라지므로 합성 후 측정된 시간을 확인해야 한다.

## KB-SCRIPT-006 · 직접 쓰기와 후킹·CTA 고정

1. **직접 쓰기** 또는 **문장 추가**를 눌러 문장을 만든다.
2. 문장 입력칸에 읽을 내용을 적는다.
3. 문장 옵션을 열어 **시작**, **종료**, **위로**, **아래로**, **삭제**를 조절한다.
4. 필요한 문장에 **시작 후킹 지정** 또는 **마지막 CTA 지정**을 적용한다.
5. 문장 순서와 시간을 검토한 뒤 음성을 생성한다.

후킹은 첫 문장, CTA는 마지막 문장으로 고정한다. 고정 문장에는 표시가 붙고 일반 문장 이동과 다르게 처리된다. 고정을 해제하려면 같은 옵션의 해제 동작을 사용한다.

**대본 비우기**는 문장과 만든 음성을 함께 버리는 동작이며 확인 창을 거친다. **음성 전부 제거**는 대본 문장을 유지하면서 음성을 제거하는 동작이다. 두 버튼의 결과를 구분해 안내한다.

## KB-SCRIPT-007 · 장면 자동 배치와 음성 길이

AI 대본을 생성하면 문장에 원본 장면을 배치한다. 음성을 만든 뒤에는 실제 음성 길이를 반영해 자동 장면의 배치를 다시 맞춘다. 사용자가 수동으로 정한 장면은 자동 배치에서 유지하는 경로가 있다.

**비디오** 단계에서 문장을 선택하여 연결된 원본·구간을 확인하고 필요한 장면 편집을 수행한다. 대본 카드의 장면 표시만으로 모든 컷이 의도대로 편집됐다고 판단하지 않는다. 대본을 크게 바꾸거나 다른 원본을 연결했으면 장면도 검토한다.

자동 배치는 사용 구간 안에서 문장과 영상을 이어주는 보조 기능이다. AI가 모든 문장을 의미상 완벽한 장면에 맞춘다고 보장하지 않는다. 자세한 비디오 조작은 편집 문서를 따른다.

## KB-SCRIPT-008 · AI 목소리 생성

1. **대본·음성 → 음성 방식 → AI 목소리**를 선택한다.
2. **음성 엔진**에서 **Fish Audio** 또는 **Gemini TTS**를 고른다.
3. 엔진에 맞는 목소리를 선택한다. 목소리 목록이 비어 있으면 연결 상태와 목록 불러오기를 확인한다.
4. **말하기 속도**, **음높이**, **합성 방식**을 설정한다.
5. **미리듣기**로 목소리를 확인한다.
6. **음성 전부 만들기**를 누르고 문장별 음성 상태를 확인한다.
7. 완성한 문장의 **들어보기**로 발음·경계·문장 누락을 확인한다.

현재 속도 범위는 0.90~1.25배, 음높이는 -3~+3반음이다. 속도·음높이를 바꾸면 기존 음성을 그대로 최신으로 쓰지 않고 다시 생성해야 한다. Gemini TTS의 미설정 기본 모델은 `gemini-3.1-flash-tts-preview`, 기본 목소리는 `Kore`다. 사용자가 선택·저장한 값이 있으면 해당 설정을 따른다.

미리듣기도 공급자 요청을 사용할 수 있다. 남은 크레딧·할당량·모델 권한은 셀비 로그인 기간과 별개다. 키 등록이나 연결 테스트 성공만으로 모든 목소리와 모델의 합성을 보장하지 않는다.

## KB-SCRIPT-009 · 통합 합성과 문장별 합성

기본 **통합 합성(자연스러운 억양)**은 전체 대본 또는 필요한 연속 문장들을 묶어 요청한다. 긴 텍스트는 엔진별 한도에 맞춰 여러 요청으로 나눌 수 있으므로 항상 단 한 번만 호출한다고 설명하지 않는다.

통합 합성 결과는 전체 음성 파일을 유지하고 각 문장의 시작 위치와 길이를 기록한다. 문장별 듣기는 그 파일의 해당 구간을 재생한다. 현재 구현을 “음성 파일을 문장마다 물리적으로 잘라 저장한다”라고 설명하면 부정확하다.

문장 경계는 가능한 경우 음성 인식 결과와 문장을 정렬하고 쉼을 참고한다. 음성 인식이 없거나 결과가 맞지 않으면 감지된 무음 또는 글자 수 비례로 시간을 나누는 대체 처리를 사용한다. 이 때문에 자막·문장별 들어보기의 시작이 완벽하지 않을 수 있으며 실제 듣고 조절해야 한다.

**문장별 합성(정확한 경계)**은 문장마다 합성하는 방식이다. 문장 단위 제어가 명확하지만 이어지는 억양은 통합 합성과 다를 수 있다. “정확한 경계”라는 메뉴 이름이 어떤 문장이든 발음·내용까지 무오류라는 뜻은 아니다.

## KB-SCRIPT-010 · 수정과 재생성, 부분 실패

문장을 수정하거나 엔진·목소리 설정이 달라지면 영향을 받는 음성이 **업데이트 필요** 상태가 될 수 있다. **다시 생성** 또는 **음성 전부 만들기**를 누르면 현재 설정과 맞고 사용할 수 있는 음성은 재사용하고, 음성이 없거나 오래됐거나 실패한 문장을 처리한다. 버튼 이름에 “전부”가 있어도 모든 문장을 매번 새 요청하는 것은 아니다.

통합 합성에서 여러 문장이 연속으로 필요하면 묶음으로 처리하고, 하나만 필요하면 문장 단위 경로를 쓸 수 있다. 일부가 실패하면 완료한 음성은 유지하고 실패 문장의 안내를 보여준다. 오류에 나온 인증·한도·모델·연결 문제를 해결한 뒤 재시도한다.

모든 음성을 버리고 처음부터 다시 만들 의도가 있을 때만 **음성 전부 버리고 다시 만들기**를 사용한다. 일반적인 오탈자 수정에 이 동작을 우선 권하지 않는다. 이미 만들어 둔 렌더는 대본·음성 변경 이후의 결과가 아니므로 새 렌더 상태도 확인한다.

## KB-SCRIPT-011 · 내 음성 파일 사용

1. **음성 방식 → 내 음성 파일**을 선택한다.
2. **WAV·MP3 가져오기**로 전체 대본을 읽은 파일 한 개를 선택한다.
3. 각 문장의 자막 시작·종료를 실제 읽는 위치에 맞춘다.
4. 미리보기와 렌더 결과에서 음성과 자막의 일치를 확인한다.

이 모드는 문장별 AI 음성을 합성하는 모드와 다르다. 전에 만든 AI 문장 음성이 프로젝트에 남아 있더라도 로컬 음성 모드에서는 해당 문장별 AI 들어보기를 사용하지 않도록 표시한다. 업로드한 파일의 내용을 자동으로 대본으로 완벽하게 변환한다고 안내하지 않는다.

## KB-SCRIPT-012 · JSON 복사와 붙여넣기

**목적:** 셀비 대본·음성 설정을 클립보드 JSON으로 보관하거나 같은 형식으로 되돌린다. 프로젝트 전체 백업이나 미디어 패키지 전송은 아니다.

1. 복사할 프로젝트의 **대본·음성**을 연다.
2. **JSON 복사**를 누른다. 현재 대본을 저장한 뒤 JSON 텍스트를 클립보드에 복사한다.
3. 필요하면 개인 메모나 파일에 그 텍스트를 보관한다. 문장·상품명 등 사용자 작성 내용이 포함되므로 공유 대상을 확인한다.
4. 복원할 때 저장한 셀비 JSON 전체를 클립보드에 복사한다.
5. 대상 프로젝트에서 **JSON 붙여넣기**를 실행한다.
6. 가져온 문장 수와 유지되지 못한 음성·장면 안내를 확인한다.

지원 문서 표식은 `format: "selvi-script"`, 현재 `version: 1`이다. 문장, 역할, 시간, 장면, 음성 참조, 엔진·합성 방식·속도·음높이·대본 모드·언어 등을 포함한다. 유효한 문장이 필요하며 최대 크기는 8 MiB다. 알 수 없는 필드나 다른 버전·형식은 거절한다. 일반적인 AI 채팅의 자유 형식 JSON을 그대로 붙여넣을 수 있는 기능으로 설명하지 않는다. 원형은 셀비의 **JSON 복사**로 확보하는 것이 안전하다.

붙여넣기는 대상 프로젝트의 대본과 관련 음성 설정을 교체한다. 음성 데이터 자체가 JSON 안에 들어 있는 것은 아니다. 같은 프로젝트 안에 참조 파일이 있고 해시가 일치하는 등 검사를 통과해야 기존 음성을 유지한다. 파일이 없거나 내용이 바뀌면 음성을 다시 만들어야 한다. 현재 프로젝트에 없는 원본 장면이나 사용 구간에 맞지 않는 장면은 가져오기에서 제외될 수 있다.

다른 컴퓨터나 프로젝트로 JSON만 옮긴 뒤 모든 음성과 영상이 복원된다고 안내하지 않는다. JSON은 대본 자료 교환이지 원본·완성본·모든 설정을 포함한 전체 백업이 아니다.

## KB-SCRIPT-013 · 자주 묻는 질문

**Gemini 키만으로 대본과 음성 모두 만들 수 있나요?**

Gemini 계열 인증으로 대본과 Gemini TTS를 사용하는 경로가 있다. 해당 계정에서 모델을 이용할 수 있어야 하며 할당량·결제는 별도 확인한다.

**대본 한 글자를 고쳤는데 모든 음성을 다시 만드나요?**

일반 생성은 사용할 수 있는 최신 음성을 재사용하고 필요한 부분을 처리한다. 엔진·목소리처럼 전체 음성의 조건을 바꾸면 영향 범위가 커질 수 있다.

**통합 합성인데 문장마다 잘린 것처럼 들려요.**

문장별 들어보기는 전체 파일 안의 특정 구간을 재생한다. 경계 추정이 맞는지 전체 흐름과 함께 확인한다. 현재 구현은 통합 원음을 문장별 파일로 잘라 보관하는 방식이 아니다.

**내 음성 파일을 올리면 자막이 저절로 완벽하게 맞나요?**

아니다. 파일 한 개를 연결하는 방식이며 문장별 자막 시간을 확인·조절해야 한다.

**JSON을 붙였는데 음성이 없어졌어요.**

JSON은 파일을 포함하지 않는다. 해당 프로젝트에서 기존 파일·내용 검사를 통과하지 못한 음성은 유지하지 않고 재생성이 필요한 상태로 둔다.

## 구현 근거

- `frontend/src/main.ts`: `renderScript`, `scriptPatternSelect`, `scriptLanguageSelect`, `scriptBriefField`, `scriptPhraseField`, `scriptLengthHelp`, `scriptLead`, `voiceDeliveryControls`, `stageVoiceSelect` 및 JSON 복사·붙여넣기 동작 처리.
- `frontend/src/state.ts`: `SCRIPT_PATTERN_OPTIONS`, `SCRIPT_LANGUAGE_OPTIONS`, `STAGES`.
- `app.go`: `GenerateScript`, `generateScriptCore`, `scriptDraft.place`, `GenerateFishAudio`, `GenerateGeminiAudio`, `generateNarrationCoreWithProgress`, `geminiTTSCacheKey`.
- `app_narration.go`: `generateNarrationWhole`, `generateNarrationSentence`, `synthesizeWholeRun`, `wholeChunkBounds`, `pendingRuns`.
- `app_scriptjson.go`: `ScriptExchange`, `ExportScriptJSON`, `ImportScriptJSON`, `decodeScriptExchange`, `applyScriptExchange`.
- `internal/settings/settings.go`: `DefaultGeminiTTSModel`, `DefaultGeminiTTSVoice`, `EffectiveGeminiTTSModel`, `EffectiveGeminiTTSVoice`.

해당 파일의 현재 소스를 읽어 오래된 주석과 실제 처리가 다른 통합 음성 저장 방식을 정정했다. 그래프에 기록된 누락이 없다는 사실만으로 공급자 출력·실제 발음·모든 경계 품질을 확정하지 않는다. 관련 문서: [처음 시작하기](01-product-and-start.md), [아이템과 원본](02-discovery-and-sources.md).