Voilaa! — Google Gemini를 사용하여 모든 YouTube 영상을 인터랙티브 학습 앱으로 변환하기

Voilaa! — Google Gemini를 사용하여 모든 YouTube 영상을 인터랙티브 학습 앱으로 변환하기

이 포스트는 DEV Education Track: Build Apps with Google AI Studio에 제출하기 위한 저의 작업물입니다.

내가 만든 것

**Voilaa!**는 모든 YouTube 영상을 풍부하고 인터랙티브한 학습 경험으로 변환하는 풀스택 (Full-stack) 교육용 놀이터입니다. 실시간 퀴즈, 플래시카드 (Flashcard) 덱, 공식 시뮬레이터, 데이터 시각화 등을 상상해 보세요. 이 모든 것은 Google Gemini AI에 의해 즉석에서 생성됩니다.

아이디어는 간단합니다: YouTube URL을 붙여넣고, 학술적 깊이를 선택하면, 몇 초 안에 Gemini가 영상의 내용을 분석하고 해당 레슨에 딱 맞춘 완전히 기능적이고 독립적인 인터랙티브 HTML 학습 앱을 합성해 냅니다.

작동 방식

이 마법은 전적으로 서버 측에서 실행되는 2단계 AI 체인 (AI chain)으로 이루어집니다:

1단계 — 의미론적 분석가 (Semantic Analyst) (Gemini 1.5 Flash / Pro)

첫 번째 모델은 교육학자 (Pedagogist) 역할을 합니다. 영상을 시청하고 다음과 같은 내용이 포함된 구조화된 JSON 페이로드 (Payload)를 생성합니다:

• spec — 앱의 핵심 메커니즘, 상호작용 및 교육 목표를 설명하는 독립적인 커리큘럼 청사진 (Blueprint).
• flashcards — 능동적 회상 (Active recall)을 위해 영상에서 추출한 최소 5개의 핵심 용어와 정의.

이 단계를 위해 제가 정교하게 만든 프롬프트 (Prompt)는 프로젝트 전체에서 가장 중요한 부분이었습니다:

You are a pedagogist and product designer with deep expertise in crafting 
engaging learning experiences via interactive web apps.

...

2단계 — 소프트웨어 아키텍트 (Software Architect) (Gemini 1.5 Pro)

두 번째 모델은 명세(Spec)를 전달받아 깨끗한 단일 파일 HTML/CSS/JS 애플리케이션을 생성합니다. 프레임워크 (Framework)나 외부 의존성 (External dependencies) 없이 샌드박스된 iframe 내부에서 바로 실행될 수 있도록 준비됩니다.

사용자에게 노출된 주요 프롬프트 제어 항목:

• Temperature (온도) — AI의 창의성을 조절합니다 (0.0 → 1.0)
• Academic Intensity (학술적 강도) — 간결함 (Concise), 균형 잡힘 (Balanced), 또는 상세함 (Detailed) 레슨 깊이 선택
• Model Selection (모델 선택) — 각 단계에서 Flash와 Pro 사이를 전환

기술 스택 (The Tech Stack)

기술 스택 (The Tech Stack)

Layer	Technology
Frontend	React 18 + Vite (SPA)
...
Gemini API 키는 오직 서버에서만 존재하며, 클라이언트 번들에는 절대 노출되지 않습니다.

워크스페이스 (The Workspace)

학습 앱이 생성되면 사용자는 세 개의 탭으로 구성된 워크스페이스를 얻게 됩니다:

🖥️ 렌더 탭 (Render Tab)

생성된 앱을 실행하는 라이브 샌드박스 <iframe>입니다. 페이지 새로고침 없이 완전히 상호작용이 가능합니다.

📝 소스 탭 (Source Tab)

원시 생성된 HTML/JS/CSS를 보여주고(그리고 편집할 수 있게 하는) 전체 Monaco Editor입니다. 저장된 변경 사항은 미리보기를 즉시 핫 리로드합니다.

📋 스펙 탭 (Spec Tab)

Semantic Analyst가 생성한 커리큘럼 청사진을 검사하거나 편집할 수 있습니다. 수정 사항을 반영하여 재구성을 요청하는 데 유용합니다.

또한, 방해 요소를 줄이고 집중할 수 있도록 주변 UI를 흐릿하게 만드는 Zen Mode와 방해받지 않는 학습을 위한 Fullscreen Mode가 제공됩니다.

데모 (Demo)

🔗 실시간 앱 → (https://voilaa-498153626537.us-west1.run.app/)

예시: 음악 이론에 관한 YouTube 튜토리얼 붙여넣기

→ Gemini가 코드 진행, 긴장감(tension), 해결(resolution)을 분석합니다.

→ 코드 클릭 피드백이 있는 인터랙티브 피아노 시뮬레이터를 생성합니다.

→ 플래시카드 덱에는 다음 내용이 포함됩니다: 토닉(Tonic), 도미넌트(Dominant), 리딩 톤(Leading Tone), 카덴스(Cadence), 보이스 리딩(Voice Leading)

예시: 정렬 알고리즘에 관한 YouTube 강의 붙여넣기

→ Gemini가 단계별 애니메이션 버블 정렬/병합 정렬 시각화 도구를 생성합니다.

→ 플래시카드는 시간 복잡도(time complexity), 제자리 정렬(in-place sorting), 안정성(stability) 등을 다룹니다.

저의 경험 (My Experience)

가장 놀라웠던 점

저는 프론트엔드 샌드박스 메커니즘이 가장 어려울 것이라고 예상했습니다. 그렇지 않았습니다. 가장 어려웠던 부분은 Semantic Analyst에 대한 프롬프트 엔지니어링이었습니다.

초기 버전의 스펙 프롬프트는 너무 모호한(

이 문장 하나만으로 출력 품질이 극적으로 향상되었습니다. Gemini는 막연한 희망 사항 대신, 명확하게 범위가 지정된 구체적인 메커니즘을 가진 스펙(specs)을 생성하기 시작했습니다.

배운 점

1. 두 개의 모델 체인(Two-model chains)을 사용하면 단일 프롬프트로는 얻을 수 없는 품질을 확보할 수 있습니다. "무엇을 만들지 생각하기"와 "코드를 작성하기"를 분리함으로써 훨씬 더 나은 결과를 얻었습니다. 기획 모델(planning model)은 교육학(pedagogy)에 완전히 집중할 수 있었고, 코딩 모델(coding model)은 구현(implementation)에만 온전히 집중할 수 있었습니다.

2. 창의적인 교육 콘텐츠를 만들 때는 모델의 선택보다 온도(Temperature) 설정이 더 중요합니다. 약 0.75의 온도는 일관성을 유지하면서도 가장 다양하고 재미있는 학습 앱을 만들어냈습니다.

3. API 키를 서버 측(server-side)에 유지하는 것은 타협할 수 없는 원칙입니다. 해커톤 데모일지라도 Express를 통해 모든 Gemini 호출을 프록시(proxy)하도록 구성하면, 할당량(quota)을 보호하고 키 유출을 방지할 수 있습니다.

4. 샌드박스형 iframe(Sandboxed iframes)의 가치는 과소평가되어 있습니다. 사용자 생성 HTML을 <iframe sandbox="allow-scripts"> 내에서 실행함으로써, XSS나 DOM 오염(DOM pollution)에 대한 걱정 없이 AI가 생성한 코드를 브라우저로 직접 보낼 수 있었습니다.

다음에 만들 것들

• YouTube 자막 API 연동 — 현재 Gemini는 URL과 제목을 통해 영상 콘텐츠를 추론합니다. 자막(transcript)을 직접 입력받을 수 있다면 Semantic Analyst가 전체 구어체 스크립트를 바탕으로 작업할 수 있을 것입니다.
• 학습 이력(Lesson history) — 영상별로 이전에 생성된 앱을 저장하고 다시 방문할 수 있는 기능.
• 공유 링크 — 사용자가 생성한 학습 앱을 짧은 URL로 게시할 수 있는 기능.
• 협업 편집(Collaborative editing) — 스터디 그룹이 함께 스펙을 편집하고 공동으로 다시 생성할 수 있는 기능.

Voilaa!는 제작 과정이 진심으로 즐거운 프로젝트였습니다. Gemini의 멀티모달(multimodal) 이해 능력과 @google/genai SDK의 유연성이 결합되어, 복잡할 수 있었던 AI 통합 과정을 놀라울 정도로 깔끔하게 만들어 주었습니다. 만약 지금 유튜브의 알고리즘 속에서 길을 잃고 헤매고 있다면 — 그 영상을 인터랙티브한 수업으로 바꿔보는 건 어떨까요? 🎬✨