---

이름: 책-비디오-파이프라인

설명: "샤오홍슈 도서 추천 영상 자동 생성 v3 - Seedance 2.0: 네이티브 오디오 + 자막 지원, 도서 선정부터 게시까지 완전 자동화"

라이선스: MIT

호출: "/book-video

---

# 샤오홍슈 도서 추천 영상 자동 파이프라인 생성 v3

book-video-pipeline

## 개요

Volcano Ark의 Seedance 2.0 API를 기반으로 Xiaohongshu용 도서 추천 영상을 생성하는 완전 자동화 프로세스입니다.

**v3 개선 사항 (공식 프롬프트 단어 가이드 기반):**

- **네이티브 오디오** — 프롬프트에 내레이션을 직접 지정하면 Seedance가 자동으로 음성을 생성합니다(더 이상 edge-tts를 사용하지 않음).

- **원본 자막** — 안내 메시지에 자막 내용을 지정하면 Seedance에서 영상과 동기화된 자막을 생성합니다.

- **표지 제목 카드** — 팬/줌 효과 및 무음 오디오 트랙을 포함하여 편집 호환성을 보장합니다.

- **체인 생성** — 각 세그먼트는 이전 세그먼트의 마지막 프레임을 시작 이미지로 사용하여 더욱 일관성 있는 시각적 흐름을 생성합니다.

- **크로스페이드 스플라이싱** — 비디오 크로스페이드와 오디오 크로스페이드를 결합하여 시청각 콘텐츠를 동기화합니다.

**핵심 프로세스:** 도서 선정 → 세부 정보/표지 → 시나리오 → 스토리보드 → 영상 제작(음성 및 자막 포함) → 편집 → 미리보기 → 게시

---

## 무음 실행 프로토콜

진행 여부를 확인하기 위해 문의하지 마십시오.

전체 결과를 한 번에 생성합니다.

데이터가 누락된 경우, 정의된 기본값을 사용합니다.

- "계속하시겠습니까?", "도움이 필요하신가요?", "확인해 주시겠습니까?"와 같은 말을 끊는 표현은 절대 사용하지 마세요.

---

## 환경 요구사항

필수 구성 요소 | 설치 |

|------|------|

| Volcano Ark API 키 | 환경 변수 `VOLCENGINE_API_KEY` |

| imageio-ffmpeg | `pip install imageio-ffmpeg` (ffmpeg에 포함되어 있음) |

| Docker (xiaohongshu-mcp) | `localhost:18060`에 배포해야 합니다 |

---

## 실행 프로세스

**트리거 방식: `/book-video` 또는 `/book-video 《책 제목》`**

1단계: 책 고르기

**시나리오 A - 사용자가 책 제목을 지정한 경우:** 해당 제목을 바로 사용하세요.

**시나리오 B - 도서 제목 미지정:** 검색 스크립트를 실행합니다(판매량이 적은 베스트셀러를 우선 순위로 표시).

세게 때리다

파이썬 "D:\skills\xiaohongshu-book-publisher\scripts\search_hot_books_v2.py"

```

"저분말 베스트셀러" 카테고리에서 "[출간된]"을 제외하고 1위를 자동으로 선택합니다.

**오류 처리:** 스크립트 시간 초과 → 캐시 → 웹 검색 → 기본값 (미움받을 용기)

---

2단계: 책 정보 및 표지 확보

**2.1 두반에서 상세 정보를 확인하세요**

```

WebFetch: https://search.douban.com/book/subject_search?search_text={책 제목}

발췌: 책 제목, 저자, 더우반 평점, 줄거리, 주요 인용구/핵심 관점, 표지 URL

```

**2.2 표지 다운로드 (영문 파일명!)**

세게 때리다

curl -o "D:\xiaohongshu_data\cover_{english_name}.jpg" -H "Referer: https://book.douban.com/" "표지 URL"

```

curl 명령이 실패하면 다음을 사용하세요.

세게 때리다

파이썬 "D:\skills\xiaohongshu-book-publisher\scripts\get_cover_playwright.py" "{책 제목}"

```

---

3단계: 도서 추천 스크립트 및 스토리보드 생성

책의 내용을 바탕으로 대화형 비디오 스크립트를 작성하세요.

**콜러지 공식 (시드댄스 2.0 공식 가이드 기준):**

각 스토리보드 프롬프트는 세 부분으로 구성됩니다.

1. **음성 명령** — 음성 해설이 포함된 비디오를 생성합니다. `{voice_type}`은 "내레이션 텍스트"를 의미합니다.

2. **시각적 묘사** — `주제 + 동작 + 환경 + 카메라 움직임 + 분위기`

3. **자막 지침** — 자막은 화면 하단에 나타납니다. 자막은 "내레이션 텍스트"이며 오디오 리듬과 완벽하게 동기화되어야 합니다.

**스크립트 템플릿 (6-7개 장면, 약 35초 분량):**

```마크다운

## 도서 추천 영상 스크립트

**도서 제목**: 《{도서 제목}》

**스타일:** 힐링 (따뜻한 골드 톤)

### 장면 1 - 오프닝 긴장감 조성 (5초)

**내레이션:** {시선을 사로잡는 첫 대사}

**시각적 묘사:** {영어 50-80단어: 피사체 + 동작 + 환경 + 카메라 구도 + 분위기}

### 장면 2 - 책이 나타난다 (5초)

내레이터: 이 책에 대한 간략한 소개

**시각 자료:** {영어로, 책과 관련된 장면}

### 스토리보드 3 - 작가/배경 (5초)

**내레이션:** {작가의 배경 또는 창작 이야기}

**장면**: {영어, 글쓰기 환경, 공부 등}

### 스토리보드 4 - 핵심 관점 1 (5초)

**내레이션:** {감동적인 관점 또는 기억에 남는 명언}

**시각적 요소:** {영어로, 관점에 맞는 시각적 은유}

### 장면 5 - 핵심 관점 2 (5초)

**내레이션:** {또 다른 설득력 있는 관점 또는 기억에 남는 인용구}

**시각적 요소:** {영어로, 관점에 맞는 시각적 은유}

### 스토리보드 6 - 개인적인 소감 (5초)

내레이터: {제 솔직한 감상과 책을 읽고 난 후 경험한 변화들}

**영상:** {영어, 감동적인 장면}

### 장면 7 - 행동 촉구 (5초)

내레이터: {행동 촉구}

**영상:** {영어, 감동적인 엔딩 장면}

```

**화면 설명 규칙:**

- **반드시 영어로 작성해야 하며,** 50~80단어 분량이어야 합니다.

- 다음 공식에 따라: 피사체 + 수행되는 동작 + 환경 + 조명/분위기 + 카메라 움직임

- **표지 이미지/책 제목 텍스트는 언급하지 마세요.** (텍스트는 자막에서 생성됩니다.)

- 가능한 한 구체적인 시나리오를 설명하고 추상적인 개념은 피하십시오.

**선택 가능한 사운드 유형:**

- 힐링: '부드럽고 차분한 여성 목소리'

- 서스펜스/미스터리: '깊고 낮은 남성 목소리'

- 산뜻하고 깔끔한 스타일: 가볍고 활기찬 여성 보컬.

---

4단계: 파이프라인을 사용하여 비디오를 생성합니다.

**4.1 스토리보드 JSON 저장**

JSON

[

{"scene_id": 1, "prompt": "영어 시각적 설명...", "narration": "중국어 내레이션"},

{"scene_id": 2, "prompt": "영어 시각적 설명...", "narration": "중국어 내레이션"},

...

]

```

`D:\xiaohongshu_data\storyboard_{english_name}.json`에 저장하세요.

**4.2 전체 파이프라인 v3 호출**

파이썬

sys, json을 가져옵니다.

sys.path.insert(0, r"D:\skills\book-video-pipeline\scripts")

Seedance_client에서 SeedanceClient를 가져옵니다.

클라이언트 = SeedanceClient(api_key="YOUR_API_KEY")

with open(r"D:\xiaohongshu_data\storyboard_xxx.json", encoding="utf-8") as f:

스토리보드 = json.load(f)

결과 = 클라이언트.generate_full_video(

스토리보드 = 스토리보드,

cover_path=r"D:\xiaohongshu_data\cover_xxx.jpg",

book_title="도서 제목",

output_dir=r"D:\xiaohongshu_data",

voice_type="부드럽고 차분한 여성 목소리",

with_subtitles=True,

)

print(f"비디오: {result['video_path']} ({result['size_kb']}KB, ~{result['duration']}초, 오디오: {result['has_audio']})")

```

**파이프라인 v3이 자동으로 실행됩니다:**

1. 표지 → 타이틀 카드 (3초간 패닝/줌 + 음소거)

2. 비디오 클립을 순차적으로 생성합니다(각 클립에는 원본 오디오와 자막이 포함됩니다).

3. 크로스페이드 스티칭(비디오 크로스페이드 + 오디오 크로스페이드)

4. 최종 영상을 출력합니다.

**API 키 구성:**

세게 때리다

VOLCENGINE_API_KEY=ark-xxx로 설정

```

---

### 5단계: 미리보기

`D:\preview_video_{name}_{date}.html` 파일에 다음 내용이 포함된 HTML 미리보기 페이지를 생성합니다.

- 비디오 플레이어

- 책 제목, 저자, 평점

- 내레이션 텍스트 버전

- 샤오홍슈의 핑크 테마 스타일

세게 때리다

시작 "" "D:\preview_video_xxx.html"

```

**사용자에게 확인해 주십시오.** 불만족스러우신 경우, 다음을 수행해 주십시오.

- 스토리보드 프롬프트 조정 → 재생성

- 사운드 유형 변경 → 재생성

- 시각적 설명 조정 → 프롬프트만 변경

---

6단계: 샤오홍슈에 게시글 올리기

**6.1 로그인 상태 확인** → MCP `check_login_status`

**6.2 비디오 메모 텍스트 생성** (비디오 스크립트가 아닙니다!)

- 제목은 20자 이하, 1인칭 시점 (감정 포함)

본문 200~300단어, 이모티콘 20개 이상

- #이 포함된 태그 10~15개

**MCP 6.3 버전 출시**

파이썬

MCP_URL = 'http://localhost:18060'

# 초기화 → publish_content(title, content, video, tags)

# 컨테이너 경로를 사용한 비디오 경로: /app/data/xxx.mp4

```

**6.4 레코드가 게시되었습니다** → `published_books.json` 파일에 `type`: `video`를 추가하세요

---

## 출력 형식

```마크다운

## 도서 추천 영상이 성공적으로 생성되었습니다

**도서 제목**: 《{도서 제목}》

**작가**: {작가} | **두반**: {평점}

### 비디오 정보

- 재생 시간: 약 {N}초 (3초 타이틀 카드 + {M}개 장면 x 5초)

- 화면 비율: 9:16 (세로)

- 해상도: 720p

파일 크기: {N} MB

- 오디오: 예/아니요

- 자막: 내장/없음

- 경로: `D:\xiaohongshu_data\{name}_final.mp4`

### 정보 공개

- 제목: {title}

- 태그: {태그}

- 상태: {성공/실패}

```

---

## 주요 규칙

1. **네이티브 오디오 우선** — Seedance 2.0은 오디오 생성을 기본적으로 지원합니다. 프롬프트에서 내레이션을 지정하기만 하면 됩니다.

2. **원본 자막** — 안내 메시지에 자막 내용을 지정하면 Seedance에서 자동으로 동기화된 자막을 생성합니다.

3. **마지막 프레임 연속** — 각 세그먼트는 이전 세그먼트의 마지막 프레임을 시작 이미지로 사용하여 더욱 일관성 있는 시각적 흐름을 제공합니다.

4. **스토리보드 장면은 영어로 제공되어야 합니다.** - Seedance는 더 나은 시각적 효과를 위해 영어 장면을 사용합니다.

5. **통일된 음향 유형** — 영화 전체에 동일한 음향 유형이 사용됩니다.

6. **비디오 화면 비율 9:16** — 샤오홍슈 세로 화면

7. **게시 전 사용자 확인이 필요합니다.** — 게시하기 전에 미리보기가 완료될 때까지 기다리세요.

8. **이미지 파일 이름은 반드시 영문이어야 합니다.** 중국어 문자를 사용하면 업로드 시간이 초과됩니다.

9. **비디오 스크립트 ≠ 텍스트 및 이미지 메모** — 스크립트는 기사 형식이 아닌 대화체로 작성됩니다.

10. **오디오 보존 전환** — 크로스페이드 비디오 전환 + 크로스페이드 오디오 전환

## 큐어 참조 (시드런스 2.0 가이드)

### 오디오 명령 템플릿

```

음성 해설이 포함된 비디오를 생성합니다. `{voice_type}` 옵션은 "{narration content}"를 의미합니다.

```

### 자막 제작 지침 템플릿

```

화면 하단에 "{자막 내용}"이라는 자막이 나타납니다. 자막은 오디오 리듬과 완벽하게 동기화되어야 합니다.

```

### 완전한 장면 프롬프트 예시

```

부드럽고 차분한 여성 목소리로 "우리는 왜 항상 다른 사람들의 기대에 부응하려고 애쓰는 걸까요?"라는 내레이션이 포함된 영상을 제작하세요. 안개가 자욱한 숲길의 갈림길에 한 사람이 서 있고, 키 큰 나무 사이로 햇살이 비치며 따뜻한 황금빛 조명이 연출됩니다. 카메라가 천천히 다가오며 얕은 심도를 사용합니다. 화면 하단에 "우리는 왜 항상 다른 사람들의 기대에 부응하려고 애쓰는 걸까요?"라는 자막이 나타나야 합니다. 자막은 음성과 완벽하게 동기화되어야 합니다.

```

## 파일 참조

| 파일 | 용도 |

|------|------|

| `D:\skills\book-video-pipeline\scripts\seedance_client.py` | Seedance API + 네이티브 오디오/자막 + 연결 (v3) |

| `D:\skills\xiaohongshu-book-publisher\scripts\search_hot_books_v2.py` | 인기 도서 검색 |

| `D:\skills\xiaohongshu-book-publisher\scripts\published_books.json` | 출판된 기록 |

| `D:\skills\xiaohongshu-book-publisher\scripts\get_cover_playwright.py` | 표지 이미지 검색(백업) |

| `D:\xiaohongshu_data\` | 비디오 및 표지 출력 디렉토리 |

## API 구성

| 매개변수 | 값 |

|------|-----|

| 비디오 모델 | `doubao-seedance-2-0-fast-260128` |

| 음성 유형 | 부드럽고 차분한 여성 음성 (기본값) |

| 비율 | `9:16` |

| 세그먼트 길이 | 5초 |

| 타이틀 카드 | 3초간 패닝/줌 + 음소거 |

| 크로스페이드 | 0.5초 전환 (영상 + 오디오) |