Notebooklm Studio

NotebookLM Studio

Import sources into NotebookLM, generate user-selected artifacts via CLI, download results locally.

Inputs

Collect from user message (ask only for missing fields):

• Sources: URLs, YouTube links, text notes, or file attachments (PDF, Word, audio, image, Google Drive link)
• Artifacts: User selects from 9 types (no default — always ask):
  • audio (podcast), video, report, quiz, flashcards, mind-map, slide-deck, infographic, data-table
• Language (optional, default: zh_Hant): applied via notebooklm language set
  • ⚠️ This is a GLOBAL setting — affects all notebooks in the account
• Artifact options (discussed in step 1b): format, style, length, difficulty, etc. See references/artifact-options.md for all options per artifact type.
• Custom instructions (optional): passed as description to generate commands
• Telegram target (optional, OpenClaw only): chat_id for delivery

See references/source-types.md for source type detection rules. See references/artifacts.md for all 9 artifact types and CLI options.

Workflow

Steps are sequential gates — do NOT skip or combine steps. Each numbered step must complete before the next begins. In particular:

• Step 0 (auth precheck) must run and pass before any other CLI command.
• Step 1b (options discussion) must get user confirmation before generation. Do not assume defaults unless the user explicitly says "use defaults."

⚠️ Concurrency: This skill does NOT support concurrent execution on the same NotebookLM account. The CLI uses global state (notebooklm use, language set) that will conflict if two agents run simultaneously.

0. Auth precheck — Verify the session is valid before doing any work:

   notebooklm auth check --test --json
   

   • "status": "ok" → proceed to step 1.
   • "status": "error" → stop immediately. Tell the user:

     NotebookLM 登入已過期，請先重新登入（notebooklm login），完成後告訴我，我再繼續。

   • Command itself fails (network error, CLI not found, etc.) → also stop and report the error.
   • --test is required — without it, only local checks run, which can pass even with an expired session.
   • When the user confirms re-login, re-run this check before continuing.

1. Parse input & configure artifacts —

   1a. Select artifacts — Detect source types from user message (URLs, files, text). Confirm which artifacts to generate.

   1b. Discuss options — Before generating, confirm key options for each selected artifact. Refer to references/artifact-options.md for priority levels:

   • ASK options: must ask the user
   • OFFER options: state the default, let user decide whether to change
   • SILENT options: use defaults without asking
   • Options already specified by the user → skip
   • Present all questions in a single message (batch, not one-by-one)

   If user says "use defaults" → skip all questions, proceed with default values immediately.

   Example agent message (audio + video + report + quiz + flashcards + slides + infographic selected):

   Before generating, a few options to confirm:

   • Podcast: deep-dive / brief / critique / debate?
   • Video: explainer / brief / cinematic? (cinematic uses Veo 3, takes 30-40 min)
   • Report: briefing-doc / study-guide / blog-post / custom?
   • Slides: detailed / presenter?
   • Quiz & Flashcards: difficulty medium, quantity standard — adjust?
   • Infographic: style auto, or prefer a specific style (sketch-note, professional, bento-grid...)?
   • Language: zh_Hant, OK?

   Or just say "use defaults" to start immediately.

2. Derive slug — Based on the sources and user message, generate a short kebab-case slug (2-4 words) that captures the core topic. This slug is used for both the notebook name and the output directory.

   • Examples: react-server-components, feynman-technique, taiwan-semiconductor-q4
   • Keep it concise, lowercase, ASCII-only (transliterate non-ASCII if needed)
   • Must match: ^[a-z0-9][a-z0-9-]{0,48}[a-z0-9]$ (no slashes, dots, spaces, or path traversal)
   • If the user provides a topic or title, prefer that as the basis

3. Create notebook —

   notebooklm create "<slug> <YYYYMMDD>"
   # → {"notebook_id": "xyz789", ...}  ← capture notebook_id
   notebooklm use <notebook_id>
   mkdir -p ./output/<slug>
   

4. Set language —

   notebooklm language set <confirmed_language>
   

   Use the language confirmed in step 1b. ⚠️ GLOBAL setting — always set explicitly to avoid residual from previous runs.

5. Add sources — For each source:

   # URL, YouTube, or file path
   notebooklm source add "<url_or_filepath>"
   
   # Google Drive
   notebooklm source add-drive <file_id> "<title>"
   

   For plain text → save to a .txt file first, then source add "./temp_text.txt".

6. Generate artifacts — Two-tier strategy for timeout safety:

   ⚠️ Deduplication gate (Tier 2 only) — Before generating Tier 2 artifacts, call artifact list once and check all requested types in that single response:

   notebooklm artifact list --json
   # → [{"task_id": "abc123", "type": "slide-deck", "status": "processing"}, ...]
   

   For each Tier 2 artifact you are about to generate, look for entries where type matches (e.g., slide-deck, audio, video). If multiple entries match the same type, the non-terminal status takes priority (processing/pending > completed > failed):

   • processing / pending → do NOT generate again. Take the existing task_id, go to step 9 (wait + deliver).
   • completed → do NOT generate again. Skip the wait — go directly to download + deliver in step 9.
   • failed → safe to re-generate.
   • No matching entry → proceed with generation.

   If artifact list itself fails or returns an error, proceed with generation — the dedup check is a safety net, not a hard gate. Duplicate generation wastes resources and causes confusion — this gate prevents the most common operational error.

   Tier 1 — Immediate (use --wait, completes within timeout):

   # Sync (instant)
   notebooklm generate mind-map
   
   # Fast async (1-2 min) — use options confirmed in step 1b
   notebooklm generate report --format <chosen_format> --wait
   notebooklm generate quiz --difficulty <chosen_difficulty> --quantity <chosen_quantity> --wait
   notebooklm generate flashcards --difficulty <chosen_difficulty> --quantity <chosen_quantity> --wait
   notebooklm generate data-table "<description>" --wait
   
   # Medium async (2-5 min)
   notebooklm generate infographic --style <chosen_style> --orientation <chosen_orientation> --wait
   

   Tier 2 — Deferred (use --json without --wait, capture task_id for step 9):

   # Slow async — use options confirmed in step 1b
   # Parse JSON output to extract task_id for polling
   notebooklm generate slide-deck --format <chosen_format> --json
   # → {"task_id": "abc123", "status": "pending"}  ← save task_id
   
   notebooklm generate video --format <chosen_format> --style <chosen_style> --json
   # → {"task_id": "def456", "status": "pending"}  ← save task_id
   # Note: if cinematic, omit --style (ignored by Veo 3)
   
   notebooklm generate audio "<description>" --format <chosen_format> --length <chosen_length> --json
   # → {"task_id": "ghi789", "status": "pending"}  ← save task_id
   

   Options accepted as defaults in step 1b can be omitted (CLI uses its own defaults). Parse each JSON response and save the task_id — you will need it in step 9. Only generate the artifacts the user requested. Skip the rest. See references/artifacts.md → "Deferred Generation" for Tier 2 details.

   Write delivery status — Immediately after all Tier 2 generates are dispatched, write ./output/<slug>/delivery-status.json so the recovery script can pick up if the agent times out:

   {
     "slug": "<slug>",
     "notebook_id": "<notebook_id>",
     "created_at": "<ISO 8601>",
     "artifacts": [
       {"type": "report", "task_id": null, "status": "delivered", "output_path": "./output/<slug>/report.md"},
       {"type": "slide-deck", "task_id": "<id>", "status": "pending", "output_path": "./output/<slug>/slides.pdf"},
       {"type": "audio", "task_id": "<id>", "status": "pending", "output_path": "./output/<slug>/podcast.mp3"}
     ]
   }
   

   Include all requested artifacts (both Tier 1 and Tier 2). Tier 1 artifacts start as delivered (already sent). Update Tier 2 status as step 9 progresses: pending → completed (downloaded) → delivered (sent to Telegram), or failed on error. This file is the handoff contract between the agent and scripts/recover_tier2_delivery.sh. Telegram delivery is agent-only (requires OpenClaw message tool); the recovery script handles download + status tracking only.

7. Download Tier 1 — Each successful Tier 1 artifact into ./output/<slug>/:

   notebooklm download mind-map ./output/<slug>/mindmap.json
   notebooklm download report ./output/<slug>/report.md
   notebooklm download quiz --format json ./output/<slug>/quiz.json
   notebooklm download flashcards --format json ./output/<slug>/flashcards.json
   notebooklm download data-table ./output/<slug>/data.csv
   notebooklm download infographic ./output/<slug>/infographic.png
   

8. Report + Deliver Tier 1 — Present completed Tier 1 artifacts to user. If Tier 2 artifacts are pending, include a status note:

   "Slides/Audio/Video are still generating, I'll send them when ready."

   Telegram delivery (OpenClaw only) — If message tool is available:

   1. Text summary with Tier 2 pending status (always first)
   2. Report → Quiz → Flashcards → Mind Map → Infographic → Data Table

   See references/telegram-delivery.md for delivery contract. Skip Telegram delivery if running outside OpenClaw (e.g. Claude Code, Codex).

9. Poll + Deliver Tier 2 — Wait for each deferred artifact in order of expected speed (fastest first), then download and deliver as each completes:

   # Wait by expected completion order: slide-deck (fastest) → video → audio (slowest)
   # Uses --interval 5 (not default 2) since Tier 2 artifacts take minutes, not seconds
   notebooklm artifact wait <slide_task_id> --timeout 1800 --interval 5 --json
   # → {"status": "completed", ...}  ← task_id from generate is used as artifact_id here
   notebooklm download slide-deck ./output/<slug>/slides.pdf
   # → deliver to Telegram immediately
   
   notebooklm artifact wait <video_task_id> --timeout 1800 --interval 5 --json
   # Note: if cinematic, use --timeout 2400 (generation takes 30-40 min)
   notebooklm download video ./output/<slug>/video.mp4
   # → deliver to Telegram immediately
   
   notebooklm artifact wait <audio_task_id> --timeout 1800 --interval 5 --json
   notebooklm download audio ./output/<slug>/podcast.mp3
   bash scripts/compress_audio.sh ./output/<slug>/podcast.mp3 ./output/<slug>/podcast_compressed.mp3
   # → deliver to Telegram immediately
   

   • Order matters: wait for fastest artifact first (slide-deck → video → audio) to minimize idle time
   • On completion: download → post-process → deliver to Telegram → update delivery-status.json status to delivered
   • On failure: update status to failed with reason, notify user, continue to next artifact
   • On timeout: see timeout recovery below
   • Max wait: 30 minutes per artifact (covers worst-case audio/video)
   • If agent is about to exit with any artifact still pending, tell the user:

     "Tier 2 補送模式已啟動，recovery script 會每 5 分鐘檢查並自動送達。"

   ⚠️ Timeout recovery — If artifact wait returns status: "timeout", the artifact is likely still generating. NEVER re-generate. Instead:

   1. Re-check status: notebooklm artifact poll <task_id> --json
   2. If processing → re-wait: notebooklm artifact wait <task_id> --timeout 1800 --interval 5 --json
   3. If completed → download and deliver
   4. If failed → notify user with error, move to next artifact
   5. If re-wait also times out (2+ total timeouts, ~60 min elapsed) → give up, notify user, suggest downloading from NotebookLM directly A timeout means the wait expired, not that generation failed. The task continues server-side. Re-generating creates duplicates and wastes time.

Error handling

• Auth errors → caught by step 0 precheck. If any CLI command later returns an authentication/session error (HTTP 401, "Not logged in", "session expired", token fetch failure), treat it as a mid-workflow auth failure — stop, ask user to re-login, then re-run step 0 before resuming.
• Tier 1 failure: retry up to 2 times (3 total attempts), then include failure note in step 8 delivery.
• Tier 2 failure: notify user per-artifact in step 9. Tier 1 is already delivered by this point, so Tier 2 failures never block text artifact delivery.
• All sources failed (step 5): if every source add fails, stop immediately — generation without sources is meaningless. Report the failures and ask user to check sources.
• Notebook creation failed (step 3): if notebooklm create fails (API error, rate limit), stop and report. Do not proceed without a valid notebook_id.
• delivery-status.json write failure (step 6): if writing the JSON file fails, log a warning and continue — Tier 2 artifacts are already dispatched. The agent can still poll and deliver, but cron recovery will not be available.
• Audio still > 50MB after compression (step 9): if compress_audio.sh output exceeds 50MB, warn user and provide the local file path instead of attempting Telegram delivery. Suggest downloading from NotebookLM directly.
• Capture failure reason in delivery status.

Delivery confirmation gate

Before reporting "complete" to the user, ALL of the following must be true:

1. Every requested artifact is either successfully delivered or reported as failed with reason
2. For Telegram delivery (OpenClaw): each message tool call (OpenClaw's built-in messaging tool) returned a success response with a messageId
   • If a send fails, retry once. If still failing, report the failure to the user — do NOT silently skip
3. No artifact is still in processing or pending status without being tracked

Never say "done" while any artifact is still pending delivery. If Tier 2 artifacts are still generating, say so explicitly and continue waiting. The task is not complete until everything is delivered or accounted for.

Quality gate

Before delivery, verify:

• Sources are concrete article/content pages (not category/index pages).
• Report contains actionable takeaways (not generic summary).
• Quiz tests key concepts and mechanics.
• Flashcards focus on terms, decisions, and trade-offs.
• Output respects requested language and length.

See references/output-contracts.md for format specifications.

Delivery template

1. Selection rationale (<=3 bullets)
2. Artifact list with paths/status (all 9 types if applicable)
3. Key takeaways (3-5 bullets)
4. Failures + fallback note (if any)
5. One discussion question

Changelog

v2.1.3

• Schema unification — delivery-status.json now uses a single schema across SKILL.md, telegram-delivery.md, and recovery script. Eliminates conflicting flat vs structured formats.
• Recovery cooldown — cron script skips artifacts younger than 30 minutes (RECOVERY_COOLDOWN_MIN), preventing agent/cron race conditions.
• Concurrency guard — explicit warning that concurrent execution on the same account is unsupported (CLI global state conflicts).
• Infographic fixed Tier 1 — removed ambiguous "borderline" classification; infographic is now unambiguously Tier 1.
• Critical error handling — added 5 rules for previously silent failures: all-sources-failed, notebook-create-failed, delivery-json-write-failure, audio-over-50MB, and retry count clarification.
• Slug validation — regex ^[a-z0-9][a-z0-9-]{0,48}[a-z0-9]$ prevents path traversal and command injection.
• Recovery logging — ISO 8601 timestamps on all recovery script output.

v2.1.0

• Auth precheck gate — step 0 runs auth check --test --json before any work; expired sessions fail fast instead of blowing up mid-generation.
• Dedup gate — step 6 checks artifact list before Tier 2 generation to prevent duplicate artifacts when agent retries or resumes.
• Timeout recovery — artifact wait timeout no longer triggers re-generation; polls status and re-waits, giving up only after 2 consecutive timeouts (~60 min).
• Delivery confirmation gate — agent cannot claim "done" until every artifact is delivered or explicitly reported as failed with reason.
• Delivery status contract — step 6 writes delivery-status.json after Tier 2 dispatch; step 9 updates it as artifacts complete. Enables cron-based recovery via scripts/recover_tier2_delivery.sh when agent times out.