@jamestesting888/tum-mcp 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changes
 
+## 0.10.0 — 2026-10-27
+
+- Add the optional `video-notes` extension (`tum-mcp install video-notes`): short
+  narrated, animated explainers from prepared Study topics, one per selected topic,
+  under the course's `videos/` folder. The skill plans storyboards from the prepared
+  content only; `tum-mcp video-notes` checks storyboards, measures narration, renders
+  with a pinned Manim/Typst runtime installed on first use, verifies sync, loudness,
+  captions and layout, and publishes with receipts, archives and crash recovery.
+- Play published videos in the local app above each topic's Content, with chapters,
+  captions, a transcript and a notice when the topic changed after the video was made.
+  Hosted study sites never request or include videos.
+- Keep extension selections forward compatible: unknown on/off settings from newer
+  releases are preserved, and the video setting is only written when enabled.
+- Use NVIDIA GPUs for Prepare Lecture recognition on Windows x64 and Linux/WSL x86_64.
+  `auto` selects CUDA for a CUDA 12 GPU of compute capability 7.0+, adds a pinned cuBLAS to
+  the runtime (no CUDA toolkit or cuDNN), checks the GPU during installation and
+  otherwise stays on CPU int8. `TUM_MCP_LECTURE_ENGINE` also accepts `cuda`.
+- Document the eSpeak data path limit that breaks local Kokoro on macOS in Audio Notes.
+- Keep the local course app loading on Windows: the preview server now queues the
+  app's burst of parallel module requests instead of refusing all but five.
+
+## 0.9.5 — 2026-10-27
+
+- Simplify the course project overview wording.
+
 ## 0.9.4 — 2026-10-27
 
 - Document the course project folders, including optional extension outputs.

package/README.md

@@ -51,16 +51,18 @@ Run `tum-mcp install` to choose extensions, then reload your client.
 | `lecture` | `prepare-lecture` | Lecture Notes with the professor's extra explanations, timestamps and selected critical visuals. Prefers transcripts and slides; local recognition is optional. |
 | `studocu` | `sync-studocu` | Search and collect selected supplementary PDFs saved in your browser. Personal use only; excluded from published sites. |
 | `audio-notes` | `audio-notes` | Turn prepared Study lessons into concise audio tracks, with resumable generation and coverage tracking. Voice setup happens when used. |
+| `video-notes` | `video-notes` | Turn prepared Study topics into short narrated, animated explainers that play inside the local app, with checked sync, captions and layout. The render runtime installs when first used. |
 
 Use `tum-mcp doctor` to see installed workflows and `tum-mcp uninstall` to remove
 them.
 
 [Lecture and recognition](docs/lecture-notes.md) ·
-[Studocu collection](docs/study.md#studocu-materials) · [Setup details](docs/setup.md)
+[Studocu collection](docs/study.md#studocu-materials) ·
+[Video Notes](docs/study.md#create-and-maintain-video-notes) · [Setup details](docs/setup.md)
 
 ## Course project
 
-Each course has its own folder. Optional extension files appear when used:
+After initialization, a course project looks something like this:
 
 ```text
 course/
@@ -74,10 +76,9 @@ course/
     lecture-assets/         Optional: selected lecture figures
   .tum-mcp/                 Private course state, comments and lecture evidence
   audio/                    Optional: scripts, tracks and chapters for Audio Notes
+  videos/                   Optional: storyboards, scenes and explainer videos for Video Notes
 ```
 
-Existing projects may use `study/` instead of `app/`.
-
 ## Privacy, updates and removal
 
 Sessions are encrypted locally. Your agent uses your configured AI provider to

package/docs/development.md

@@ -70,6 +70,9 @@ Desktop jobs additionally install the optional hash-locked CPU recognizer and
 transcribe the synthetic speech fixture; supported Apple Silicon runners also
 exercise MLX. This explicit test downloads public pinned model files, never campus
 recordings. Ordinary test runs skip it unless `TUM_MCP_LECTURE_ASR_INTEGRATION=1`.
+Linux and Windows jobs also install the hash-locked CUDA runtime and load its pinned
+cuBLAS the way CTranslate2 does, without a GPU (`TUM_MCP_LECTURE_CUDA_LIBRARIES=1`);
+GPU inference itself runs in the native test only on a host with an NVIDIA GPU.
 Recognition runs before package lifecycle checks to expose native dependency
 failures early. Windows also runs the affected browser/UTF-8 fixture checks first.
 Its complete job budget is 35 minutes for native ACL and subprocess coverage;
@@ -105,7 +108,8 @@ tag and artifact integrity before pushing the release documentation.
 | `src/tum_mcp/credentials.py`, `transport.py`, `settings.py` | Shared campus credential vault, HTTP transport and account policy |
 | `src/tum_mcp/client_*.py` | Host-specific configuration and managed skill installation |
 | `src/tum_mcp/study_*.py` | Course snapshots, teaching, build, preview and project-local passage comments |
-| `src/tum_mcp/bundled/skills/` | Canonical versioned source of reading, study and audio skills and their references/assets |
+| `src/tum_mcp/bundled/skills/` | Canonical versioned source of reading, study, audio and video skills and their references/assets |
+| `src/tum_mcp/video_*.py`, `bundled/video_runtime/` | Video Notes contracts, lint, media checks, orchestration and the isolated render worker |
 | `npm/` | Private-runtime installation, updates, integrity and cleanup |
 | `tests/` | Synthetic backend, package and owned-browser checks |
 
@@ -147,6 +151,21 @@ session reuse. Automated synthetic sign-in does not certify human SSO on every O
 For UI changes, exercise the generated app at narrow/wide widths in both themes;
 check keyboard navigation, reduced motion, source links and retained progress.
 
+## Optional Video Notes runtime
+
+`install video-notes` only selects the workflow. `tum-mcp video-notes runtime install`
+creates a uv venv per lock under the data directory from
+`bundled/video_runtime/requirements.lock` (universal, hash-pinned). Everything is a
+wheel except `pycairo`, `manimpango` and `srt`, which build from hashed sources; the
+locked `pkgconf` wheel is installed first and provides `pkg-config`. Regenerate the
+lock with the command in its header. Helper code (`vnotes/`, `worker.py`, fonts) runs
+from the package, so changing it never reinstalls the runtime; it does change the
+render profile and therefore the chapter cache. Default tests use a fake worker and
+the synthetic media in `tests/fixtures/video/` (`generate.py` recreates them). Set
+`TUM_MCP_VIDEO_RENDER_INTEGRATION=1` to install the real runtime into a temporary
+data directory and render, mix, check and publish a synthetic video; the browser
+playback tests also run WebKit when Playwright's WebKit is installed.
+
 ## Optional Lecture extension
 
 Base setup exposes five workflows and no `tum_live_*` tools. `install lecture`

package/docs/lecture-notes.md

@@ -64,8 +64,9 @@ revision-pinned public model weights; neither is part of the base runtime.
 | Apple Silicon macOS 15+ | MLX acceleration by default |
 | Apple Silicon macOS 14 | CPU int8 |
 | Intel macOS 13+ | CPU int8 |
-| Windows x64 | CPU int8; Microsoft Visual C++ runtime required |
-| Linux/WSL x86_64 or ARM64, glibc 2.28+ | CPU int8 |
+| Windows x64 | NVIDIA CUDA when a GPU is detected, otherwise CPU int8; Microsoft Visual C++ runtime required |
+| Linux/WSL x86_64, glibc 2.28+ | NVIDIA CUDA when a GPU is detected, otherwise CPU int8 |
+| Linux ARM64, glibc 2.28+ | CPU int8 |
 
 Native Windows ARM64, 32-bit systems and musl Linux have no supported locked
 runtime. Use captions/imported WebVTT there. CPU inference requires compatible
@@ -80,9 +81,20 @@ video frames. They are unnecessary for imported captions and cached text.
 `lecture runtime status` reports the selected engine and missing prerequisites.
 Use `lecture runtime install` to retry after fixing a prerequisite. Advanced users
 can set `TUM_MCP_LECTURE_ENGINE=cpu` consistently for installation and preparation
-to bypass Metal; the default `auto` retains existing MLX runtimes and model caches.
+to bypass Metal or CUDA; the default `auto` retains existing MLX runtimes and model caches.
 An engine switch uses separate caches. No cloud transcription API is configured.
 
+On Windows x64 and Linux/WSL x86_64, `auto` uses an NVIDIA GPU of compute capability
+7.0 or newer (GTX 16, RTX 20 series and later) when its driver supports CUDA 12
+(driver 525 or newer); older GPUs stay on CPU. Only the driver is needed: the runtime
+adds a pinned cuBLAS (about 600 MB) and decodes in float16, without a CUDA toolkit
+or cuDNN. Installation first creates a cuBLAS handle on the GPU. If that fails,
+automatic selection records it (`lecture-runtime/cuda-unusable.json` in the data
+directory) and installs the CPU runtime instead, so `tum-mcp update` keeps working.
+After a driver fix, `TUM_MCP_LECTURE_ENGINE=cuda tum-mcp lecture runtime install`
+retries and, on success, clears that record. `cuda` never falls back silently;
+`lecture runtime status` shows when a GPU was declined.
+
 CPU decoding uses int8, one worker and at most four threads. It consumes the full
 retained audio, with word timestamps and no VAD retiming. ASR remains fallible,
 especially for names and notation; compare important wording with slides and the

package/docs/setup.md

@@ -38,6 +38,15 @@ Audio Notes is optional: use `tum-mcp install audio-notes`. It adds the
 `audio-notes` skill for prepared Study content; synthesis is set up when used.
 Existing course audio is retained when the extension is disabled.
 
+Video Notes is optional: use `tum-mcp install video-notes`. It adds the
+`video-notes` skill and the `tum-mcp video-notes` commands for prepared Study content.
+Its render runtime (about 320 MB) installs on first use; `tum-mcp video-notes runtime
+status` lists any prerequisite (macOS: `brew install cairo`; Linux/WSL: Cairo and
+Pango development packages and a C compiler) without installing it. Course videos are
+retained when the extension is disabled. Clients pinned to a runtime generation older
+than this release cannot read the enabled Video Notes setting and would hide Studocu
+tools; refresh them with `tum-mcp update` or `setup --client NAME`.
+
 ## Terminal output
 
 `tum-mcp doctor` is the overview for saved connections, optional extensions,
@@ -229,7 +238,8 @@ protected. `--forget-credentials` removes saved local credentials and session
 keys; it does not revoke remote credentials. Settings, custom skills, course
 cache, downloads and assignment work are retained by these commands.
 No command recursively deletes the campus
-data root. Course audio and optional shared speech models/runtimes also remain.
+data root. Course audio and videos, the optional video render runtime and shared
+speech models/runtimes also remain.
 Remove a shared speech cache only when explicitly requested and no other course
 needs it; its host paths are documented in the audio skill. If removal is
 interrupted, run `tum-mcp setup --client NAME` to recover before reuse.

package/docs/study.md

@@ -8,7 +8,8 @@ The optional `prepare-lecture` skill adds a Lecture Notes workspace; install it
 `tum-mcp install lecture`. See [Lecture Notes](lecture-notes.md).
 The optional `sync-studocu` skill collects selected student-uploaded material separately.
 The optional `audio-notes` skill turns prepared lessons into spoken tracks; install
-it with `tum-mcp install audio-notes`.
+it with `tum-mcp install audio-notes`. The optional `video-notes` skill turns prepared
+topics into short narrated explainer videos; install it with `tum-mcp install video-notes`.
 
 ## Start with one course
 
@@ -43,6 +44,7 @@ pse-ws26/
     content.json            Optional source-backed Study content
     exercises.json          Optional prepared exercise guidance
   audio/                    Optional category audio derived from the prepared website
+  videos/                   Optional explainer videos derived from the prepared website
 ```
 
 `AGENTS.md` retains user rules and points agents to `.tum-mcp/course.md`. That short
@@ -241,7 +243,7 @@ previously managed lecture images. A notes-only export with notes excluded is re
 
 Only the selected generated website renderer and data are uploaded. Downloaded
 originals, credentials, AGENTS.md, study inventory, passage comments, progress,
-audio and arbitrary files stay local. Git itself is not required: the publisher
+audio, videos and arbitrary files stay local. Git itself is not required: the publisher
 uses authenticated GitHub API calls through `gh`. Local publication settings do
 not contain credentials.
 
@@ -339,6 +341,73 @@ for the updated study website”** to reconcile added, changed, removed or moved
 material with the previous verified coverage. This is an agent skill, not a new
 `tum-mcp study` CLI subcommand or a built-in speech service.
 
+## Create and maintain video notes
+
+Install the optional workflow with `tum-mcp install video-notes`. After
+`prepare-study` has authored the course, ask for explainer videos, for example:
+
+```text
+Plan explainer videos for the topics in this study website that benefit from animation,
+then make the BFS one first.
+```
+
+The agent proposes which topics get a video and records a reason for each topic it
+leaves text-first. Each video covers one topic, usually 3 to 8 minutes, in short
+chapters. It is a visual adaptation of the prepared lesson: the problem first, the
+course's own example before the general rule, consistent colors per symbol, one or
+two pause-and-think questions from the topic's practice, and a short recap. Nothing
+outside the prepared content is added; a missing example is reported back to
+`prepare-study`.
+
+Behind the skill, `tum-mcp video-notes` does the checkable work. It prints the
+fingerprints a storyboard cites and rejects storyboards whose sources changed. It
+measures one narration file per sentence and renders the scenes with a pinned Manim
+and Typst runtime (no LaTeX needed). It enforces that animations fit their narration
+frame by frame and reports overlapping or off-screen text. Each run produces a
+contact sheet per chapter for review, and the final video is checked for codec,
+sync, loudness, captions and chapters before publication. Unchanged chapters are
+reused, interrupted runs resume, and a failed publication restores the previous
+files.
+
+Narration follows the Audio Notes policy: the free ElevenLabs website when it really
+generates and downloads the text, otherwise local Kokoro, with no accounts or
+payments. Kokoro has no German voice, so a German topic without a working voice
+keeps its narration pending; a silent draft can be rendered for review but is never
+published.
+
+```text
+videos/
+  plan.json                  Which topics get videos, and why others are text-first
+  storyboards/03_topic.json  Beats, narration, on-screen items and source locators
+  scenes/03_topic/chapters.py  Manim scenes using the bundled helpers
+  tracks/03_topic.mp4        Published H.264/AAC video
+  captions/03_topic.vtt      Captions from measured narration
+  chapters/03_topic.vtt      Chapter markers (and a JSON copy)
+  posters/03_topic.jpg       Poster frame
+  narration/03_topic.txt     Transcript
+  manifest.json              Verified receipts for published videos
+  style.json, voice.json     Course look and actual narrator profiles
+  README.md, COVERAGE.md     Generated overview and coverage
+  .build/                    Narration audio, timing, runs and caches
+  archive/                   Superseded published files
+```
+
+Published videos appear above the topic's Content in the local app (`tum-mcp study`)
+with chapters, captions and a transcript link, and show a notice when the topic
+changed after the video was made. They load when you press play. Hosted study sites
+never include or request videos; copy files from `videos/tracks/` to watch them
+elsewhere. `tum-mcp video-notes inspect PROJECT` reports planned, stale, pending and
+published videos, and `tum-mcp study demo PROJECT --videos` adds a synthetic preview
+clip.
+
+The render runtime (about 320 MB) installs on first use with
+`tum-mcp video-notes runtime install`. Windows x64 needs nothing else. macOS 14+ on
+Apple Silicon needs `brew install cairo` and the Xcode Command Line Tools; Linux and
+WSL on x86_64 with glibc 2.28+ need `libcairo2-dev`, `libpango1.0-dev` and a C
+compiler. `runtime status` prints the exact command and never runs it for you.
+Windows on ARM, Intel Macs, Linux ARM64 and musl Linux are not supported: Manim's
+OpenGL dependencies publish no wheels there.
+
 ## Studocu materials
 
 Install the optional extension with `tum-mcp install studocu` and reload your

package/docs/tum-mcp.md

@@ -227,12 +227,16 @@ The Codex adapter uses a contained Node launcher to pin the managed Python in
 isolated mode; portable stdio manifests require a bare or contained executable.
 The base pack contains five skills: `read-content`, `sync-course`,
 `prepare-study`, `prepare-exercises` and `publish-course`. Optional extensions add
-`prepare-lecture`, `sync-studocu` and `audio-notes`; choose them with `tum-mcp install`.
+`prepare-lecture`, `sync-studocu`, `audio-notes` and `video-notes`; choose them with
+`tum-mcp install`.
 Website-specific retrieval guidance is loaded from references within read-content.
 Teaching and content guidance lives with prepare-study; the course app and its
 synthetic example ship as reusable assets and define the site's design.
 Audio Notes converts prepared content into category tracks and maintains coverage,
 scripts, voice settings, candidates and archives under the course's `audio/` root.
+Video Notes turns prepared topics into narrated explainer videos under `videos/`;
+`tum-mcp video-notes` validates storyboards, measures narration, renders with an
+optional pinned runtime and publishes checked videos for the local app only.
 Publish Course uses host GitHub CLI authentication to create a private repository
 and a public Pages website after explicit publication consent. It chooses a course
 and semester name, updates the same site after successful study builds, and shows

package/npm/backend/manifest.json

@@ -1,5 +1,5 @@
 {
-  "wheel": "tum_mcp-0.9.4-py3-none-any.whl",
-  "wheelSha256": "9014825fc2571531a52db0020fe39aa993638694e816c631318b923257e5a3c6",
+  "wheel": "tum_mcp-0.10.0-py3-none-any.whl",
+  "wheelSha256": "69a13997a3c5630f411e0237f33f7b59224b56d96bbcea07f263b939df1a5eff",
   "requirementsSha256": "39a401b6e606d3292eb91b8fe9ef60367d4852f203eb409dc52f38b76e513ccf"
 }

package/npm/tum-mcp.mjs

@@ -24,13 +24,14 @@ try {
         ['setup', 'Configure your coding client and managed runtime.'],
         ['login', 'Sign in to selected campus services.'],
         ['doctor', 'Show connections, extensions and relevant client/runtime health.'],
-        ['install', 'Choose optional Lecture, Studocu or Audio Notes workflows.'],
+        ['install', 'Choose optional Lecture, Studocu, Audio Notes or Video Notes workflows.'],
         ['uninstall', 'Choose extensions or All to remove TUM MCP.'],
         ['manage', 'Manage TUMonline permissions.'],
         ['skills', 'Inspect and validate workflow skills.'],
         ['study', 'Prepare, preview and publish a course app.'],
         ['lecture', 'Prepare lecture recording evidence (optional extension).'],
         ['studocu', 'Collect selected supplementary materials (optional extension).'],
+        ['video-notes', 'Render and maintain explainer videos (optional extension).'],
         ['discover', 'List accessible courses or channels.'],
         ['update', 'Update the package and configured clients.'],
         ['logout', 'Remove one saved connection.'],
@@ -42,7 +43,7 @@ try {
   } else if (['--version', 'version'].includes(args[0])) {
     console.log(version);
   } else if (args[0] === 'install' && args.some(arg => ['--help', '-h'].includes(arg))) {
-    printHelp(version, 'Choose optional workflows to install, or provide their names.', 'tum-mcp install [lecture|studocu|audio-notes]... [OPTIONS]', [
+    printHelp(version, 'Choose optional workflows to install, or provide their names.', 'tum-mcp install [lecture|studocu|audio-notes|video-notes]... [OPTIONS]', [
       ['Options', [['--asr / --no-asr', 'Provision isolated lecture recognition; models load on demand.'], ['--json', 'Print machine-readable results.'], ['-h, --help', 'Show this help.']]],
     ]);
   } else if (['setup', 'update', 'uninstall'].includes(args[0]) && args.some(arg => ['--help', '-h'].includes(arg))) {
@@ -59,7 +60,7 @@ try {
       },
       uninstall: {
         description: 'Remove managed setup while retaining saved user data by default.',
-        usage: 'tum-mcp uninstall [lecture|studocu|audio-notes]... [OPTIONS]',
+        usage: 'tum-mcp uninstall [lecture|studocu|audio-notes|video-notes]... [OPTIONS]',
         options: [['(no arguments)', 'Choose extensions or All in the interactive picker.'], ['--client NAME', 'Remove one client registration.'], ['--host local|windows', 'Choose the client host.'], ['--purge-runtime', 'Remove verified runtimes when All is selected.'], ['--forget-credentials', 'Forget saved credentials when All is selected.']],
       },
     };
@@ -68,7 +69,7 @@ try {
       ['Options', [...selected.options, ['-h, --help', 'Show this help.']]],
     ]);
   } else {
-    const hasExtension = args.slice(1).some(arg => ['lecture', 'studocu', 'audio-notes'].includes(arg));
+    const hasExtension = args.slice(1).some(arg => ['lecture', 'studocu', 'audio-notes', 'video-notes'].includes(arg));
     let packageAction = args[0] === 'update';
     if (args[0] === 'update') {
       if (args.length > 2 || (args.length === 2 && args[1] !== '--local')) throw new Error('Usage: tum-mcp update [--local]. Use --help for details.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Read-only TUM campus tools and source-backed study, exercise and lecture workflows",
   "license": "MIT",
   "type": "module",