Lumen YouTube

Lumen YouTube is an Obsidian plugin that turns YouTube clippings into clean transcript Markdown — original text plus an optional Chinese translation — and, since v0.4, plays the video inside Obsidian with the transcript following along.

It identifies the YouTube URL in a clipping note, fetches the video's existing captions, and writes a tidy, timestamped transcript into your vault for Lumen (or any other workflow) to digest.

What It Does

• Find the video automatically — reads the YouTube URL from a note's frontmatter (source / url / link) or body. Supports watch, youtu.be, shorts, live, and embed links, including ones inside Markdown syntax.
• Fetch existing captions via YouTube's InnerTube player API — no Whisper, no audio download, no video download. Manual captions are preferred over auto-generated ones, and a picker appears when several tracks could match.
• Write a clean transcript to your output folder as {title} - {videoId}.md, with clickable per-line timestamps under a stable ## Transcript heading.
• Optional Chinese translation into a sibling … CN.md file via any OpenAI-compatible provider (OpenAI / OpenRouter / DeepSeek / Kimi / Custom). Off by default; runs only when an API key and model are set, so there are no silent API calls or costs. Every timestamp line is preserved.
• Live translation progress — a persistent window shows streaming text, current chunk, completed subtitle lines, elapsed time, cancellation, retry, and safe compatibility fallback. DeepSeek V4 translation starts directly in non-thinking mode instead of appearing frozen during hidden reasoning.
• Link back to the clipping — writes status frontmatter (transcript_status, transcript_file, transcript_cn_file, …) and a ## Lumen YouTube section into the source note. Re-running is idempotent.
• Play inside Obsidian (desktop, v0.4) — open the clipping's video next to its transcript, with the current line highlighting and autoscrolling in sync. Click any line to seek; toggle original / Chinese / bilingual display.
• Visible player entry points — open the player from the ribbon, a Markdown file menu, processed-note buttons, or the successful-processing Notice; the command palette remains available but is no longer required.
• Five player themes — Default, Retro terminal, Frosted, Midnight Cinema, and Neo-Brutalism. The two newest themes cover the transcript, player tray, and settings surface and preserve filled, side-bar, or text-only highlighting.
• Timestamped notes — freeze the current playback time and append a clickable - [MM:SS](…) note line to the clipping's ## Notes section.
• Localized UI — English or Chinese, following Obsidian's configured language.

What It Is Not

Lumen YouTube does not summarize, download video or audio, transcribe with Whisper, or talk to the Lumen plugin directly. It produces text assets from captions that already exist on YouTube; the player is a read/review surface streamed live from YouTube.

Web Clipper note → Lumen YouTube → Transcript Markdown (+ optional CN) → Lumen Summary
                                 ↘ Player + synced transcript (v0.4, desktop)

What's New in v0.8.0

• Translation output now appears token by token with durable progress and immediate cancellation.
• DeepSeek V4 default thinking mode no longer causes false first-token timeouts; reasoning-only activity from compatible providers is shown as an active thinking state without exposing reasoning text.
• Response, first-token, and stream-idle timeouts use separate timing windows with safe diagnostics that exclude credentials and model output.
• Player access is discoverable from visible UI entry points, not only commands.
• New Midnight Cinema and Neo-Brutalism themes provide complete dark and high-contrast visual alternatives.

Installation

Lumen YouTube is not yet in the Obsidian community plugin store.

Via BRAT (recommended)

BRAT installs the plugin and keeps it auto-updated from this repository.

1. Install BRAT from Community Plugins and enable it.

2. Run the command BRAT: Add a beta plugin for testing.

3. Paste this repository URL:

   https://github.com/leoyang1984/obsidian-lumen-youtube-public
   

4. BRAT downloads the latest release into your vault.

5. Enable Lumen YouTube in Community Plugins, then open its settings.

Manual install

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Put all three files in <your-vault>/.obsidian/plugins/lumen-youtube/.
3. Reload Obsidian and enable Lumen YouTube in Community Plugins.

Usage

1. Open a clipping note that contains a YouTube URL.
2. Click Process YouTube transcript or Open Lumen YouTube player in the ribbon. Processed notes also expose contextual player/transcript buttons.
3. You can still run any workflow from the command palette:
   • Lumen YouTube: Process current note — fetch (and translate, if enabled).
   • Lumen YouTube: Fetch transcript only — never translates.
   • Lumen YouTube: Translate current transcript — translate an already-open transcript file into a CN file.
   • Lumen YouTube: Open player with synced transcript — desktop only.
   • Lumen YouTube: Add note at current time — desktop only.

Optional translation is configured in settings: pick a provider, paste an API key, and set a model name. Base URLs are prefilled but editable.

Output Format

A transcript file with clickable, per-line timestamps:

---
source: "https://www.youtube.com/watch?v=VIDEOID"
video_id: VIDEOID
caption_kind: manual
generator: Lumen YouTube
---

# Video title

## Transcript

- [00:00](https://www.youtube.com/watch?v=VIDEOID&t=0s) First line of dialogue
- [00:04](https://www.youtube.com/watch?v=VIDEOID&t=4s) Second line of dialogue

With translation enabled, a sibling … CN.md file mirrors the timestamps under a ## 中文翻译 heading so the player can switch languages line-for-line.

Known Limitation

YouTube has been tightening unauthenticated caption access. Most public videos work, but some (often newer or auth-gated ones) expose no caption tracks without a logged-in session — for those the plugin correctly reports no_caption. This is a YouTube-side constraint, not a bug in the fetch logic.

The in-Obsidian player is desktop only (the YouTube embed and custom views are impractical on mobile); transcript fetching and translation stay cross-platform. Videos that disallow embedding open in your browser instead.

Source Code

This public repository is used for plugin distribution and release notes only. The compiled main.js is published here for installation; the TypeScript source is not published.

Credits

The InnerTube caption-fetching strategy is adapted from ljantzen/obsidian-youtube-transcript (MIT).

License

Lumen YouTube is available for non-commercial use only. See LICENSE.md.

Commercial use, resale, SaaS hosting, paid-client use, marketplace redistribution, and commercial bundling require prior written permission.