7a92c59bc4
- 스크린샷 → Gemini 분석 → 주석 슬라이드 → TTS 나레이션 → FFmpeg 합성 - 기존 Google API Key + TTS/BGM 서비스 재사용 - 4단계 로드맵 (MVP 2주 → PPTX → 고급기능 → 자동화) - 영상당 비용 ~$0.07 (Veo 미사용) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
18 KiB
18 KiB
SAM 사용법 설명 영상 자동 생성 시스템 계획서
목적: 고객에게 SAM 사이트의 사용법을 설명하는 영상을 AI 기반으로 자동 생성
1. 핵심 아이디어
SAM 화면 스크린샷 → AI 분석 → 설명 대본 생성 → 주석 슬라이드 생성 → 나레이션 + 영상 합성
고객이 SAM의 특정 메뉴/화면을 선택하면, AI가 해당 화면을 분석하여 "사용법 설명 영상"을 자동으로 만들어주는 시스템.
2. 기술 가능성 분석
| 기술 | 활용 | 현재 보유 여부 |
|---|---|---|
| Gemini API (스크린샷 분석) | 화면 캡처 → UI 요소 인식 + 설명 대본 생성 | ✅ API Key 보유 |
| Google Cloud TTS | 대본 → 한국어 나레이션 음성 생성 | ✅ 이미 Veo3에서 사용 중 |
| FFmpeg | 이미지 시퀀스 + 나레이션 + BGM → MP4 합성 | ✅ Docker에 설치됨 |
| LibreOffice | PPTX → 슬라이드 이미지 변환 | ⬜ Docker에 설치 필요 |
| python-pptx | 주석/하이라이트가 포함된 PPTX 생성 | ⬜ composer/pip 설치 필요 |
| GD/Imagick (PHP) | 스크린샷에 하이라이트/화살표/번호 오버레이 | ✅ PHP 확장 사용 가능 |
불가능한 것 (제외)
- ❌ python-pptx의 애니메이션 기능 → 미지원 (대안: 단계별 슬라이드 분리)
- ❌ Veo로 PPTX 직접 변환 → 미지원 (대안: 이미지 시퀀스 + FFmpeg)
- ❌ LibreOffice의 애니메이션/전환 효과 보존 → 손실됨 (대안: FFmpeg 전환 효과)
3. 생성 파이프라인
Phase 1: 입력 & AI 분석
[사용자]
│
├── SAM 메뉴 선택 (예: "견적서 관리")
│
└── 시스템이 해당 화면의 스크린샷을 자동 캡처
또는 사용자가 스크린샷 업로드
Gemini 분석 (핵심)
입력: SAM 화면 스크린샷 이미지
출력 (JSON):
{
"page_title": "견적서 관리",
"page_description": "견적서를 생성, 조회, 수정할 수 있는 화면입니다.",
"ui_elements": [
{
"name": "검색 필터",
"type": "form",
"position": {"x": 100, "y": 200, "w": 800, "h": 60},
"description": "날짜, 거래처, 상태 등으로 견적서를 검색합니다.",
"how_to_use": "원하는 조건을 선택한 후 검색 버튼을 클릭하세요."
},
{
"name": "신규 작성 버튼",
"type": "button",
"position": {"x": 900, "y": 150, "w": 120, "h": 40},
"description": "새 견적서를 작성합니다.",
"how_to_use": "버튼을 클릭하면 견적서 작성 화면으로 이동합니다."
}
],
"step_by_step": [
{"step": 1, "action": "검색 필터에서 조건을 설정합니다", "focus_element": "검색 필터"},
{"step": 2, "action": "검색 버튼을 클릭합니다", "focus_element": "검색 버튼"},
{"step": 3, "action": "목록에서 원하는 견적서를 클릭합니다", "focus_element": "견적서 목록"},
{"step": 4, "action": "상세 화면에서 내용을 확인합니다", "focus_element": "상세 영역"}
],
"narration_script": "이 화면은 견적서 관리 화면입니다. 상단의 검색 필터로..."
}
Phase 2: 주석 슬라이드 생성
각 step마다 스크린샷에 시각적 주석을 오버레이하여 슬라이드 이미지 생성:
원본 스크린샷
│
├── Step 1 이미지: 검색 필터 영역에 빨간 테두리 + ① 번호 + 화살표
├── Step 2 이미지: 검색 버튼에 빨간 테두리 + ② 번호 + "클릭" 텍스트
├── Step 3 이미지: 목록 행에 하이라이트 + ③ 번호
└── Step 4 이미지: 상세 영역에 하이라이트 + ④ 번호
주석 스타일:
- 빨간색/파란색 테두리 박스 (해당 UI 요소 강조)
- 번호 원형 배지 (①②③④)
- 화살표 (클릭/입력 방향 지시)
- 반투명 딤 처리 (강조 외 영역 어둡게)
- 하단 캡션 바 (현재 설명 텍스트)
구현 방식 2가지:
| 방식 | 장점 | 단점 |
|---|---|---|
| A. PHP GD/Imagick | 추가 설치 없음, Laravel 통합 용이 | 복잡한 그래픽 한계 |
| B. PPTX 생성 → 이미지 변환 | 풍부한 레이아웃, 다운로드 가능 | LibreOffice 설치 필요 |
권장: 두 방식 병행
- 영상용: PHP GD로 직접 이미지 생성 (빠름)
- 다운로드용: PPTX도 함께 생성 (고객이 편집 가능)
Phase 3: 나레이션 생성
Gemini가 생성한 step별 대본
│
└── Google Cloud TTS (ko-KR-Neural2-A, 여성, 1.2x)
│
├── step_1_narration.mp3 (3초)
├── step_2_narration.mp3 (2초)
├── step_3_narration.mp3 (4초)
└── step_4_narration.mp3 (3초)
Phase 4: 영상 합성 (FFmpeg)
슬라이드 이미지 + 나레이션 + 전환효과 + BGM → 최종 MP4
ffmpeg 처리:
1. 각 슬라이드를 나레이션 길이 + 1초 여유만큼 표시
2. 슬라이드 전환: crossfade 0.5초 (부드러운 전환)
3. 나레이션 오디오 합성
4. 배경음악 (볼륨 낮게) 합성
5. 인트로/아웃트로 슬라이드 추가
FFmpeg 전환 효과 (애니메이션 대체):
# 크로스페이드 전환
-filter_complex "xfade=transition=fade:duration=0.5:offset=4"
# 줌인 효과 (요소 강조 시)
-filter_complex "zoompan=z='min(zoom+0.001,1.3)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=75"
# 슬라이드 와이프 전환
-filter_complex "xfade=transition=wipeleft:duration=0.5:offset=4"
4. 화면 구성 (MNG 관리자 UI)
┌─────────────────────────────────────────────────────┐
│ SAM 사용법 영상 생성기 │
├─────────────────────────────────────────────────────┤
│ │
│ [Step 1] 화면 선택 │
│ ┌──────────────────────────────────────────┐ │
│ │ 메뉴 트리에서 선택 또는 스크린샷 업로드 │ │
│ │ │ │
│ │ 📁 견적 관리 │ │
│ │ ├── 견적서 목록 │ │
│ │ ├── 견적서 작성 │ │
│ │ └── 견적서 상세 │ │
│ │ 📁 주문 관리 │ │
│ │ ├── ... │ │
│ │ │ │
│ │ [스크린샷 직접 업로드] [URL로 캡처] │ │
│ └──────────────────────────────────────────┘ │
│ │
│ [Step 2] AI 분석 결과 확인/편집 │
│ ┌──────────────────────────────────────────┐ │
│ │ 🤖 AI가 분석한 UI 요소: │ │
│ │ │ │
│ │ ① 검색 필터 [수정] │ │
│ │ 설명: 날짜, 거래처 등으로 검색... │ │
│ │ ② 신규 작성 버튼 [수정] │ │
│ │ 설명: 새 견적서를 작성합니다... │ │
│ │ ③ 견적서 목록 [수정] │ │
│ │ 설명: 조회된 견적서 목록... │ │
│ │ │ │
│ │ 나레이션 대본: [편집 가능한 텍스트] │ │
│ │ 음성: [여성 ▼] 속도: [1.2x ▼] │ │
│ └──────────────────────────────────────────┘ │
│ │
│ [Step 3] 미리보기 & 생성 │
│ ┌──────────────────────────────────────────┐ │
│ │ [미리보기: 주석 슬라이드 캐러셀] │ │
│ │ ◀ [슬라이드 1/4] ▶ │ │
│ │ │ │
│ │ [🎬 영상 생성] [📄 PPTX 다운로드] │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
5. 영상 구성 템플릿
기본 영상 구조 (1개 화면당)
| 구간 | 시간 | 내용 |
|---|---|---|
| 인트로 | 3초 | SAM 로고 + "견적서 관리 사용법" 타이틀 |
| 전체 화면 소개 | 5초 | 원본 스크린샷 + "이 화면은 ~입니다" 나레이션 |
| Step 1 | 나레이션 길이 + 1초 | 요소 ① 하이라이트 + 설명 나레이션 |
| Step 2 | 나레이션 길이 + 1초 | 요소 ② 하이라이트 + 설명 나레이션 |
| Step N | ... | ... |
| 아웃트로 | 3초 | "문의: support@juil.co.kr" + 로고 |
예상 영상 길이
- 단순 화면 (3
4개 요소): 3045초 - 복잡한 화면 (6
8개 요소): 6090초 - 워크플로우 (여러 화면 연결): 2~3분
6. 구현 단계별 로드맵
Stage 1: 핵심 파이프라인 (MVP) — 2주
목표: 스크린샷 1장 → 설명 영상 1개 생성
구현 항목:
├── [백엔드] TutorialVideoController (CRUD + 생성 Job)
├── [백엔드] ScreenAnalysisService (Gemini 스크린샷 분석)
├── [백엔드] SlideImageService (PHP GD로 주석 이미지 생성)
├── [백엔드] TutorialAssemblyService (FFmpeg 영상 합성)
├── [백엔드] TutorialVideoJob (Queue Job)
├── [프론트] 스크린샷 업로드 + AI 분석 결과 UI
├── [프론트] 영상 생성/미리보기/다운로드
└── [인프라] Docker에 LibreOffice 설치 (PPTX→이미지 변환용)
사용하는 API:
- Gemini 3.0 Flash → 스크린샷 분석 + 대본 생성
- Google Cloud TTS → 나레이션 음성
- FFmpeg → 최종 영상 합성
비용 (영상 1개당):
- Gemini: ~$0.001 (이미지 분석)
- TTS: ~$0.01 (60초 나레이션)
- 총 약 $0.01/영상 (Veo 미사용)
Stage 2: PPTX 생성 + 편집 기능 — 1주
추가 구현:
├── [백엔드] PptxGeneratorService (python-pptx 기반 PPTX 생성)
│ ├── 인트로 슬라이드 (SAM 로고 + 제목)
│ ├── Step별 주석 슬라이드
│ └── 아웃트로 슬라이드
├── [프론트] AI 분석 결과 편집 (요소 추가/삭제/순서 변경)
├── [프론트] 나레이션 대본 직접 편집
└── [프론트] PPTX 다운로드 버튼
Stage 3: 고급 기능 — 2주
추가 구현:
├── SAM 메뉴 트리 연동 (메뉴 선택 → 해당 화면 자동 캡처)
├── 다중 화면 워크플로우 (화면 A → B → C 연결 영상)
├── FFmpeg 줌/팬 애니메이션 (요소별 줌인 효과)
├── 영상 템플릿 시스템 (인트로/아웃트로 커스터마이징)
├── Lyria BGM 자동 생성 (기존 BgmService 재사용)
└── 생성된 영상 관리 (목록, 삭제, 재생성)
Stage 4: 자동화 & 배포 — 1주
추가 구현:
├── 고객 포털에 영상 임베드 (공개 URL)
├── SAM 화면 변경 시 영상 자동 재생성 알림
├── 다국어 지원 (영어/일본어 나레이션)
└── GCS 업로드 + CDN 배포
7. 기술 아키텍처
┌─────────────────────────────────────────────────────────────┐
│ MNG (Laravel) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Tutorial │ │ Screen │ │ SlideImage │ │
│ │ Video │──▶│ Analysis │──▶│ Service │ │
│ │ Controller │ │ Service │ │ (PHP GD) │ │
│ └──────┬───────┘ │ (Gemini) │ └────────┬─────────┘ │
│ │ └──────────────┘ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Tutorial │ │ TTS │ │ Tutorial │ │
│ │ Video Job │──▶│ Service │──▶│ Assembly Service │ │
│ │ (Queue) │ │ (기존 재사용) │ │ (FFmpeg 합성) │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Pptx │ │ BGM │ │
│ │ Generator │ │ Service │ │
│ │ (python-pptx)│ │ (기존 재사용) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Google Cloud APIs │
│ │
│ • Gemini 3.0 Flash │
│ (스크린샷 분석) │
│ • Cloud TTS │
│ (나레이션 생성) │
│ • Lyria (BGM, 선택) │
│ • GCS (영상 저장) │
└───────────────────────┘
8. 기존 코드 재사용
| 기존 서비스 | 재사용 내용 |
|---|---|
TtsService |
나레이션 음성 생성 (ko-KR-Neural2-A) |
BgmService |
배경음악 생성 (Lyria or 프리셋) |
VideoAssemblyService |
FFmpeg 합성 로직 참고 (새 서비스로 분리) |
GeminiScriptService.callGemini() |
Gemini API 호출 공통 로직 |
GoogleCloudStorageService |
GCS 업로드/서명 URL |
GoogleCloudService |
OAuth 토큰 관리 |
9. DB 스키마 (신규 테이블)
CREATE TABLE tutorial_videos (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
tenant_id INT UNSIGNED NOT NULL,
user_id INT UNSIGNED NOT NULL,
-- 입력
title VARCHAR(255) NOT NULL COMMENT '영상 제목 (예: 견적서 관리 사용법)',
menu_id INT UNSIGNED NULL COMMENT 'SAM 메뉴 ID (선택)',
screenshot_path TEXT NULL COMMENT '원본 스크린샷 경로',
-- AI 분석 결과
analysis JSON NULL COMMENT 'Gemini 분석 결과 (UI 요소, 대본 등)',
-- 생성 설정
voice_name VARCHAR(50) DEFAULT 'ko-KR-Neural2-A',
speaking_rate DECIMAL(3,1) DEFAULT 1.2,
bgm_mood VARCHAR(50) DEFAULT 'calm',
-- 출력
status VARCHAR(30) DEFAULT 'pending',
progress TINYINT UNSIGNED DEFAULT 0,
current_step VARCHAR(100) NULL,
slides_data JSON NULL COMMENT '생성된 슬라이드 이미지 경로들',
pptx_path TEXT NULL COMMENT 'PPTX 파일 경로',
output_path TEXT NULL COMMENT '최종 MP4 경로',
gcs_path VARCHAR(500) NULL,
cost_usd DECIMAL(8,4) DEFAULT 0,
error_message TEXT NULL,
created_at TIMESTAMP NULL,
updated_at TIMESTAMP NULL,
INDEX idx_tenant_user (tenant_id, user_id),
INDEX idx_status (status)
);
10. 비용 분석
영상 1개 생성 비용
| 항목 | 비용 | 비고 |
|---|---|---|
| Gemini (스크린샷 분석) | ~$0.001 | Flash 모델, 이미지 1장 |
| Google Cloud TTS | ~$0.01 | 60초 분량 나레이션 |
| Lyria BGM (선택) | ~$0.06 | 30초 BGM 생성 |
| FFmpeg | $0 | 로컬 처리 |
| GCS 저장 | ~$0.001 | 50MB 영상 기준 |
| 합계 | ~$0.07 | Veo 미사용으로 저렴 |
Veo3 Shorts 영상 대비
| 튜토리얼 영상 | Veo3 Shorts | |
|---|---|---|
| 영상당 비용 | ~$0.07 | ~$7.00 |
| 생성 시간 | 1~2분 | 15~25분 |
| 용도 | 화면 설명 | 창작 콘텐츠 |
11. 기대 효과
- 고객 문의 감소: 반복되는 "이 기능 어떻게 쓰나요?" 문의를 영상으로 대체
- 빠른 온보딩: 신규 고객이 SAM 주요 기능을 영상으로 빠르게 학습
- 유지보수 용이: 화면 변경 시 스크린샷만 다시 업로드하면 영상 재생성
- PPTX 병행: 영상뿐 아니라 인쇄용 매뉴얼(PPTX)도 동시 제공
- 저비용: Veo 없이 이미지+TTS+FFmpeg만으로 영상당 $0.07
12. 우선순위 제안
| 순위 | 항목 | 이유 |
|---|---|---|
| 1 | Stage 1 (MVP) | 핵심 가치 검증 — 스크린샷 1장으로 영상 생성 가능 여부 확인 |
| 2 | Stage 2 (PPTX) | 고객이 직접 편집 가능한 산출물 제공 |
| 3 | Stage 3 (고급) | 줌 애니메이션, 다중 화면 워크플로우로 품질 향상 |
| 4 | Stage 4 (배포) | 고객 포털 연동, 자동화 |