NoteWise

NoteWise started with a simple frustration: technical lectures and conference talks are great while watching, but hard to revisit later.

Details like system trade-offs and failure modes get lost in two-hour video streams. Raw transcripts lack formatting, and taking manual notes during a complex talk breaks concentration.

I built NoteWise to turn video content into clear, structured Markdown notes saved directly to your filesystem, typeset across multiple document formats.

¶The six-stage processing pipeline

Processing long technical videos with language models introduces practical challenges around context windows, rate limits, and formatting consistency. NoteWise handles this through a structured compilation pipeline:

¶1. Ingestion and local caching

The CLI takes a single video URL, a full playlist, or a text file of links. It checks the local SQLite database (~/.notewise/notewise.db) first. If the transcript has already been processed, it skips network requests entirely. For new videos, it fetches transcripts and chapter timestamps, supporting cookie files (YOUTUBE_COOKIE_FILE) for age-gated or private materials.

¶2. AST-aware boundary stitching

When a video exceeds prompt limits or lacks native chapters, NoteWise splits the transcript into 4,000-token chunks with 200-token overlaps. Standard text chunkers often split code blocks or sentences mid-thought.

NoteWise implements boundary-aware stitching using _split_tail_for_stitching and _split_head_for_stitching:

• It detects natural markdown headings and closed code blocks before choosing a split point.
• It carries overlap context across generation passes so references and terminology stay continuous.
• It normalizes the combined document, stripping temporary chunk labels (Part 1, Part 2) to produce a single coherent study guide.

¶3. Multi-provider model routing

Through LiteLLM, NoteWise connects to various language model providers without code changes:

• Google Gemini (default gemini/gemini-2.5-flash), Anthropic Claude, OpenAI, Groq, Mistral, DeepSeek, and local endpoints like Ollama or llama.cpp.
• Built-in OAuth device login flows for ChatGPT (chatgpt/gpt-5.2) and GitHub Copilot (github_copilot/gpt-5-mini), allowing users to run jobs without managing API keys.
• Automated rate limiting with exponential backoff and jitter (--throttle) to handle large batch playlists overnight without hitting provider quotas.

¶4. Multi-format rendering

Markdown is treated as the source of truth. From that single output, NoteWise can compile multiple formats in one run:

• .md: clean, portable markdown for Obsidian, Logseq, or Git repositories.
• .html: self-contained browser document with styling and navigation.
• .pdf: typeset document suitable for printing or tablet reading.
• .docx: formatted Microsoft Word file for sharing with non-developers.
• .txt and .json: raw transcripts and timestamped segments for downstream search scripts.

¶Practical CLI workflows

A terminal utility needs to be easy to run and integrate into everyday habits:

• notewise process "URL" --format md,pdf,docx: single command that processes a lecture and outputs three document types simultaneously.
• notewise process playlist-url -o ./course: queues an entire course syllabus for unattended batch processing.
• --chapter-directory-output: writes each video chapter as an individual file inside a structured directory rather than one large document.
• --quiz: automatically generates active-recall review questions and answers alongside the primary notes.
• notewise doctor and notewise setup: checks environment dependencies, API keys, and local SQLite database health.

¶Why it stayed

NoteWise is available on PyPI (uv tool install notewise or pip install notewise) with documentation hosted at docs.notewise.click.

Building it for my own study routine helped keep the tool focused on what matters: clean text, reliable local storage, and predictable CLI behavior that fits inside shell scripts and cron jobs.