# 렌더링·썸네일·캐러셀 카드뉴스

> 기준일: 2026-09-19
> 대상: 완성 영상을 저장하거나 대표 이미지·카드뉴스를 만드는 회원, AI 상담 및 도움말 작성자

## KB-OUT-001 · 세 가지 결과물 구분

- **영상 렌더링:** 소스 영상, 내레이션, 자막, 디자인, 레이어를 합쳐 MP4 완성본을 만듭니다.
- **썸네일:** 영상에 사용할 세로 대표 이미지를 만듭니다. 영상 앞장 삽입과 지원 채널의 별도 이미지 업로드는 각각 설정합니다.
- **캐러셀 카드뉴스:** 별도 사이드 메뉴에서 정사각형 카드 이미지 여러 장을 만듭니다. 영상 프로젝트의 여섯 제작 단계와 독립된 작업입니다.

캐러셀 ZIP을 영상 완성본이나 UUP 영상 전달 패키지로 설명하지 않습니다. 영상의 디자인 조정은 [비디오와 디자인](04-video-and-design.md), 게시 전달은 [UUP 안내](06-publishing-and-uup.md)를 참고하세요.

## KB-OUT-002 · 영상 렌더링 시작

**목적:** 현재 프로젝트를 검증된 MP4 파일로 저장합니다.

**선행조건:** 소스 파일이 연결되어 있고 현재 대본에 맞는 음성이 준비되어 있어야 합니다. 저장 폴더와 영상 처리 도구가 정상이어야 합니다.

1. 제작 화면에서 **렌더링**을 엽니다.
2. 미리보기와 제목·자막을 확인합니다.
3. 출력 위치에서 **폴더 선택**으로 완성본 폴더를 정합니다.
4. 자막 파일이 필요하면 **자막 파일(SRT)도 함께 저장**을 켭니다. 기본은 꺼져 있습니다.
5. **렌더 전 확인**의 영상·대본·음성·저장 위치 항목을 확인합니다. **조치 필요**가 있다면 제공된 이동 버튼으로 해당 단계에서 해결합니다.
6. **영상 렌더링**을 누릅니다. 이전 출력이 있으면 **다시 렌더링**, 변경 사항이 있으면 **바뀐 설정으로 다시 렌더링**으로 표시될 수 있습니다.
7. 위쪽 **작업**에서 진행 상태를 확인합니다. 멈추려면 **렌더링 취소**를 누릅니다.
8. 완료 후 **앱에서 재생** 또는 **기본 플레이어**로 실제 완성본을 확인합니다. 파일은 **폴더 열기**로 찾습니다.

출력은 세로 **1080×1920, 9:16, H.264 영상·AAC 음성의 MP4**입니다. 새 렌더는 구분되는 파일 이름으로 저장합니다. 기존 완성본 파일을 사용자가 직접 덮어쓰는 절차를 기본 사용법으로 안내하지 않습니다.

## KB-OUT-003 · 렌더 검증과 최신 완성본

렌더링은 준비 → 인코딩 → 출력 검증 → 내보내기 순서로 진행됩니다. 저장 위치의 존재·쓰기 가능 여부를 실행 전에 검사하고, 인코딩 결과의 미디어 정보·예상 길이 등을 확인합니다. 외부 완성본 폴더로 복사한 파일도 무결성을 확인합니다. 이러한 검사를 마쳐야 **검증된 완성본**이 됩니다.

이 검증은 파일과 출력 조건에 관한 검사입니다. 대본의 사실성, 상품 외형, 모든 문구의 가독성, 음악 이용 권리 또는 플랫폼 게시 성공을 자동으로 보증하는 검사는 아닙니다. 실제 MP4를 재생해 화면·음성·광고 표시를 확인하세요.

렌더 시작 후 설정을 바꾸면 진행 중인 결과에는 새 변경이 반영되지 않습니다. 완성본이 **기존 렌더 · 업데이트 필요**, **오래됨**으로 표시되면 다시 렌더링해야 최신 설정을 UUP에 전달할 수 있습니다. 전달 대상은 최신 검증 렌더이며, 오래된 결과를 임의로 최신 결과처럼 전달하지 않습니다.

음성의 실제 길이와 장면의 길이를 비교해 출력 길이를 조정합니다. 화면에 표시된 길이 조정 안내를 읽고, 느려진 장면이나 마지막 화면 유지가 의도에 맞는지 확인하세요. 선택한 썸네일 앞장이 켜져 있으면 최종 출력 길이에 그 시간이 더해집니다.

## KB-OUT-004 · SRT 자막과 렌더 문제 해결

**SRT:** 완성 MP4와 같은 기본 이름의 UTF-8 파일로 함께 저장합니다. 현재 표시 구절과 자막 시간을 사용합니다. 썸네일 앞장이 있으면 그 길이를 반영해 자막 시간을 뒤로 옮깁니다. 다른 편집기에서 수정할 때 사용할 수 있으며, MP4 위에 그려진 자막 자체를 SRT 파일 삭제만으로 없앨 수는 없습니다.

**시작 버튼이 비활성화됨:** **렌더 전 확인**의 안내를 순서대로 해결합니다. 음성을 바꿨다면 현재 대본의 음성이 준비됐는지 확인하고, 영상 처리 도구 문제는 **설정 → 환경 검사**에서 확인합니다.

**저장 위치 오류:** 폴더가 실제로 존재하는지, 외장 드라이브가 연결되어 있는지, 쓰기 권한과 여유 공간이 있는지 확인한 뒤 폴더를 다시 선택합니다.

**썸네일 손상·변경 오류:** 선택한 썸네일 파일을 다시 만들거나 정상 이미지로 선택을 바꾸고 렌더합니다.

**렌더 실패:** 오류 문구를 확인한 후 원본·음성·출력 위치를 점검하고 **다시 렌더링**을 사용합니다. 반복되면 **진단 내보내기**로 자료를 만들어 [문제 해결](08-troubleshooting.md)에 따라 접수합니다. 완료 전 임시 결과를 완성본으로 사용하지 않습니다.

**앱 재생만 실패:** 파일이 검증 완료인지 먼저 확인하고 **기본 플레이어**로도 재생해 봅니다. 한 플레이어의 실패만으로 렌더 파일 손상을 단정하지 말고 발생 환경과 오류를 함께 전달합니다.

## KB-OUT-005 · 썸네일 생성

**목적:** 상품과 영상의 인상을 담은 세로 대표 이미지를 생성합니다.

**선행조건:** 소스 영상이 한 개 이상 필요합니다. **설정 → API 키**에서 Gemini API Key 또는 Google Vertex Key(서비스 계정 JSON)를 저장하고 사용 가능한 공급자 상태를 확인합니다. 이미지 생성 비용이 발생합니다.

1. 제작 화면의 **썸네일**을 엽니다.
2. **썸네일 문구 (선택)**에 짧은 문구를 입력하거나 **AI 문구 생성**으로 후보를 만듭니다. 후보를 누르면 문구 칸에 적용됩니다.
3. **추가 지시 (선택)**에 배경·분위기·연출을 적습니다.
4. 필요하면 **참조 이미지 첨부**를 사용합니다.
5. **썸네일 만들기** 또는 **새 썸네일 만들기**를 누릅니다.
6. 생성 후 글자·상품 형태·배치를 확인합니다. 잘못된 문구는 입력만 바꿔서는 이미지에 반영되지 않으므로 다시 생성합니다.

기존 썸네일·참조 이미지·비디오의 이미지 레이어와 첫 영상의 사용 구간 프레임 등을 참조해 최대 세 장의 참조를 구성하며 실제 원본 프레임을 포함합니다. 이미지와 문구는 공급자에 전송되어 생성에 사용됩니다. 상품 외형과 글자가 완벽히 보존된다고 보장하지 않습니다.

만든 이미지는 **만든 썸네일** 목록에 쌓입니다. **이 이미지 사용**으로 현재 선택을 바꾸고, 각 이미지의 내려받기·삭제 버튼을 사용할 수 있습니다. 새로 만들었다고 기존 이미지가 모두 사라지는 방식은 아닙니다. 선택한 결과는 **내려받기** 또는 **이미지 열기**로 별도 확인합니다.

현재 썸네일 생성 화면은 생성 중 취소할 수 없다고 안내합니다. 완료까지 기다리고 실패 메시지가 나오면 인증·네트워크·공급자 상태를 확인한 뒤 재시도합니다.

## KB-OUT-006 · 썸네일 앞장과 게시용 커버

**영상 앞장:** 썸네일을 선택하고 **영상 맨 앞에 표시**를 켭니다. **앞장 길이**는 기본 0.1초이며 1초까지 조절할 수 있습니다. 최종 렌더한 MP4의 앞에 들어가고, 디자인 미리보기는 본편부터 시작하므로 해당 미리보기에 보이지 않을 수 있습니다.

**별도 게시용 썸네일:** **배포 준비·UUP 전달 → 게시용 썸네일**에서 채널·영상 조건과 UUP 연결의 지원 여부에 따라 **만든 썸네일 함께 업로드**가 표시됩니다. 현재 계약상 Instagram과 쇼츠 조건이 아닌 YouTube 영상이 대상입니다. 세로 또는 정사각형이며 180초 이하인 YouTube 영상은 별도 커버 업로드 지원에서 제외됩니다.

따라서 보통의 Selvi 세로 쇼츠에는 “YouTube 대표 이미지가 자동으로 적용된다”고 약속하지 않습니다. 영상 앞장 삽입만으로 SNS가 그 프레임을 대표 이미지로 선택한다고 보장할 수도 없습니다. 플랫폼에서 최종 확인하세요.

UUP 쇼핑 페이지 상품 카드의 이미지로 썸네일을 전달하는 경로는 채널 대표 이미지 지원 여부와 별개입니다.

## KB-OUT-007 · 캐러셀 카드뉴스 새로 만들기

**목적:** 하나의 주제를 넘겨 읽는 정사각형 이미지 카드 여러 장으로 만듭니다. 영상 원본·내레이션·영상 렌더링이 필수인 흐름은 아닙니다.

**선행조건:** 로그인과 저장 폴더 설정, 사용 가능한 Gemini 계열 인증이 필요합니다. 대본과 이미지 생성은 외부 API를 사용합니다.

1. 사이드 메뉴 **캐러셀**에서 **새 카드뉴스**를 누릅니다.
2. **주제 / 참고자료**에 만들 이야기를 입력하거나 참고 글을 붙여 넣습니다. 최대 20,000자입니다.
3. **장수 (카드 수)**를 4~20장 사이로 정합니다. 기본은 8장입니다.
4. **언어**에서 한국어·영어·일본어를 고릅니다.
5. **이야기를 풀어낼 방식**에서 정보전달형·웹툰형·스토리텔링형·리스트형·질문답변형 중 하나를 고릅니다.
6. 필요하면 **추가 지시**를 입력합니다.
7. **카드뉴스 대본 생성**을 누릅니다. 커버부터 마무리까지의 카드 흐름과 문구를 생성합니다.
8. **카드 작업대**에서 각 카드의 제목·문구·이미지 프롬프트를 확인한 뒤 이미지 생성을 진행합니다.

대본 생성은 이미지 생성과 별개입니다. 문구 미리보기만 보인다면 아직 카드 이미지가 완성되지 않은 상태일 수 있습니다. **카드뉴스 대본 다시 만들기**는 카드 구성을 다시 생성하므로 기존 편집을 유지하려는 경우 카드별 문구를 직접 수정하는 편이 맞습니다.

## KB-OUT-008 · 카드 수정과 이미지 일괄 생성

1. 카드 번호나 이전·다음 버튼으로 카드를 선택합니다.
2. **이 카드 다듬기**에서 **제목**(최대 40자)과 **문구**(최대 120자)를 수정합니다.
3. 세부 장면이 필요하면 **이미지 프롬프트 편집**을 펼쳐 수정합니다.
4. **문구 저장**으로 수정 내용을 저장합니다.
5. **이 카드 이미지 만들기** 또는 **이미지 다시 만들기**를 눌러 수정한 문구가 들어간 이미지를 생성합니다.

저장된 문구와 이미지는 구분됩니다. 문구만 고쳤을 때 기존 이미지의 글자가 즉시 바뀌지 않습니다. 수정 문구를 반영하려면 해당 이미지를 다시 만드세요.

**이미지 N장 일괄 생성**은 아직 이미지가 없는 카드를 순서대로 처리합니다. 일부가 완성되면 **남은 N장 일괄 생성**으로 표시됩니다. 이미 완성한 카드까지 바꾸려면 **모두 다시 만들기**를 사용합니다.

일괄 작업의 **중단**은 현재 처리 중인 카드까지 마친 뒤 멈춥니다. 즉시 모든 공급자 요청을 취소하거나 과금을 되돌린다는 뜻은 아닙니다. 진행 표시의 처리 수·실패 수를 확인하고 실패한 카드의 오류 안내에 따라 다시 만드세요. 연속 3장이 실패하면 일괄 생성을 자동 중단하므로 인증·한도 등 공통 원인을 해결한 뒤 재시도합니다. 스타일을 변경한 뒤에는 화면의 기존 대본 스타일 불일치 안내를 확인합니다.

## KB-OUT-009 · PNG와 ZIP 내려받기

- **카드 한 장:** 이미지를 만든 뒤 카드 아래 **내려받기**를 누르고 PNG 저장 위치를 정합니다.
- **여러 장:** **zip 내려받기 (N장)**를 누르고 저장 위치를 정합니다. 이미지가 한 장 이상 있으면 사용할 수 있습니다.
- **프로젝트 찾기:** 편집 화면 위 **폴더**로 작업 폴더를 열 수 있습니다. **목록**으로 돌아가 기존 카드뉴스를 다시 엽니다.

ZIP에는 생성되어 존재하는 이미지가 카드 순서에 맞는 `제목 01.png` 형태의 이름으로 들어갑니다. 이미지가 없는 카드는 빠집니다. 예를 들어 8장 중 5장만 만들었다면 ZIP은 5장짜리일 수 있으므로 내려받기 전 완성 수를 확인합니다. ZIP은 카드뉴스 프로젝트 폴더 밖에 저장해야 합니다.

현재 이 카드뉴스 흐름의 결과물은 PNG 또는 ZIP입니다. 영상 MP4 렌더링이나 캐러셀을 UUP로 바로 게시하는 절차로 안내하지 않습니다. 내려받은 카드를 게시하려면 대상 서비스가 제공하는 이미지·캐러셀 게시 절차를 별도로 사용하세요.

## KB-OUT-010 · 자주 묻는 질문

**Q. 렌더 완료인데 UUP에서 다시 렌더하라고 해요.**

A. 렌더 후 영상에 영향을 주는 설정이 바뀌었는지 확인하세요. 최신 검증 결과가 필요합니다.

**Q. 썸네일이 미리보기 시작에 안 보여요.**

A. 디자인 미리보기는 본편부터 시작합니다. **영상 맨 앞에 표시**를 켠 뒤 최종 렌더한 MP4에서 확인하세요.

**Q. 카드 문구를 고쳤는데 다운로드한 이미지가 옛날 내용이에요.**

A. 문구를 저장한 뒤 **이미지 다시 만들기**를 실행해야 이미지에 반영됩니다.

**Q. ZIP에 모든 카드가 없어요.**

A. 이미지가 있는 카드만 포함됩니다. 남은 카드 생성 또는 오류 재시도를 마치고 다시 내려받으세요.

**Q. 캐러셀도 영상과 같은 프로젝트인가요?**

A. 별도 메뉴와 저장 흐름을 가진 카드뉴스 작업입니다. 영상의 대본·음성·렌더링·UUP 전달 단계와 구분합니다.

## 구현 근거

- `app.go`: `Render`, `renderCore`; 선행검사, 출력 진행, 검증 결과 기록, 외부 내보내기 무결성 검사, SRT 시간 보정.
- `internal/media/render.go`: `Service.Render`; 소스·음성 실측, 길이 계획, 최종 검사, 부분 파일 처리.
- `app_thumbnail.go`: `GenerateThumbnail`; 참조 구성, Gemini 요청, 이미지 파일 저장·선택.
- `frontend/src/main.ts`: `renderThumbnail`, `renderDesignPreflight`, `renderDesign`; 실제 버튼·출력 규격·앞장 안내.
- `frontend/src/carousel.ts`: `CAROUSEL_CARD_MIN/MAX/DEFAULT`, `CAROUSEL_STYLES`, `renderCarouselPage`, `renderCarouselBatchActions`.
- `app_carousel.go`: `GenerateCarouselScript`, `GenerateCarouselCardImage`, `ExportCarouselCard`, `ExportCarouselZip`.
- `internal/uup/contract.go`: `SupportsCover`; `frontend/src/uup.ts`: `renderUUPHandoff`.
- 기준일의 구현을 읽어 정리했다. 이번 문서 정비에서 유료 이미지 생성, 모든 플레이어 재생, 실제 플랫폼 커버 적용을 새로 검증한 것은 아니다.