notebooklm-chunker 0.1.0

Turn long PDFs into chunked NotebookLM workflows with Studio outputs

notebooklm-chunker

Uploading one large PDF to NotebookLM usually gives weak Studio outputs. Reports, slide decks, quizzes, and similar artifacts stay short and generic because they are generated from one oversized context.

notebooklm-chunker solves that by splitting a long document into smaller, heading-aware chunks, uploading each chunk as a separate NotebookLM source, and then running the Studio outputs you choose. The result is closer to an interactive learning kit than a single uploaded PDF.

Demo

This repository ships with a full demo built around the freely downloadable InfoQ mini-book Domain-Driven Design Quickly.

Demo command:

nblm run --config ./examples/workflows/ddd-quickly-demo.toml

Demo files:

• Workflow file: ./examples/workflows/ddd-quickly-demo.toml
• Source PDF: ./examples/ddd-quickly.pdf

What you get:

• NotebookLM is ready with your chunked PDF sources and configured Studio (report and slide in this case) outputs
• Markdown chunks under ./examples/workflows/output/ddd-quickly/chunks
• One report per chunk under ./examples/workflows/output/ddd-quickly/reports
• One slide deck per chunk under ./examples/workflows/output/ddd-quickly/slides

Requirements

• Python 3.12+
• pip
• A NotebookLM account
• The same Python interpreter for install and Playwright setup

This project automates NotebookLM through notebooklm-py, which is an unofficial community library.

For local development and contribution flow, see DEVELOPMENT.md.

Installation

From PyPI, once the package is published:

pip install "notebooklm-chunker[full]"
python -m playwright install chromium
nblm doctor
nblm login

From a local checkout:

python -m pip install "/ABS/PATH/notebooklm-chunker[full]"
python -m playwright install chromium
nblm doctor
nblm login

To clear local notebooklm-py auth state later:

nblm logout

Quick Start

Create a starter workflow:

nblm init

Check auth, config, Playwright, and PDF parser readiness:

nblm doctor --config ./nblm.toml

Run the whole flow:

nblm run --config ./nblm.toml

Continue later from the saved run state:

nblm resume --config ./nblm.toml

source.path lives in the config file, so you do not need to pass the input document as a CLI argument.

Run State And Resume

nblm run always starts a fresh run and writes a state file next to the chunk output:

./output/chunks/.nblm-run-state.json

That file tracks every chunk separately:

• whether its NotebookLM source upload is still pending, uploaded, or failed
• whether each Studio job for that chunk is pending, completed, or failed
• the source_id, task_id, artifact_id, output path, and last error when available

Example shape:

{
  "chunks": {
    "001-intro.md": {
      "source": {
        "status": "uploaded",
        "source_id": "src-001-intro"
      },
      "studios": {
        "report": {
          "status": "completed",
          "artifact_id": "art-report-1"
        },
        "slide_deck": {
          "status": "pending",
          "task_id": "art-slide-deck-1"
        }
      }
    }
  }
}

This is why nblm resume can continue hours or days later after quotas reset: it does not guess what happened, it reads the saved job state and continues only the unfinished source or Studio jobs.

If you want to inspect progress manually, open .nblm-run-state.json.

Source uploads and per-chunk Studio jobs run as separate queues. That means new source uploads can keep moving while earlier reports, slide decks, or other Studio jobs are still running.

Resume After Quotas

NotebookLM usage limits and quotas depend on your plan. Google documents those limits here:

• NotebookLM usage limits and upgrades

That matters for long books. If your quota fills up in the middle of a run, you can stop, wait for the quota window to reset, and then run:

nblm resume --config ./nblm.toml

Because nblm persists source and Studio job state separately, it can continue from where it left off instead of redoing the whole notebook. NotebookLM's help page also notes that daily quotas reset after 24 hours.

Workflow File

This is the practical full workflow shape:

[source]
path = "./your-document.pdf"
# PDF only. Inclusive page ranges to skip.
# skip_ranges = ["1-8", "399-420", "512"]

[notebook]
title = "Interactive Learning Notebook"
# id = "nb_..."

[chunking]
output_dir = "./output/chunks"
target_pages = 3.0
min_pages = 2.5
max_pages = 4.0
words_per_page = 500

[runtime]
max_parallel_chunks = 3
max_parallel_heavy_studios = 1
studio_wait_timeout_seconds = 7200
studio_create_retries = 5
studio_create_backoff_seconds = 5.0
studio_rate_limit_cooldown_seconds = 30.0
rename_remote_titles = false

[studios.report]
enabled = true
per_chunk = true
max_parallel = 3
output_dir = "./output/reports"
language = "en"
format = "study-guide"
prompt = """
Write a study-guide style report for this chunk.
Explain the main ideas, terminology, and design tradeoffs.
"""

[studios.slide_deck]
enabled = true
per_chunk = true
max_parallel = 3
output_dir = "./output/slides"
language = "en"
format = "detailed"
length = "default"
download_format = "pdf"
prompt = """
Build a teaching deck for this chunk.
Keep the section order and make each slide carry one clear idea.
"""

Studio Parameters

Common fields:

Field	Meaning
enabled	Turn the Studio on or off.
per_chunk	Generate one output per chunk instead of one output for the whole notebook.
max_parallel	Override generic concurrency for this Studio type.
prompt	Extra instructions for NotebookLM. Use TOML multiline strings for anything non-trivial.
output_path	Single output file. Best for notebook-level generation.
output_dir	Output directory for per_chunk = true.
language	Output language when supported.

Per-Studio options:

Studio	Extra fields	Defaults
audio	format, length	deep-dive, long
video	format, style	explainer, whiteboard
report	format	study-guide
slide_deck	format, length, download_format	detailed, default, pdf
quiz	quantity, difficulty, download_format	more, hard, json
flashcards	quantity, difficulty, download_format	more, hard, markdown
infographic	orientation, detail	portrait, detailed
data_table	language, prompt	en, built-in comparison prompt
mind_map	output_path	JSON output path

Notes:

• For report, format = "custom" sends prompt as the main custom report prompt.
• For built-in report formats, prompt is appended as extra instructions.
• mind_map currently has no custom prompt surface in notebooklm-py.

Technical Notes

Heading-Aware Chunking

• chunks start and end on heading boundaries when possible
• chunk size targets target_pages while trying to stay inside min_pages and max_pages
• local chunk filenames come from the first or nearest heading, including leading numbers

PDF Cleanup

• skip_ranges lets you remove contents, foreword, references, appendix, or index pages
• ranges are inclusive, for example: ["1-8", "399-420", "512"]

Parallelism And Quotas

• max_parallel_chunks controls how many source uploads run at once
• per-chunk Studio jobs run on their own queues after each source upload finishes
• max_parallel_heavy_studios is the generic fallback for heavier Studio types such as audio, video, slide_deck, and infographic
• studios.<name>.max_parallel overrides that fallback per Studio type
• good starting point for long books: max_parallel_chunks = 3
• values like 5 can hit NotebookLM quota or rate-limit errors faster

Retry And Backoff

• failed NotebookLM CREATE_ARTIFACT calls retry automatically
• quota or rate-limit errors trigger a shared cooldown before more Studio create requests are sent
• tune this with:
  • runtime.studio_create_retries
  • runtime.studio_create_backoff_seconds
  • runtime.studio_rate_limit_cooldown_seconds

Optional NotebookLM Renaming

• by default, NotebookLM keeps its own auto-generated source and artifact titles
• set runtime.rename_remote_titles = true if you want NotebookLM titles to follow chunk headings
• tradeoff: the related Studio type becomes more serialized so renames stay correct

Examples

Start from the general end-to-end workflows first. Use the partial prepare examples only when you want to inspect chunking before any live NotebookLM run.

DDD Quickly Demo

nblm run --config ./examples/workflows/ddd-quickly-demo.toml

Full Learning Kit

nblm run --config ./examples/workflows/learning-kit.toml

Per-Chunk Report + Slide Deck

nblm run --config ./examples/workflows/per-chunk-report-and-slides.toml

Single-Studio Workflows

NotebookLM Studio is NotebookLM's built-in generation layer: Audio Overview, Video Overview, Report, Slide Deck, Quiz, Flashcards, Infographic, Data Table, and Mind Map.

Single-Studio end-to-end examples live under:

./examples/workflows/studios/

Run one of them with:

nblm run --config ./examples/workflows/studios/audio.toml

Chunking Only

PDF:

nblm prepare --config ./examples/workflows/pdf.toml

Markdown:

nblm prepare --config ./examples/workflows/markdown.toml

Commands

nblm --help:

usage: nblm [-h]
            {login,logout,doctor,init,prepare,upload,studios,run,resume} ...

Split long documents into NotebookLM-ready chunks and optionally generate
Studio outputs.

positional arguments:
  {login,logout,doctor,init,prepare,upload,studios,run,resume}
    login               Run `notebooklm login` for notebooklm-py authentication.
    logout              Clear notebooklm-py local authentication state from disk.
    doctor              Check config discovery, auth, Playwright, PDF parser, and notebooklm CLI readiness.
    init                Write a workflow config file with chunking and Studio settings.
    prepare             Parse a document and export Markdown chunks.
    upload              Upload existing chunks to NotebookLM.
    studios             Generate enabled Studio outputs for an existing notebook.
    run                 Prepare a document, create a fresh notebook run, then generate enabled Studio outputs.
    resume              Continue a previous run from `.nblm-run-state.json` and finish pending uploads or Studio jobs.