Merge pull request teng-lin#198 from teng-lin/release/v0.3.4

chore: release v0.3.4

Author: teng-lin

.github/workflows/test.yml

@@ -28,11 +28,8 @@ jobs:
         python -m pip install --upgrade pip
         pip install -e ".[all]"
 
-    - name: Run linting
-      run: ruff check src/ tests/
-
-    - name: Check formatting
-      run: ruff format --check src/ tests/
+    - name: Run pre-commit checks
+      run: pre-commit run --all-files
 
     - name: Run type checking
       run: mypy src/notebooklm --ignore-missing-imports

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-03-12
+
+### Added
+- **Notebook metadata export** - Added notebook metadata APIs and CLI export with a simplified sources list
+  - New `notebooklm metadata` command with human-readable and `--json` output
+  - New `NotebookMetadata` and `SourceSummary` public types
+  - New `client.notebooks.get_metadata()` helper
+- **Cinematic Video Overview support** - Added cinematic generation and download flows
+  - `notebooklm generate video --format cinematic`
+- **Infographic styles** - Added CLI support for selecting infographic visual styles
+- **`source delete-by-title`** - Added explicit exact-title deletion command for sources
+
+### Fixed
+- **Research imports on timeout** - CLI research imports now retry on timeout with backoff
+- **Metadata command behavior** - Aligned metadata output and implementation with current CLI patterns
+- **Regional login cookies** - Improved browser login handling for regional Google domains
+- **Notebook summary parsing** - Fixed notebook summary response parsing
+- **Source delete UX** - Improved source delete resolution, ambiguity handling, and title-vs-ID errors
+- **Empty downloads** - Raise an error instead of producing zero-byte files
+- **Module execution** - Added `python -m notebooklm` support
+
+### Changed
+- **Documentation refresh** - Updated release, development, CLI, README, and Python API docs for current commands, APIs, and `uv` workflows
+- **Public API surface** - Exported `NotebookMetadata`, `SourceSummary`, and `InfographicStyle`
+
 ## [0.3.3] - 2026-03-03
 
 ### Added
@@ -319,7 +344,8 @@ This is the initial public release of `notebooklm-py`. While core functionality
 - **Authentication expiry**: CSRF tokens expire after some time. Re-run `notebooklm login` if you encounter auth errors.
 - **Large file uploads**: Files over 50MB may fail or timeout. Split large documents if needed.
 
-[Unreleased]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/teng-lin/notebooklm-py/compare/v0.3.0...v0.3.1

README.md

@@ -60,7 +60,7 @@
 | Type | Options | Download Format |
 |------|---------|-----------------|
 | **Audio Overview** | 4 formats (deep-dive, brief, critique, debate), 3 lengths, 50+ languages | MP3/MP4 |
-| **Video Overview** | 2 formats, 9 visual styles (classic, whiteboard, kawaii, anime, etc.) | MP4 |
+| **Video Overview** | 3 formats (explainer, brief, cinematic), 9 visual styles, plus a dedicated `cinematic-video` CLI alias | MP4 |
 | **Slide Deck** | Detailed or presenter format, adjustable length; individual slide revision | PDF, PPTX |
 | **Infographic** | 3 orientations, 3 detail levels | PNG |
 | **Quiz** | Configurable quantity and difficulty | JSON, Markdown, HTML |
@@ -131,6 +131,7 @@ notebooklm ask "What are the key themes?"
 # 4. Generate content
 notebooklm generate audio "make it engaging" --wait
 notebooklm generate video --style whiteboard --wait
+notebooklm generate cinematic-video "documentary-style summary" --wait
 notebooklm generate quiz --difficulty hard
 notebooklm generate flashcards --quantity more
 notebooklm generate slide-deck
@@ -141,6 +142,7 @@ notebooklm generate data-table "compare key concepts"
 # 5. Download artifacts
 notebooklm download audio ./podcast.mp3
 notebooklm download video ./overview.mp4
+notebooklm download cinematic-video ./documentary.mp4
 notebooklm download quiz --format markdown ./quiz.md
 notebooklm download flashcards --format json ./cards.json
 notebooklm download slide-deck ./slides.pdf
@@ -149,6 +151,17 @@ notebooklm download mind-map ./mindmap.json
 notebooklm download data-table ./data.csv
 ```
 
+Other useful CLI commands:
+
+```bash
+notebooklm auth check --test         # Diagnose auth/cookie issues
+notebooklm language list             # List supported output languages
+notebooklm metadata --json           # Export notebook metadata and sources
+notebooklm share status              # Inspect sharing state
+notebooklm source add-research "AI"  # Start web research and import sources
+notebooklm skill status              # Check Claude Code skill installation
+```
+
 ### Python API
 
 ```python
@@ -199,6 +212,7 @@ notebooklm skill install
 - **[CLI Reference](docs/cli-reference.md)** - Complete command documentation
 - **[Python API](docs/python-api.md)** - Full API reference
 - **[Configuration](docs/configuration.md)** - Storage and settings
+- **[Release Guide](docs/releasing.md)** - Release checklist and packaging verification
 - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
 - **[API Stability](docs/stability.md)** - Versioning policy and stability guarantees
 

docs/cli-reference.md

@@ -1,7 +1,7 @@
 # CLI Reference
 
 **Status:** Active
-**Last Updated:** 2026-03-02
+**Last Updated:** 2026-03-12
 
 Complete command reference for the `notebooklm` CLI—providing full programmatic access to all NotebookLM features, including capabilities not exposed in the web UI.
 
@@ -27,7 +27,8 @@ See [Configuration](configuration.md) for details on environment variables and C
 - **Session commands** - Authentication and context management
 - **Notebook commands** - CRUD operations on notebooks
 - **Chat commands** - Querying and conversation management
-- **Grouped commands** - `source`, `artifact`, `generate`, `download`, `note`
+- **Grouped commands** - `source`, `artifact`, `generate`, `download`, `note`, `share`, `research`, `language`, `skill`, `auth`
+- **Utility commands** - `metadata`
 
 ---
 
@@ -67,7 +68,6 @@ See [Configuration](configuration.md) for details on environment variables and C
 | `create <title>` | Create notebook | `notebooklm create "Research"` |
 | `delete <id>` | Delete notebook | `notebooklm delete abc123` |
 | `rename <title>` | Rename current notebook | `notebooklm rename "New Title"` |
-| `share` | Toggle notebook sharing | `notebooklm share` or `notebooklm share --revoke` |
 | `summary` | Get AI summary | `notebooklm summary` |
 
 ### Chat Commands
@@ -125,7 +125,8 @@ All generate commands support:
 | Command | Options | Example |
 |---------|---------|---------|
 | `audio [description]` | `--format [deep-dive\|brief\|critique\|debate]`, `--length [short\|default\|long]`, `--wait` | `generate audio "Focus on history"` |
-| `video [description]` | `--format [explainer\|brief]`, `--style [auto\|classic\|whiteboard\|kawaii\|anime\|watercolor\|retro-print\|heritage\|paper-craft]`, `--wait` | `generate video "Explainer for kids"` |
+| `video [description]` | `--format [explainer\|brief\|cinematic]`, `--style [auto\|classic\|whiteboard\|kawaii\|anime\|watercolor\|retro-print\|heritage\|paper-craft]`, `--wait` | `generate video "Explainer for kids"` |
+| `cinematic-video [description]` | Alias for `video --format cinematic`; supports the same options | `generate cinematic-video "Documentary about quantum physics"` |
 | `slide-deck [description]` | `--format [detailed\|presenter]`, `--length [default\|short]`, `--wait` | `generate slide-deck` |
 | `revise-slide <description>` | `-a/--artifact <id>` (required), `--slide N` (required), `--wait` | `generate revise-slide "Move title up" --artifact <id> --slide 0` |
 | `quiz [description]` | `--difficulty [easy\|medium\|hard]`, `--quantity [fewer\|standard\|more]`, `--wait` | `generate quiz --difficulty hard` |
@@ -154,6 +155,7 @@ All generate commands support:
 |---------|-----------|---------|---------|
 | `audio [path]` | Output path | `-a/--artifact`, `--all`, `--latest`, `--name`, `--force`, `--dry-run` | `download audio --all` |
 | `video [path]` | Output path | `-a/--artifact`, `--all`, `--latest`, `--name`, `--force`, `--dry-run` | `download video --latest` |
+| `cinematic-video [path]` | Output path | Alias for `download video`; same options as `video` | `download cinematic-video ./documentary.mp4` |
 | `slide-deck [path]` | Output path      | `-a/--artifact`, `--all`, `--latest`, `--name`, `--force`, `--dry-run`, `--format [pdf\|pptx]` | `download slide-deck ./slides.pdf` |
 | `infographic [path]` | Output path | `-a/--artifact`, `--all`, `--latest`, `--name`, `--force`, `--dry-run` | `download infographic ./info.png` |
 | `report [path]` | Output path | `-a/--artifact`, `--all`, `--latest`, `--name`, `--force`, `--dry-run` | `download report ./report.md` |
@@ -169,10 +171,28 @@ All generate commands support:
 | `list` | - | - | `note list` |
 | `create <content>` | Note content | - | `note create "My notes..."` |
 | `get <id>` | Note ID | - | `note get note123` |
-| `save <id>` | Note ID | - | `note save note123` |
+| `save <id>` | Note ID | `--title`, `--content` | `note save note123 --title "Updated title"` |
 | `rename <id> <title>` | Note ID, title | - | `note rename note123 "Title"` |
 | `delete <id>` | Note ID | - | `note delete note123` |
 
+### Metadata Command
+
+Export notebook metadata and a simplified source list.
+
+```bash
+notebooklm metadata [OPTIONS]
+```
+
+**Options:**
+- `-n, --notebook ID` - Specify notebook (uses current if not set)
+- `--json` - Output as JSON for scripts
+
+**Examples:**
+```bash
+notebooklm metadata
+notebooklm metadata -n abc123 --json
+```
+
 ### Skill Commands (`notebooklm skill <cmd>`)
 
 Manage Claude Code skill integration.
@@ -781,7 +801,7 @@ notebooklm summary
 # 4. Generate study materials
 notebooklm generate quiz --difficulty hard --wait
 notebooklm generate flashcards --wait
-notebooklm generate report --type study-guide --wait
+notebooklm generate report --format study-guide --wait
 
 # 5. Ask specific questions
 notebooklm ask "Explain the key concepts in chapter 3"
@@ -806,7 +826,7 @@ notebooklm ask "What are the main points?"
 notebooklm ask "Create bullet point notes"
 
 # 4. Generate a quick briefing doc
-notebooklm generate report --type briefing-doc --wait
+notebooklm generate report --format briefing-doc --wait
 ```
 
 ### Bulk Import

docs/development.md

@@ -1,7 +1,7 @@
 # Contributing Guide
 
 **Status:** Active
-**Last Updated:** 2026-01-21
+**Last Updated:** 2026-03-12
 
 This guide covers everything you need to contribute to `notebooklm-py`: architecture overview, testing, and releasing.
 
@@ -107,9 +107,12 @@ src/notebooklm/
 
 1. **Install dependencies:**
    ```bash
-   uv pip install -e ".[dev]"
+   uv sync --extra dev --extra browser
+   uv run pre-commit install
    ```
 
+   CI runs the same lint gate with `uv run pre-commit run --all-files`, so local hook results should match the `quality` job.
+
 2. **Authenticate:**
    ```bash
    notebooklm login
@@ -125,12 +128,12 @@ src/notebooklm/
 
 ```bash
 # Unit + integration tests (no auth needed)
-pytest
+uv run pytest
 
 # E2E tests (requires auth + test notebook)
-pytest tests/e2e -m readonly        # Read-only tests only
-pytest tests/e2e -m "not variants"  # Skip parameter variants
-pytest tests/e2e --include-variants # All tests including variants
+uv run pytest tests/e2e -m readonly        # Read-only tests only
+uv run pytest tests/e2e -m "not variants"  # Skip parameter variants
+uv run pytest tests/e2e --include-variants # All tests including variants
 ```
 
 ### Test Structure
@@ -159,13 +162,13 @@ VCR tests record HTTP interactions for offline, deterministic replay. We have tw
 
 ```bash
 # Run all VCR tests
-pytest tests/integration/
+uv run pytest tests/integration/
 
 # Run only CLI VCR tests
-pytest tests/integration/cli_vcr/
+uv run pytest tests/integration/cli_vcr/
 
 # Record new cassettes (sensitive data auto-scrubbed)
-NOTEBOOKLM_VCR_RECORD=1 pytest tests/integration/test_vcr_*.py -v
+NOTEBOOKLM_VCR_RECORD=1 uv run pytest tests/integration/test_vcr_*.py -v
 ```
 
 Sensitive data (cookies, tokens, emails) is automatically scrubbed from cassettes.
@@ -181,7 +184,7 @@ Sensitive data (cookies, tokens, emails) is automatically scrubbed from cassette
 ### Rate Limiting
 
 NotebookLM has undocumented rate limits. Generation tests may be skipped when rate limited:
-- Use `pytest tests/e2e -m readonly` for quick validation
+- Use `uv run pytest tests/e2e -m readonly` for quick validation
 - Wait a few minutes between full test runs
 - `SKIPPED (Rate limited by API)` is expected behavior, not failure
 

docs/python-api.md

@@ -1,7 +1,7 @@
 # Python API Reference
 
 **Status:** Active
-**Last Updated:** 2026-03-02
+**Last Updated:** 2026-03-12
 
 Complete reference for the `notebooklm` Python library.
 
@@ -31,8 +31,9 @@ async def main():
 
         # Generate a podcast
         status = await client.artifacts.generate_audio(nb.id)
-        final = await client.artifacts.wait_for_completion(nb.id, status.task_id)
-        print(f"Audio ready: {final.url}")
+        await client.artifacts.wait_for_completion(nb.id, status.task_id)
+        output_path = await client.artifacts.download_audio(nb.id, "podcast.mp3")
+        print(f"Audio saved to: {output_path}")
 
 asyncio.run(main())
 ```
@@ -157,10 +158,15 @@ class NotebookLMClient:
     chat: ChatAPI              # Conversations
     research: ResearchAPI      # Web/Drive research
     notes: NotesAPI            # User notes
+    settings: SettingsAPI      # User settings (language, etc.)
     sharing: SharingAPI        # Notebook sharing
+    auth: AuthTokens           # Current authentication tokens
+    is_connected: bool         # Connection state
 
     @classmethod
-    async def from_storage(cls, path: str = None) -> "NotebookLMClient"
+    async def from_storage(
+        cls, path: str | None = None, timeout: float = 30.0
+    ) -> "NotebookLMClient"
 
     async def refresh_auth(self) -> AuthTokens
 ```
@@ -177,8 +183,10 @@ class NotebookLMClient:
 | `delete(notebook_id)` | `notebook_id: str` | `bool` | Delete a notebook |
 | `rename(notebook_id, new_title)` | `notebook_id: str, new_title: str` | `Notebook` | Rename a notebook |
 | `get_description(notebook_id)` | `notebook_id: str` | `NotebookDescription` | Get AI summary and topics |
+| `get_metadata(notebook_id)` | `notebook_id: str` | `NotebookMetadata` | Get notebook metadata and sources |
 | `get_summary(notebook_id)` | `notebook_id: str` | `str` | Get raw summary text |
-| `share(notebook_id, settings=None)` | `notebook_id: str, settings: dict` | `Any` | Share notebook with settings |
+| `share(notebook_id, public=True, artifact_id=None)` | `notebook_id: str, bool, str \| None` | `dict` | Create or update a share link |
+| `get_share_url(notebook_id, artifact_id=None)` | `notebook_id: str, str \| None` | `str` | Get a share URL |
 | `remove_from_recent(notebook_id)` | `notebook_id: str` | `None` | Remove from recently viewed |
 | `get_raw(notebook_id)` | `notebook_id: str` | `Any` | Get raw API response data |
 
@@ -203,8 +211,14 @@ for topic in desc.suggested_topics:
 summary = await client.notebooks.get_summary(nb.id)
 print(summary)
 
-# Share a notebook
-await client.notebooks.share(nb.id, settings={"public": True})
+# Get metadata for automation or exports
+metadata = await client.notebooks.get_metadata(nb.id)
+print(metadata.title)
+
+# Enable public sharing and fetch the URL
+await client.notebooks.share(nb.id, public=True)
+url = await client.notebooks.get_share_url(nb.id)
+print(url)
 ```
 
 **get_summary vs get_description:**
@@ -440,21 +454,20 @@ status = await client.artifacts.generate_video(
 # Report
 status = await client.artifacts.generate_report(
     notebook_id,
+    report_format=ReportFormat.STUDY_GUIDE,  # BRIEFING_DOC, STUDY_GUIDE, BLOG_POST, CUSTOM
     source_ids=None,
-    title="...",
-    description="...",
-    format=ReportFormat.STUDY_GUIDE,  # BRIEFING_DOC, STUDY_GUIDE, BLOG_POST, CUSTOM
-    language="en"
+    language="en",
+    custom_prompt=None,          # Used with ReportFormat.CUSTOM
+    extra_instructions="..."     # Optional append for built-in formats
 )
 
 # Quiz
 status = await client.artifacts.generate_quiz(
     notebook_id,
     source_ids=None,
     instructions="...",
-    quantity=QuizQuantity.STANDARD,    # FEWER, STANDARD
+    quantity=QuizQuantity.MORE,        # FEWER, STANDARD, MORE (MORE aliases STANDARD)
     difficulty=QuizDifficulty.MEDIUM,  # EASY, MEDIUM, HARD
-    language="en"
 )
 ```
 
@@ -473,7 +486,8 @@ final = await client.artifacts.wait_for_completion(
 )
 
 if final.is_complete:
-    print(f"Download URL: {final.url}")
+    path = await client.artifacts.download_audio(nb_id, "podcast.mp3")
+    print(f"Saved to: {path}")
 else:
     print(f"Failed or timed out: {final.status}")
 ```
@@ -966,6 +980,7 @@ class VideoStyle(Enum):
 class QuizQuantity(Enum):
     FEWER = 1
     STANDARD = 2
+    MORE = 2  # Alias of STANDARD used by the CLI/web UI
 
 class QuizDifficulty(Enum):
     EASY = 1
@@ -1050,6 +1065,8 @@ class SourceType(str, Enum):
     PDF = "pdf"
     PASTED_TEXT = "pasted_text"
     WEB_PAGE = "web_page"
+    GOOGLE_DRIVE_AUDIO = "google_drive_audio"
+    GOOGLE_DRIVE_VIDEO = "google_drive_video"
     YOUTUBE = "youtube"
     MARKDOWN = "markdown"
     DOCX = "docx"