[chhoumann]

Summary

Rewrites and expands the PodNotes user documentation for 2.25.0 multi-provider transcription (ElevenLabs, Deepgram, OpenRouter, OpenAI, and OpenAI-compatible server), including:

• All five OpenRouter transcription models: speaker-labeled Grok STT 2.0 (recommended, with multi-part MP3 speaker matching), ElevenLabs Scribe v2, and MAI-Transcribe 2, plus Voxtral Mini Transcribe 3 (segment timestamps, 4.55% measured mean word error) and Qwen3 ASR 1.7B (word timestamps with punctuation restored from text, about $0.03 per hour).
• The OpenAI-compatible server provider (/v1/audio/transcriptions), covering accepted http:// and https:// Server address forms, optional OpenAI-compatible server API key, text Model ID, 24 MB upload parts, local-machine audio privacy, phone localhost vs LAN/VPN behavior, and verbose_json timestamp handling with HTTP 400 fallback to json.
• The 2.24.0-to-2.25.0 migration guide and fresh light/dark/phone screenshots captured from the isolated e2e vault against the local fixture server.

Pages added

• docs/src/content/docs/transcription-providers.md (/transcription-providers/): concise provider overview, step-by-step setup for ElevenLabs, Deepgram, OpenAI, OpenRouter (all five models), and OpenAI-compatible server, plus the Provider and model reference tables (OpenRouter models and API keys across devices and backups) at the end of the page.
• docs/src/content/docs/update-2-25.md (/update-2-25/): 2.25.0 transcription migration guide covering how existing 2.24.0 setups map to transcript.provider, OpenAI's move from whisper-1 and gpt-4o-transcribe-diarize to GPT Transcribe (gpt-transcribe, ahead of OpenAI's 2027-02-26 shutdown), how to keep speaker labels or connect an OpenAI-compatible server, and mixed-device behavior when syncing with 2.24.0 clients.

Pages and site config updated

• docs/src/site.mjs: adds Choose a transcription provider under Listen right after Transcribe episodes, and Update to 2.25.0 under Start here.
• docs/src/content/docs/transcripts.md: rewrites Transcribe episodes around published RSS transcripts, audio transcription (PodNotes: Transcribe current episode and PodNotes: Transcribe current episode from audio), the Transcript panel (Transcribe with <Provider> + Paid vs Transcribe with your server without Paid), clickable timestamps, speaker labels (model support, disabled-while-off Speaker labels row, OpenRouter Grok STT 2.0 MP3 voice matching vs per-part speaker resets, and 18 MB / 30 min MP3 vs 12 MB / 15 min MP3 OpenRouter part limits), and Limits (including offline command gating and 24 MB server upload parts).
• docs/src/content/docs/upgrade.md: links 2.24.0 upgraders directly to Update to 2.25.0 while keeping the 2.22.0 migration reference intact.
• docs/src/content/docs/settings.md: updates Timestamp template, Transcripts (Transcription provider, Server address, all five provider API key rows including optional OpenAI-compatible server API key, dropdown/text Model row, Speaker labels, Speaker label format, Transcript path, Transcript template), and Include API keys.
• docs/src/content/docs/faq.md: adds Which provider should I use?, Why does my transcript have no speaker labels?, and Why did my transcription fail? covering every preflight and HTTP failure notice from TranscriptionService.ts and src/services/transcription/http.ts (including server address/model validation, server 401/403, server 404, HTTP 400 format rejection, and server connection notices).
• docs/src/content/docs/mobile.md: explains phone transcription behavior, direct URL fetch on ElevenLabs, Deepgram, and OpenRouter's ElevenLabs Scribe v2 vs on-device upload/splitting on the other models and OpenAI-compatible server, and reaching a computer's server via LAN/VPN IP instead of localhost.
• docs/src/content/docs/import_export.md, docs/src/content/docs/sync.md, docs/src/content/docs/player.md, docs/src/content/docs/templates.md, docs/src/content/docs/commands.md: aligns SecretStorage references (openAICompatibleSecretId / podnotes-openai-compatible-api-key), serverUrl / model sync and export behavior, Transcript panel button labels, and template timestamp behavior across all five provider options.

Screenshots added and regenerated

• docs/public/screenshots/transcript-settings.webp (-dark, -phone, -phone-dark)
• docs/public/screenshots/openrouter-models.webp (-dark, -phone, -phone-dark) — regenerated to show all five OpenRouter models on desktop and the closed Model row on phone
• docs/public/screenshots/openai-compatible-settings.webp (-dark, -phone, -phone-dark) — Transcripts group with OpenAI-compatible server, fixture http://localhost:<port>/v1 Server address, unlinked OpenAI-compatible server API key, whisper-large-v3-turbo Model, and disabled Speaker labels
• docs/public/screenshots/transcript-note.webp (-dark, -phone, -phone-dark)
• docs/scripts/screenshots.mjs, docs/screenshots/seed.mjs, .claude/skills/verify/net.mjs: extends automated screenshot capture for all five OpenRouter models and OpenAI-compatible server using .claude/skills/verify/fixtures.mjs server and net.mjs watch (including re-installing net.mjs watch after place("phone") reloads the renderer).

Verification

Commands run

• fnm exec --using 22.23.2 npm ci
• fnm exec --using 22.23.2 npm run build
• fnm exec --using 22.23.2 npm run start:e2e-obsidian
• fnm exec --using 22.23.2 node docs/scripts/screenshots.mjs openrouter-models openrouter-models-phone openai-compatible-settings openai-compatible-settings-phone
• fnm exec --using 22.23.2 node .claude/skills/verify/fixtures.mjs stop && fnm exec --using 22.23.2 npm run stop:e2e-obsidian
• fnm exec --using 22.23.2 npm run docs:build
• fnm exec --using 22.23.2 npm run lint
• fnm exec --using 22.23.2 npm run format:check
• fnm exec --using 22.23.2 npm run typecheck
• fnm exec --using 22.23.2 npm run test:tooling

Review rounds

1. Standards (docs/STYLE.md): Audited every new and modified page line by line against docs/STYLE.md. Verified one job per page, verb-first task headings and noun-phrase concept headings, no -ing headings, no skipped heading levels, single-sentence description: frontmatter, <150-character alt text with no NN:NN times, zero semicolons (;), zero em dashes (—), zero banned words (simply, just, easy, powerful, seamless, utilize), exact bold UI labels, and single-action numbered steps naming the place before the action. Consolidated cloud key setup boilerplate and moved lookup tables under Provider and model reference at the end of /transcription-providers/ to stay within STYLE.md's screen-length guidance while preserving all heading fragment IDs.
2. Facts (src/): Traced every behavioral claim, UI label, placeholder, validation string, limit, and quoted notice to src/services/transcription/{registry,transcribe,http,audioSource,speakers,cues,split}.ts, src/services/transcription/providers/{elevenlabs,deepgram,openrouter,openai,openaiCompatible,verboseJson}.ts, src/utility/assertFetchableUrl.ts, src/services/TranscriptionService.ts, src/ui/settings/PodNotesSettingsTab.ts, src/ui/PodcastView/TranscriptPanel.svelte, src/settingsMigrations.ts, src/settingsTransfer.ts, src/persistence/settingsCodec.ts, and src/types/Credentials.ts. Verified exact SLOW_PART_CAPS (12 MB / 15 min MP3) on Voxtral Mini Transcribe 3 and Qwen3 ASR 1.7B, 24 MB upload cap on OpenAI-compatible server, HTTP 400 response_format / verbose_json / timestamp_granularities retry to json (openaiCompatible.ts:50-54, transcribe.ts:66-68), Transcribe with your server button text without Paid (TranscriptPanel.svelte:71-73, 191-192), and offline command gating even with a local server. (Note for PR feat(transcription): transcribe with any OpenAI-compatible server #546: Obsidian 1.14.4 logs a console warning PodNotes: duplicate setting key "name:Model" when opening the PodNotes settings tab because PodNotesSettingsTab.ts:377-384 defines both dropdown and text Model rows with name: "Model".)
3. Cold reader (390 px & 1440 px, light & dark): Served docs/dist/ locally and inspected all 8 touched pages in headless Chrome at 390×844 and 1440×900 in light and dark themes. Verified zero horizontal overflow (scrollWidth === innerWidth across all 32 route/viewport/theme combinations), responsive -phone and -dark <picture> source switching, legible closed-dropdown phone crops, and clean mobile card stacking for both Provider and model reference and OpenRouter models tables.

Release impact

None (documentation and screenshot tooling only; targets feat/transcription-openai-compatible as a draft PR for the 2.25.0 release).

Note

Rewrite transcript docs for provider choice, API keys, and model setup

• Reworks transcripts.md to cover feed transcripts and audio transcription via ElevenLabs, Deepgram, OpenRouter, OpenAI, or an OpenAI-compatible server, with provider selection, model choice, speaker labels, and troubleshooting links.
• Adds a new provider guide (transcription-providers.md) with setup steps, timestamp/speaker-label behavior, and key storage, sync, and export notes.
• Adds a 2.25.0 migration guide (update-2-25.md) covering the OpenAI change to GPT Transcribe and how old diarization and key settings map to the new settings.
• Updates related pages (settings, player, mobile, sync, import/export, FAQ, commands, templates, upgrade) and the sidebar to match the new provider model.
• Extends screenshots.mjs with transcript settings, OpenRouter model-menu, and transcript-note captures in desktop and phone sizes, plus a transcript fixture and a --turns option in net.mjs for the network watcher.
• Risk: several old fragment IDs in transcripts.md are preserved only as aliases; check that external links to moved setup, cost, and key-storage sections still resolve.

^{Macroscope summarized a96df75.}

---

Note

Low Risk
Documentation and e2e/screenshot tooling only; no production transcription or plugin runtime logic changes.

Overview
Documents PodNotes 2.25.0 transcription across ElevenLabs, Deepgram, OpenRouter, OpenAI, and OpenAI-compatible server, replacing the older OpenAI/Deepgram-only docs.

Adds transcription-providers.md (setup steps, model comparison, device/backup key behavior) and update-2-25.md (settings migration from 2.24.0, GPT Transcribe, mixed-device sync). transcripts.md and related guides (settings, FAQ, player, mobile, sync, import/export, commands, templates) are rewritten for provider choice, timestamps, speaker labels, server address/model preflight, and transcription failure notices. site.mjs links the new pages in the sidebar.

Screenshot automation grows to support selective runs ([shot ...]), Transcripts settings captures (including native Model dropdown via OS window grab), fixture-backed transcript notes from seed.json, and net.mjs watch --turns so mocked API responses match the multi-turn demo dialogue.

^{Reviewed by Cursor Bugbot for commit a96df75. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cloudflare-workers-and-pages]

Deploying podnotes with    Cloudflare Pages

Latest commit:	a96df75
Status:	✅  Deploy successful!
Preview URL:	https://5799e1ab.podnotes.pages.dev
Branch Preview URL:	https://docs-transcription-guide.podnotes.pages.dev

View logs