feat: NotebookLM 통합 — 멀티미디어 콘텐츠 생성 연동

[inbeomheo]

Problem Statement

현재 Insight Engine은 YouTube URL에서 자막을 추출하고 AI로 텍스트 콘텐츠를 생성하지만, 팟캐스트(오디오), 비디오, 인포그래픽, 슬라이드 같은 멀티미디어 콘텐츠는 생성할 수 없다. 사용자가 이런 콘텐츠를 원하면 NotebookLM 웹에 직접 들어가 수동으로 소스를 추가하고 생성해야 하는 번거로움이 있다.

또한 기존 TTS 팟캐스트 변환, 마인드맵 기능은 NotebookLM의 동일 기능보다 품질이 낮아 중복이 발생한다.

Solution

NotebookLM CLI(nlm)를 백엔드 서비스로 래핑하여, 결과 카드의 더보기 메뉴에서 NotebookLM 콘텐츠를 원클릭으로 생성할 수 있게 한다.

핵심 설계

• 노트북 1개 고정 재사용: 앱 최초 사용 시 노트북 1개 생성, 이후 영상 생성 시마다 자막을 소스로 추가
• 기존 중복 기능 제거: TTS 팟캐스트 변환, 마인드맵을 NotebookLM으로 대체
• 결과 하이브리드 표시: 생성 중 → 카드에 진행 표시, 완료 → 카드 내 NotebookLM 섹션 (오디오 플레이어, 이미지 미리보기, 다운로드)

User Stories

1. 사용자가 YouTube 영상으로 콘텐츠를 생성한 후, 더보기 메뉴에서 "NotebookLM 팟캐스트"를 클릭하면 해당 영상 자막으로 AI 팟캐스트가 생성된다
2. 사용자가 더보기 메뉴에서 "NotebookLM 비디오"를 클릭하면 해당 영상 자막 기반 설명 비디오가 생성된다
3. 사용자가 더보기 메뉴에서 "NotebookLM 인포그래픽"을 클릭하면 시각적 인포그래픽이 생성된다
4. 사용자가 더보기 메뉴에서 "NotebookLM 슬라이드"를 클릭하면 프레젠테이션 덱이 생성된다
5. 사용자가 더보기 메뉴에서 "NotebookLM 마인드맵"을 클릭하면 마인드맵이 생성된다
6. 사용자가 더보기 메뉴에서 "NotebookLM 퀴즈"를 클릭하면 퀴즈 문항이 생성된다
7. 사용자가 더보기 메뉴에서 "NotebookLM 플래시카드"를 클릭하면 학습용 플래시카드가 생성된다
8. 사용자가 더보기 메뉴에서 "NotebookLM 브리핑"을 클릭하면 브리핑 문서가 생성된다
9. 사용자가 더보기 메뉴에서 "NotebookLM 스터디 가이드"를 클릭하면 학습 가이드가 생성된다
10. 생성이 시작되면 카드에 진행 상태가 표시되어 사용자가 대기 시간을 알 수 있다
11. 생성이 완료되면 카드 하단에 NotebookLM 섹션이 나타나 오디오 플레이어/이미지 미리보기/다운로드 버튼을 제공한다
12. 앱 최초 사용 시 NotebookLM 노트북이 자동 생성되고, 이후에는 동일 노트북을 재사용한다
13. 콘텐츠 생성 시 자막이 NotebookLM 소스로 자동 추가된다 (이미 추가된 소스는 중복 추가하지 않음)
14. 기존 TTS 팟캐스트 변환 메뉴 항목이 제거되고 NotebookLM 팟캐스트로 대체된다
15. 기존 마인드맵 메뉴 항목이 제거되고 NotebookLM 마인드맵으로 대체된다
16. 오디오/비디오 생성 완료 시 다운로드 버튼으로 파일을 로컬에 저장할 수 있다
17. NotebookLM 인증이 안 된 상태에서 메뉴를 클릭하면 인증 안내 메시지가 표시된다
18. 생성 실패 시 에러 메시지와 재시도 버튼이 표시된다

Implementation Decisions

백엔드

• services/notebooklm/notebooklm_service.py 신규 모듈: nlm CLI를 subprocess로 래핑하는 서비스. 노트북 관리, 소스 추가, 콘텐츠 생성, 상태 폴링, 다운로드를 캡슐화
• 노트북 ID 관리: 서버 시작 시 기존 노트북 확인, 없으면 생성. ID를 config 또는 로컬 파일에 저장하여 재사용
• 소스 중복 방지: YouTube URL 또는 자막 해시를 기준으로 이미 추가된 소스인지 확인
• 비동기 생성: 생성 요청은 즉시 반환(artifact_id), 프론트엔드가 상태 폴링
• API 엔드포인트:
  • POST /api/notebooklm/generate — 콘텐츠 생성 요청 (type, source_text, url)
  • GET /api/notebooklm/status/<artifact_id> — 생성 상태 폴링
  • GET /api/notebooklm/download/<artifact_id> — 완성 파일 다운로드
  • GET /api/notebooklm/auth-check — 인증 상태 확인

프론트엔드

• ResultCard 더보기 메뉴: 기존 "팟캐스트로 변환", "마인드맵" 제거 → "NotebookLM" 서브메뉴 그룹으로 9개 항목 추가
• NotebookLmSection 컴포넌트: ResultCard 하단에 조건부 렌더링. 기존 SeoSection, GeoSection 패턴과 동일
  • 오디오: 인라인 <audio> 플레이어 + 다운로드
  • 비디오: 썸네일 + 다운로드
  • 인포그래픽/슬라이드: 이미지 미리보기 + 다운로드
  • 텍스트(퀴즈/플래시카드/브리핑/스터디가이드): 접기/펼치기 텍스트
  • 마인드맵: 기존 마인드맵 뷰어 재활용 가능
• 상태 관리: Report 타입에 notebooklm 필드 추가 (artifacts 배열, 각 artifact의 type/status/url)
• 폴링: 생성 시작 후 5초 간격으로 상태 폴링, 완료 시 카드 업데이트

제거 대상

• handleTts 및 관련 TTS 코드 (ResultCard의 "팟캐스트로 변환")
• setMindmapModalOpen 및 마인드맵 모달 (NotebookLM 마인드맵으로 대체)

Testing Decisions

좋은 테스트 = 외부 동작만 검증, 내부 구현 세부사항은 테스트하지 않음.

테스트 대상 모듈

1. notebooklm_service.py: 핵심 서비스. subprocess 호출을 mock하여 테스트

   • 노트북 생성/조회 로직
   • 소스 중복 방지 로직
   • 콘텐츠 생성 → 상태 폴링 → 다운로드 흐름
   • 에러 핸들링 (인증 만료, 타임아웃, 네트워크 에러)
   • 기존 패턴: @patch('services.xxx_service.subprocess') 또는 @patch('subprocess.run')

2. API 라우트 테스트: Flask test client로 엔드포인트 검증

   • 기존 패턴: tests/ 디렉토리의 route 테스트 참조

3. 프론트엔드: NotebookLmSection 컴포넌트 렌더링 (선택적)

Out of Scope

• NotebookLM 인증 자동화 (사용자가 nlm login으로 직접 인증해야 함)
• NotebookLM 노트북 삭제/관리 UI
• 여러 노트북 지원 (v1은 단일 노트북)
• NotebookLM 리서치(딥리서치) 기능 연동
• 오디오/비디오 스트리밍 재생 (다운로드만 지원)

Further Notes

• NotebookLM CLI(nlm)는 커뮤니티 도구이므로, NotebookLM UI 변경 시 동작이 불안정해질 수 있음. 서비스 레이어에서 graceful degradation 처리 필요
• 세션 만료 (~20분)로 인해 장시간 사용 시 재인증 필요. 에러 발생 시 사용자에게 nlm login 안내
• 오디오/비디오 생성은 1~10분 소요. 사용자가 페이지를 떠나도 백엔드에서 폴링 지속하고, 돌아왔을 때 결과 표시 고려
• nlm CLI의 --confirm 플래그는 필수. 서비스에서 항상 포함