notebooklm-py: 종합적인 NotebookLM 스킬 및 비공식 Python API

종합적인 NotebookLM 스킬 및 비공식 Python API. Python, CLI, 그리고 Claude Code, Codex, OpenClaw와 같은 AI 에이전트를 통해 웹 UI에서 제공하지 않는 기능을 포함하여 NotebookLM의 기능에 대한 완전한 프로그래밍 방식의 접근을 제공합니다.

소스 및 개발: https://github.com/teng-lin/notebooklm-py

⚠️ 비공식 라이브러리 - 사용 시 주의 사항
이 라이브러리는 예고 없이 변경될 수 있는 문서화되지 않은 Google API를 사용합니다.

• Google과 관련이 없음 - 이는 커뮤니티 프로젝트입니다
• API가 중단될 수 있음 - Google은 언제든지 내부 엔드포인트를 변경할 수 있습니다
• 속도 제한(Rate limits) 적용 - 과도한 사용 시 제한될 수 있습니다
  프로토타입, 연구 및 개인 프로젝트에 가장 적합합니다. 디버깅 팁은 Troubleshooting을 참조하세요.

🤖 AI 에이전트 도구 - NotebookLM을 Claude Code, Codex 및 기타 LLM 에이전트에 통합하세요. GitHub 및 npx skills add 검색을 위한 루트 NotebookLM 스킬, Claude Code 및 .agents 스킬 디렉토리를 위한 로컬 notebooklm skill install 지원, 그리고 AGENTS.md에 포함된 리포지토리 수준의 Codex 가이드를 제공합니다.

📚 연구 자동화 - 소스(URL, PDF, YouTube, Google Drive)를 대량으로 가져오고, 자동 가져오기를 통해 웹/Drive 연구 쿼리를 실행하며, 프로그래밍 방식으로 통찰(Insights)을 추출합니다. 반복 가능한 연구 파이프라인을 구축하세요.

🎙️ 콘텐츠 생성 - 오디오 오버뷰 (Audio Overviews, 팟캐스트), 비디오, 슬라이드 덱, 퀴즈, 플래시카드, 인포그래픽, 데이터 테이블, 마인드맵 및 학습 가이드를 생성합니다. 형식, 스타일 및 출력에 대한 완전한 제어가 가능합니다.

📥 다운로드 및 내보내기 - 생성된 모든 결과물(MP3, MP4, PDF, PNG, CSV, JSON, Markdown)을 로컬에 다운로드합니다. Google Docs/Sheets로 내보낼 수 있습니다. 웹 UI에서 제공하지 않는 기능: 일괄 다운로드, 다양한 형식의 퀴즈/플래시카드 내보내기, 마인드맵 JSON 추출.

방식	최적의 용도
Python API	애플리케이션 통합, 비동기 워크플로 (async workflows), 커스텀 파이프라인
CLI	셸 스크립트 (Shell scripts), 빠른 작업, CI/CD 자동화
에이전트 통합 (Agent Integration)	Claude Code, Codex, LLM 에이전트, 자연어 자동화

카테고리 (Category)	기능 (Capabilities)
Notebooks	생성, 목록 조회, 이름 변경, 삭제
Sources	URL, YouTube, 파일 (PDF, text, Markdown, Word, EPUB, audio, video, images), Google Drive, 붙여넣은 텍스트; 새로고침, 가이드/전체 텍스트 가져오기
Chat	질문, 대화 기록, 커스텀 페르소나 (Custom Personas)
Research	웹 및 Drive 리서치 에이전트 (자동 가져오기 기능 포함, fast/deep 모드 지원)
Sharing	공개/비공개 링크, 사용자 권한 (뷰어/편집자), 보기 수준 제어

유형 (Type)	옵션 (Options)	다운로드 형식 (Download Format)
Audio Overview	4가지 형식 (deep-dive, brief, critique, debate), 3가지 길이, 50개 이상의 언어	MP3/MP4
Video Overview	3가지 형식 (explainer, brief, cinematic), 9가지 시각적 스타일, 전용 cinematic-video CLI 별칭 제공	MP4
Slide Deck	상세형 또는 발표자 형식, 길이 조절 가능; 개별 슬라이드 수정	PDF, PPTX
Infographic	3가지 방향(orientations), 3가지 상세 수준	PNG
Quiz	수량 및 난이도 설정 가능	JSON, Markdown, HTML
Flashcards	수량 및 난이도 설정 가능	JSON, Markdown, HTML
Report	브리핑 문서, 학습 가이드, 블로그 포스트 또는 커스텀 프롬프트	Markdown
Data Table	자연어를 통한 커스텀 구조 생성	CSV
Mind Map	대화형 계층 구조 시각화	JSON

이러한 기능들은 API/CLI를 통해 사용할 수 있지만, NotebookLM의 웹 인터페이스에는 노출되어 있지 않습니다:

일괄 다운로드 (Batch downloads)

• 특정 유형의 모든 아티팩트(artifacts)를 한 번에 다운로드

퀴즈/플래시카드 내보내기 (Quiz/Flashcard export)

• 구조화된 JSON, Markdown 또는 HTML 형식으로 가져오기 (웹 UI에서는 대화형 뷰만 제공)

마인드맵 데이터 추출 (Mind map data extraction)

• 시각화 도구를 위한 계층적 JSON 내보내기

데이터 테이블 CSV 내보내기 (Data table CSV export)

• 구조화된 테이블을 스프레드시트로 다운로드

PPTX 형식의 슬라이드 덱 (Slide deck as PPTX)

• 편집 가능한 PowerPoint 파일로 다운로드 (웹 UI에서는 PDF만 제공)

슬라이드 수정 (Slide revision)

• 자연어 프롬프트(natural-language prompts)를 사용하여 개별 슬라이드 수정

보고서 템플릿 커스터마이징 (Report template customization)

• 내장된 형식 템플릿에 추가 지침을 추가

채팅을 노트로 저장 (Save chat to notes)

• Q&A 답변 또는 대화 기록을 노트북 노트로 저장

소스 전체 텍스트 액세스 (Source fulltext access)

• 모든 소스의 인덱싱된 텍스트 콘텐츠를 검색

프로그래밍 방식의 공유 (Programmatic sharing)

• UI 없이 권한 관리

다중 계정 프로필 (Multi-account profiles)

• 재인증 없이 Google 계정 간 전환

브라우저 쿠키 가져오기 (Browser cookie import)

• Playwright를 구동하는 대신 기존 브라우저 세션의 쿠키를 재사용

전체 설치 가이드 — 6가지 페르소나 (에이전트, 엔드 유저, 라이브러리, 헤드리스, 기여자, 파워 유저), 선택적 추가 기능 매트릭스, 플랫폼 참고 사항 — 는 docs/installation.md에 있습니다.

가장 빠른 시작 (Quickest start) (CLI 사용자 및 AI 에이전트):

pip install "notebooklm-py[browser]" # 코어 + Playwright
playwright install chromium # ~170 MB; 진행 표시줄 없음 — 인내심을 갖고 기다려 주세요 (30–90초)
notebooklm login # Google 로그인을 위해 브라우저를 엽니다
...

라이브러리로 사용 (As a library) (앱에 내장 — Playwright 및 Chromium 미사용):

pip install notebooklm-py # ~10 MB; 미리 획득한 storage_state.json을 함께 배포하세요

Linux에서 playwright install chromium 실행 시 TypeError: onExit is not a function 오류가 발생하면, Linux 워크아라운드(workaround)를 참조하세요. 기여자 (Contributors): CONTRIBUTING.md를 참조하세요.

16분 세션이 30초로 압축됨

# 1. 인증 (브라우저 열기)
notebooklm login
# 또는 Microsoft Edge 사용 (SSO를 위해 Edge가 필요한 조직의 경우)
...

기타 유용한 CLI 명령어:

notebooklm auth check --test # 인증/쿠키 문제 진단
notebooklm auth refresh --quiet # 단발성 쿠키 유지 (cron / launchd / systemd 용)
notebooklm auth refresh --browser-cookies chrome # 계정 라우팅 재추출 및 복구
...

셸 명령줄(shell command line)에 넣기에 텍스트가 너무 긴 경우, ask 명령어, 프롬프트 기반의 generate 명령어, 그리고 source add-research를 사용할 때 --prompt-file PATH를 사용하세요. 이는 파일로부터 프롬프트/쿼리 텍스트를 읽어오며, 해당 파일을 NotebookLM 소스로 업로드하는 source add ./file.pdf와는 별개로 동작합니다.

import asyncio
from notebooklm import NotebookLMClient
async def main():
...

옵션 1 — CLI 설치:

notebooklm skill install

~/.claude/skills/notebooklm 및 ~/.agents/skills/notebooklm에 스킬(skill)을 설치합니다.

옵션 2 — npx 설치 (오픈 스킬 생태계를 통해):

npx skills add teng-lin/notebooklm-py

GitHub에서 공식 SKILL.md를 직접 가져옵니다.

CLI 참조 (CLI Reference) - 전체 명령어 문서
Python API - 전체 API 참조
설정 (Configuration) - 저장소 및 설정
릴리스 가이드 (Release Guide) - 릴리스 체크리스트 및 패키징 검증
문제 해결 (Troubleshooting) - 일반적인 문제 및 해결 방법
API 안정성 (API Stability) - 버전 관리 정책 및 안정성 보장

개발 가이드 (Development Guide) - 아키텍처, 테스트 및 릴리스
RPC 개발 (RPC Development) - 프로토콜 캡처 및 디버깅
RPC 참조 (RPC Reference) - 페이로드(Payload) 구조
변경 이력 (Changelog) - 버전 기록 및 릴리스 노트
보안 (Security) - 보안 정책 및 자격 증명(credential) 처리

플랫폼	상태	비고
macOS	✅ 테스트 완료	주요 개발 플랫폼
Linux	✅ 테스트 완료	전체 지원
Windows	✅ 테스트 완료	CI에서 테스트 완료

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.