# 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 전환 효과 (애니메이션 대체):** ```bash # 크로스페이드 전환 -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개 요소): 30~45초 - 복잡한 화면 (6~8개 요소): 60~90초 - 워크플로우 (여러 화면 연결): 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 스키마 (신규 테이블) ```sql 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. 기대 효과 1. **고객 문의 감소**: 반복되는 "이 기능 어떻게 쓰나요?" 문의를 영상으로 대체 2. **빠른 온보딩**: 신규 고객이 SAM 주요 기능을 영상으로 빠르게 학습 3. **유지보수 용이**: 화면 변경 시 스크린샷만 다시 업로드하면 영상 재생성 4. **PPTX 병행**: 영상뿐 아니라 인쇄용 매뉴얼(PPTX)도 동시 제공 5. **저비용**: Veo 없이 이미지+TTS+FFmpeg만으로 영상당 $0.07 --- ## 12. 우선순위 제안 | 순위 | 항목 | 이유 | |------|------|------| | 1 | Stage 1 (MVP) | 핵심 가치 검증 — 스크린샷 1장으로 영상 생성 가능 여부 확인 | | 2 | Stage 2 (PPTX) | 고객이 직접 편집 가능한 산출물 제공 | | 3 | Stage 3 (고급) | 줌 애니메이션, 다중 화면 워크플로우로 품질 향상 | | 4 | Stage 4 (배포) | 고객 포털 연동, 자동화 |