Skip to content

docs(transcripts): choose a provider, set up keys and read transcripts - #545

Merged
chhoumann merged 63 commits into
masterfrom
docs/transcription-guide
Nov 17, 2026
Merged

chhoumann merged 63 commits into
masterfrom
docs/transcription-guide

Conversation

@chhoumann

@chhoumann chhoumann commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

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

Add transcription provider docs for PodNotes 2.25.0 with new screenshots and fixture tooling

  • Adds a provider-selection and setup page (transcription-providers.md) covering ElevenLabs, Deepgram, OpenRouter, OpenAI, and OpenAI-compatible servers, and rewrites transcripts.md around provider-based setup.
  • Adds a 2.25.0 upgrade guide (update-2-25.md) with the OpenAI model migration, settings rename table, and speaker-label restore steps. Updates cross-references in the settings, FAQ, sync, mobile, player, templates, import/export, commands, and upgrade pages.
  • Extends the screenshot pipeline in screenshots.mjs to capture transcript settings, the OpenRouter model menu, and a fixture-generated transcript note in desktop and phone layouts, plus a per-shot name filter so single captures can run.
  • Adds transcript fixture turns to seed.json and lets net.mjs watch accept --turns <json> so the fixture watcher returns custom transcription turns.
  • Behavioral Change: prepareVault in screenshots.mjs now closes Obsidian Settings before enabling internal plugins; watchSource in net.mjs returns "reset" vs "watching" depending on whether it replaced a prior watcher.

Macroscope summarized 7060f8f.


Note

Low Risk
Changes are limited to documentation and e2e screenshot/verify fixtures; no production plugin runtime behavior in the diff.

Overview
Adds user-facing docs for PodNotes 2.25.0 multi-provider transcription: new Choose a transcription provider and Update to 2.25.0 pages, a full rewrite of Transcribe episodes, and aligned updates across settings, FAQ (including transcription failure notices), sync, mobile, player, commands, and import/export. The site nav now links those guides.

Screenshot tooling gains optional per-shot CLI filtering, transcript settings and OpenRouter Model menu captures (including OS-level grabs for open <select> popups), fixture-driven transcription shots on desktop and phone, and a multi-turn dialogue seed. net.mjs watch accepts --turns JSON so verify mocks match scripted transcript fixtures instead of a fixed two-turn reply.

Reviewed by Cursor Bugbot for commit 7060f8f. Bugbot is set up for automated code reviews on this repo. Configure here.

gpt-4o-transcribe-diarize rejects requests with more than 1400 s of audio,
but MP3 chunks were split by size alone. Any MP3 under about 120 kbps put
more than 1400 s in a 20 MB chunk, so every chunk failed.

For diarization, split MP3 at frame boundaries into the fewest equal parts
that stay under both 20 MB and 1400 s. Whisper keeps its size-only chunks.

Fixes #532
A chunk that OpenAI rejected with a status such as 400 or 401 was sent
three times, although each send fails the same way. A long diarized
episode went up three times before the error showed.

Retry only the statuses openai-node retries: 408, 409, 429 and 5xx, plus
network errors.

Refs #532
gpt-4o-transcribe-diarize takes up to 0.58 s per second of audio, measured
over 81 requests, so the 1,072 s parts a 54 min episode got would take about
10 min each, at the request timeout. Parts are now at most 600 s, which the
model answers in under 6 min.

Refs #532
Each test passes on the hand-written code. Together they catch wrong
derivations that no existing test sees: the -1 SecretStorage ID suffix
that released versions accept, the provider an export error names, the
kind a settings key row adopts a secret for, and the key migration
notices.
CREDENTIALS in src/types/Credentials.ts holds each kind's settings
field, export key and label. The credential repository, settings
decoder, settings transfer, settings tab and key migration notice loop
over it. IPodNotesSettings takes its key fields from it, so a kind with
no default in DEFAULT_SETTINGS fails typecheck. The plaintext key map
from before 2.19.0 stays fixed.
The published transcript renderer is the reader of the format that stays
when the diarization folder goes. The default template now lives only in
DEFAULT_SETTINGS, so src/constants.ts imports no service code.
src/services/transcription/ turns an episode into a transcript with any
provider. A provider is one file: its models, its request, and how to read
its answers. OpenAI (gpt-transcribe) and Deepgram (nova-3) are the first two.

The engine owns what providers share:

- audioSource.ts decides whether a provider may be given the episode's
  address. Only an address that a saved public feed lists, that carries no
  credential, and that names a public host passes. All other audio is
  uploaded.
- split.ts is audioChunker.ts with the caps as arguments and a start time
  on each part.
- http.ts sends a request at most three times, and only after a 429, a 5xx,
  or a lost connection. Its failure sentences never include the provider's
  own text, which can quote a private address.
- cues.ts turns words or text into the shapes of a published transcript.

Nothing calls the engine yet. Lint rejects an import of the folder's files
from outside it, except its index.
TranscriptionService keeps its queue, the published-transcript path, the
progress notice, and note saving. It calls the engine for audio.

- OpenAI transcribes with gpt-transcribe. whisper-1 and
  gpt-4o-transcribe-diarize, which OpenAI shuts down on 2027-02-26, are
  gone. A tooling test searches the built main.js for them.
- With speaker labels on and OpenAI selected, the transcript is saved
  without labels. A notice that stays until clicked names the providers
  that label speakers.
- Deepgram transcripts go through renderTranscriptBody, so each paragraph
  has a timestamp. Speakers are numbered in the order they first speak.
- Deepgram gets the address of a public episode and downloads it itself.
- A failure notice stays until clicked. Parts go out one at a time, and a
  401, 402, 404, or 400 stops the job before the next part.

Deletes src/services/diarization/, openaiTranscription.ts, the Whisper
worker pool, and createBinaryChunkFiles. getEpisodeAudioBuffer no longer
returns a basename, because uploads are named for their format only.
net.mjs answers OpenAI with { text } and Deepgram with the words of two
speakers, and logs the content type of each request. fixtures.mjs serves a
feed at priv3.supercast.com, an address that PodNotes keeps private. The
transcripts recipe covers OpenAI in parts, and Deepgram by address and by
upload.
The marketplace review test called TranscriptionService.waitForRetry, which
the engine replaced. An aborted run now rejects through waitForLifecycle, so
the test aborts a pending wait there and expects the same Error.
An aborted job no longer downloads the episode or decodes it into parts.
Until now only its requests were refused.

A 429 or a 5xx that asks to wait over a minute is sent once. A sooner send
would only upload the audio to be refused again.
A provider's name was written twice: once in its credential row and once in
its provider file. The row now owns it, so a provider file holds only its
models and its request. Each model gains the name the settings will show.
The provider was derived from the speaker settings: Deepgram with speaker
labels on, OpenAI otherwise. It is now stored as transcript.provider, with
transcript.model beside it, where "" follows the provider's recommended model.
schemaVersion stays 2 and both fields are additions, so a device on 2.24.0
keeps loading the library and keeps the fields on its own saves.

A library that has no transcript.provider gets the provider it ran with:
Deepgram for speaker labels with Deepgram, with or without its key, and OpenAI
otherwise. The migration reads only the stored document, adds no decode
warning, and gives the same answer on every load until a save stores it.

transcript.diarization.provider belongs to versions up to 2.24.0. This version
reads it for that migration alone, never writes it, keeps it in data.json as
found, and leaves it out of settings exports. Importing a 2.24.0 export that
labels speakers with Deepgram selects Deepgram.

A provider or model ID this version does not have is kept as stored and shown
under that name. An unknown provider refuses to transcribe with a notice. An
unknown model runs the recommended model and the notice says so.

The Transcripts settings now read: Transcription provider, the chosen
provider's API key, Model, Speaker labels, Speaker label format, then the path
and template. Speaker labels is disabled for a model that cannot label
speakers. The Diarization provider row is gone.
ElevenLabs is a credential row, one provider file and a registry line. Its key
reference is the new root field elevenLabsSecretId, stored in SecretStorage as
podnotes-elevenlabs-api-key, and a settings export carries the key as
secrets.elevenLabs. The export envelope stays at version 2.

A public episode goes to ElevenLabs by its address, so nothing is downloaded.
Any other episode is uploaded in one request. Word times and speakers reach
the note, and turning speaker labels off asks for none.

ElevenLabs answers 401 for a used-up quota as for a rejected key, and 400 for
a model the key may not use as for an address it could not download, so the
provider reads detail.code. Only the last of these is followed by an upload.
A request waits 10 minutes for its answer.

A new install starts on ElevenLabs with speaker labels on. A library saved up
to 2.24.0 that holds no OpenAI key and has speaker labels off moves to
ElevenLabs too, because it never set transcription up. A library that never
stored the speaker labels choice keeps them off.

The notice for a model without speaker labels now names ElevenLabs first.
A journey now seeds its transcription provider with its key, because a new
vault is on ElevenLabs. The OpenAI journeys choose OpenAI. A new journey runs
the default: a public episode goes to ElevenLabs by its address, no audio is
fetched, and the note has timestamps and speaker labels. The ElevenLabs stub
answers with the words ElevenLabs returns and records what each request named.

The settings tab test walks the new Transcripts rows, and the key recovery
test links the ElevenLabs key, the one a new vault shows.
The fixture provider answers api.elevenlabs.io with ElevenLabs' words, two
speakers with the second 12 s in, and logs the address a request named in
place of a file. The transcript guide follows the new settings rows and adds
the ElevenLabs runs and a 2.24.0 library check.
…choice

The provider row decided for itself whether the stored provider is one this
version has, and the Speaker label format row read the stored speaker setting.
Both now ask transcriptionChoice, as the key rows, the model row and the
Speaker labels row do. The engine no longer exports a type nothing imports.
The Transcripts tests looked each control up by a CSS selector inside its row
and asserted on a hidden row's inline style. They now query by role and by the
row's name, as a user or a screen reader finds a control, so a hidden row is
one the query does not find.
…ings measure

The transcription engine left main.js at 103,795 gzip bytes. The provider and
model settings, their migration and the ElevenLabs provider add 866, which
takes it to 104,661 and over the 104,000 budget. The budget rises by those 866
bytes to 104,866, so the 205 bytes of headroom stay as they were.
…m library

2.24.0 imports the diarization object whole and fills a missing provider
with OpenAI, so omitting the field moved Deepgram libraries to OpenAI.
Imports here keep the provider this library stored.
A library migrated with OpenAI speaker labels on could not turn them off,
so every transcription repeated the notice.
… one

The tests for a provider and a model a newer PodNotes stored used OpenRouter
and Grok STT 2.0, which this version is about to run. They now use AssemblyAI
and universal-3-6-pro.
OpenRouter is a credential row, one provider file and a registry line. Its
key reference is the new root field openRouterSecretId, stored in
SecretStorage as podnotes-openrouter-api-key, and a settings export carries
the key as secrets.openRouter.

It offers three models, each with the request measured to give word times
and speakers:

- Grok STT 2.0, recommended: base64 JSON with verbose_json and word and
  segment times, routed to xAI with provider.only, which takes diarize from
  provider.options.xai. A request routed elsewhere is answered with no
  speakers.
- ElevenLabs Scribe v2: multipart with diarize beside the model, or JSON with
  input_audio.url for an episode a saved public feed lists.
- MAI-Transcribe 2: multipart with diarize beside the model.

With speaker labels off, no request carries diarize. Sounds Scribe v2 lists
as audio_event items are left out.

OpenRouter takes 25 MB a request and gives the model 60 s, so an upload goes
in parts of at most 18 MB and 1,800 s. Parts of 24 MB were answered in 20 to
31 s.

A 402 says the account is out of credit, a 401 that the key was rejected,
and a 404 that the model is not offered. A 404 whose message names the
account's data policy or zero data retention says the model is not offered
under the account's OpenRouter privacy settings. Each ends the job at the
first part, and none quotes OpenRouter.
…t each part

A note saved with speaker labels asked for and none returned now says so:
"Saved without speaker labels, because Grok STT 2.0 returned none." OpenRouter
answers 200 with no speakers when a request reaches a route that ignores the
speaker option, so this is checked for every provider.

Labels from two parts already name different speakers. An episode sent in
parts now also says that its labels restart in each part, so one person can
have several labels, until labels are merged across parts.
…ll lists

PodNotes reads OpenRouter's public catalog of transcription models, without
the key, when the Model row draws and when an OpenRouter job starts. It keeps
the read in memory for 24 hours. A read that fails is not kept, so the next
one asks again, and the tested list is offered as it is.

The catalog only takes models away. A model it does not list is not offered,
and one whose expiration_date has come is skipped. A model with a later end
date reads "Grok STT 2.0, ends <date>" in the Model row. A catalog that would
leave no model is not followed.

A chosen model the catalog no longer lists stays selected in the Model row as
"<label>, no longer offered". A job runs the first offered model instead and
says "OpenRouter no longer offers ElevenLabs Scribe v2, so PodNotes used Grok
STT 2.0." The row redraws when a read lands while it is open.

A provider gets its catalog through an optional catalog() beside failure(),
so the registry owns the cache and the filter for any provider that has one.
A stub answers OpenRouter's transcriptions with two speakers, the second 12 s
in, and its model catalog with the three models PodNotes offers. It records
what each request named and a hash of the audio it carried, decoded from
base64 for JSON.

J-TR-09 plays a public episode on Scribe v2: one JSON request names the
episode's address, and the episode's audio is never fetched. J-TR-10 plays it
on the recommended Grok STT 2.0: one JSON request carries the audio as base64,
the same bytes the fixture server holds. Both notes have timestamps and
numbered speakers, and the catalog is read once, with no Authorization.

A journey seeds any provider by its credential row, and a model with it.
…eads them

The fixture provider answers openrouter.ai transcriptions with verbose_json
words from two speakers, the second 12 s in, and the model catalog with the
three models PodNotes offers. The log keeps openrouter.ai paths and reads the
address a JSON request names in input_audio.url.

The transcript guide adds the OpenRouter rows, its runs (Scribe v2 by
address, Grok by base64, a long MP3 in parts) and the notices that now name
OpenRouter.
requestWithTimeout and assertFetchableUrl take a privateHosts option. With
it, a target on this device or a private network (localhost, 127.0.0.1,
192.168.x.x, .local and the other non-public ranges) passes the target
policy. Every other rule still applies: http or https only, an explicit
authority, no fragment, no surrounding whitespace. Without the option,
which every existing caller omits, the policy is unchanged, so feeds,
artwork, transcripts and the hosted providers stay blocked from private
targets.
Qwen3 ASR lists its words without punctuation and keeps it only in `text`,
so its notes ran on as one unpunctuated stream with paragraphs cut at fixed
lengths. Each word now takes its punctuated token from `text`.
A sixth provider, "OpenAI-compatible server", sends audio to any server that
speaks OpenAI's /v1/audio/transcriptions API: a local whisper.cpp,
faster-whisper or speaches server, Groq, Together, or OpenAI itself. It is a
credential row, one provider file and a registry line, plus two settings.

Settings. transcript.serverUrl holds the address as typed, and
transcript.model the model ID the user types, both additive with
schemaVersion still 2. The key reference is the new root field
openAICompatibleSecretId, stored in SecretStorage as
podnotes-openai-compatible-api-key, and a settings export carries the key as
secrets.openAICompatible. With the provider chosen, the Transcripts rows read
Transcription provider, Server address, OpenAI-compatible server API key,
Model as a text field, then the shared rows. An address that is not http or
https says so under the field.

Address. A base such as https://api.groq.com/openai/v1 and the full
.../audio/transcriptions URL reach the same endpoint, after spaces and
trailing slashes are trimmed. Only this provider's requests may reach this
device or a private network, because the user typed the address.

Gate. The key is optional: with none selected the request carries no
Authorization header. A selected key that is not on this device still stops
the job. An address that is not http or https, or an empty model, stops the
job with a notice that says what to enter.

Request. Multipart with model, file, response_format=verbose_json and word
and segment timestamp granularities, in parts of 24 MB with no length cap.
A 400 that names the response format or the timestamp option, as OpenAI's
gpt-transcribe answers, is sent once more as json without timestamps. Words
become timed paragraphs, segments when there are no words, and text untimed
paragraphs. The provider labels no speakers, and audio is always uploaded,
so no episode address, public or private, reaches the server.

The player's Transcript panel reads "Transcribe with your server", without
the Paid tag, because PodNotes cannot tell whether the user's server
charges. The notice after a published transcript fails offers "your
OpenAI-compatible server" without the API credit clause.

Errors stay PodNotes' own sentences. A 401 says the server at <host>
rejected the API key, a 404 that it has no such model at that address, and
no answer that PodNotes could not reach the server at <host>.
…hine

The journey fixture server also answers POST /v1/audio/transcriptions as a
Whisper server does, with verbose_json words for two sentences 12 s apart,
and records each request. J-TR-11 points the OpenAI-compatible provider at
it with a trailing slash and no key, runs Transcribe current episode, and
checks the timed note and the one request: no Authorization header, the
model, verbose_json, word and segment granularities, and the episode's
audio byte for byte. The request travels Obsidian's requestUrl to
127.0.0.1, so it also proves a server on this machine is reached.
… fixture server

fixtures.mjs server prints http://podnotes.test:<port>/v1, a route on the
fixture server that answers POST /v1/audio/transcriptions with verbose_json
words, or json's text when asked for json, and refuses verbose_json for the
model json-only with the 400 OpenAI's gpt-transcribe gives.
fixtures.mjs transcriptions prints each request it answered. Runtime checks
reach it over Obsidian's real network path with no paid key. The
transcripts recipe covers the provider's settings, a local file, the json
fallback and the refusals.
…ovider measures

The branch this builds on leaves main.js at 327,446 raw and 106,873 gzip
bytes, built with the same vite command from an export of its head. The
OpenAI-compatible server provider, its settings rows, its gate and failure
sentences and the panel's server wording add 3,293 raw and 895 gzip bytes,
which takes main.js to 330,739 and 107,768, over the 330,000 and 106,970
budgets. Each budget rises by its delta, to 333,293 and 107,865, so the 2,554
raw and 97 gzip bytes of headroom stay as they were. This is the first rise
of the raw budget. AGENTS.md now names both budgets.
Comment thread docs/scripts/screenshots.mjs Resolved
…nce per job

OpenRouter and OpenAI-compatible servers answer in OpenAI's verbose_json
shape, so both now read it through providers/verboseJson.ts: words when the
answer lists any, punctuated from its text when they carry none, else
segments as the { segments } PartTranscript that cues.ts times across parts.
The OpenAI-compatible provider no longer stores segments as words.

A server that refuses verbose_json, as OpenAI's API does for gpt-transcribe,
is asked for json for that part and every later part of the job, so each
later part is uploaded once instead of twice.
Whisper lists each word with its leading space and splits some words, so
"sci-fi" arrives as " sci" and "-fi". Reading words as separate cues saved
"sci -fi" in the note. A piece without a leading space now continues the
word before it. Lists of bare words, as OpenRouter's other models send,
are unchanged.
…ible' into docs/transcription-guide-update

# Conflicts:
#	.claude/skills/verify/net.mjs
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Deploying podnotes with  Cloudflare Pages  Cloudflare Pages

Latest commit: 7060f8f
Status: ✅  Deploy successful!
Preview URL: https://87e02f2b.podnotes.pages.dev
Branch Preview URL: https://docs-transcription-guide.podnotes.pages.dev

View logs

@chhoumann
chhoumann changed the base branch from feat/transcription-speaker-merge to feat/transcription-openai-compatible November 14, 2026 13:01
…rvers

The OpenRouter table and FAQ quoted a lab word error rate and a price,
and called Deepgram the pick for speed, none of which the code or a
provider page backs. The server settings shots now show the guide's
example address instead of the capture's random fixture port.
@chhoumann
chhoumann marked this pull request as ready for review November 14, 2026 14:49
Base automatically changed from feat/transcription-openai-compatible to master November 16, 2026 17:41
…guide-update

# Conflicts:
#	.claude/skills/verify/net.mjs
#	AGENTS.md
#	scripts/size-baseline.md
#	scripts/size.mjs
#	scripts/size.test.ts
#	src/services/TranscriptionService.test.ts
#	src/services/TranscriptionService.ts
#	src/services/transcription/audioSource.ts
#	src/services/transcription/providers/openaiCompatible.ts
#	src/services/transcription/providers/verboseJson.ts
#	src/services/transcription/speakers.ts
#	src/services/transcription/split.test.ts
#	src/services/transcription/split.ts
#	src/services/transcription/transcribe.ts
#	src/ui/PodcastView/TranscriptPanel.test.ts
#	src/ui/settings/PodNotesSettingsTab.test.ts
#	src/ui/settings/PodNotesSettingsTab.ts
Length caps apply to every format, Scribe v2 on OpenRouter fetches an episode by
address only up to 30 minutes, signed links are uploaded, a server address may
hold no user name or password, and Transcribe with your server stays on
offline.
@chhoumann

Copy link
Copy Markdown
Owner Author

FAIL
Verified head 7bc0d55 by an independent verifier (GPT 6 Astra).

  • The four transcript-note*.webp screenshots do not regenerate. Committed images show four "Walking as thinking" turns; regeneration produces two generic fixture sentences at 00:00:00 and 00:00:12. Desktop height changes from 780 to 492 px, phone from 946 to 514 px. screenshots.mjs:799 passes --turns, but net.mjs:224 ignores it and uses fixed text at lines 35-36. The other 12 images match labels and layout; 10 match pixels exactly.
  • transcripts.md:48 incorrectly says every transcribe button is disabled offline. TranscriptPanel.svelte:188 exempts the server. Verified in Obsidian with local Recordings/Family/Interview with grandma.m4a: offline server button enabled, both commands unavailable. Line 110 already describes the correct exception.
  • Audio-delivery claims need qualifications. mobile.md:84 promises no upload unless URL fetching fails, but transcribe.ts:79 uploads episodes over the model's duration cap, including Scribe v2 over 30 minutes. transcription-providers.md:69 incorrectly puts downloaded episodes in the upload-only category; audioSource.ts:35 still returns their eligible public URL, confirmed by a source probe. transcripts.md:86 also promises one request for ElevenLabs/Deepgram without qualifying upload caps; transcribe.ts:97 splits oversized uploads for every provider.
  • transcripts.md:91 and transcription-providers.md:76 and line 77 incorrectly say speaker numbers restart per part. cues.ts:84 numbers unmatched voices globally; a two-part probe produced 1, then 2, not 1, then 1. One person can receive different numbers. Also, faq.md:125 wrongly promises a missing-label notice for a single voice; transcribe.ts:169 requires zero labels, not one.
  • transcription-providers.md:81 through line 84 overstates catalog caching and fallback. registry.ts:137 caches successful reads in memory only, so failures and reloads can fetch again within a day. Line 101 selects the first currently offered model, not necessarily Grok. Probes confirmed two immediate failed catalog fetches and fallback to Scribe v2 when Grok is withdrawn.
  • transcripts.md:114 promises a saved chunk-error marker whenever a part fails. transcribe.ts:31 and line 111 instead abort the entire job for authentication, credit, model, privacy, rejected-request, or format failures, even after an earlier successful part. Qualify which failures preserve a partial note.
  • faq.md:133 misquotes the server-address notice. The actual notice includes "and with no user name or password" after https://, confirmed by clicking the button and by TranscriptionService.ts:147. faq.md:147 says "retries up to three times"; http.ts:81 allows three total attempts, hence at most two retries.
  • Verification passed with the requested fnm exec --using 22.23.2 command prefix: npm run build, node docs/scripts/screenshots.mjs, npm run docs:build, and npm run format:check. Runtime source/build inputs match master dc51763. Checked remaining provider/model, timestamp, punctuation, address, key, migration, sync/export, and upload-cap claims against source. Used isolated Obsidian 1.14.4 on Linux. Stopped the fixture server and Obsidian; dry-run reports no PIDs. Restored generated assets; working tree is clean.

…catalog

Restore the verify skill's net.mjs --turns option, which the transcript note
screenshots use; they regenerate byte-identical with it.
@chhoumann

Copy link
Copy Markdown
Owner Author

FAIL

Verified head 49c7c7484fa443ad4ca130e74ac371bbacec89f2 for documentation accuracy against PodNotes 2.25.0. src/ is identical to the published 2.25.0 tag and origin/master at dc51763c2fc5344b989d3c6bfc02855467dbce73. Read AGENTS.md and docs/STYLE.md before review. No branch edits or pushes.

Two factual qualifications remain:

  1. transcripts.md:86 still omits Scribe v2's 30-minute limit for the public-URL path. The sentence says OpenRouter transcribes a full public episode in one request when Scribe v2 is selected and OpenRouter can fetch the URL. URL fetchability is not sufficient. transcribe.ts:79 skips the URL path when the feed's duration exceeds model.maxSeconds, and openrouter.ts:15 sets that to 1,800 seconds for Scribe v2. The existing boundary tests at TranscriptionService.test.ts:1547 passed, confirming URL delivery at 1,800 seconds and device upload at 1,801 seconds. Add the duration qualification here, as already done on the provider page, so the long-episode guidance does not imply that public Scribe v2 episodes always avoid uploads and keep one set of speaker labels.

  2. transcripts.md:114 incorrectly groups an “unreadable answer” with failures that stop the whole job. An HTTP 2xx response that is not JSON becomes a server failure at http.ts:134. It is retried and then becomes a failed-part marker through transcribe.ts:111, allowing later parts to finish. A source probe using the actual sender, job loop, and cue conversion with fixture I/O produced Speech 1. [Error transcribing chunk 2] Speech 5. after five sends. Replace “an unreadable answer” with the specific fatal condition, repeated rejection of the requested response format. That format classification comes from HTTP 400 mentioning the format options in openaiCompatible.ts:72, and is retried as JSON at transcribe.ts:66 before ending the job if still refused. The FAQ already correctly describes non-JSON responses as server errors.

Recheck of the nine previous items:

  1. Corrected. net.mjs parses watch --turns <json> and uses those turns. A network-free probe of its generated watcher verified all four screenshot-seed turns at 0, 8, 19, and 25 seconds with their speaker IDs, and verified that re-watching installs replacement turns. git diff --stat origin/master...HEAD -- . ':!docs' lists only .claude/skills/verify/net.mjs.
  2. Corrected. transcripts.md:48 distinguishes offline cloud buttons from Transcribe with your server, matching TranscriptPanel.svelte:188 and :279. Both palette commands still require online status through commands.ts:283.
  3. The requested mobile duration qualifications, downloaded-public-episode behavior, and ElevenLabs/Deepgram one-request caps are corrected. Finding 1 covers the remaining Scribe v2 statement on the transcript page.
  4. Corrected. Both pages now describe new numbers for unmatched voices across parts, matching the episode-wide map in cues.ts:84.
  5. Corrected. faq.md:125 says no speaker tags, matching labels.size === 0 in transcribe.ts:169.
  6. Corrected. transcription-providers.md:81 describes successful in-memory caching for a day and retries after failed reads. Line 84 describes fallback to the first offered model, normally Grok. These match registry.ts:101 and :134 onward.
  7. The recoverable/fatal distinction is now present and the named authentication, credit, model, privacy, and rejected-audio cases match ENDS_THE_JOB. Finding 2 covers the remaining overbroad description of format.
  8. Corrected. The quoted server-address notice in faq.md:133 matches TranscriptionService.ts:147, including “and with no user name or password”.
  9. Corrected. faq.md:147 now says up to three total sends, matching MAX_SENDS = 3 and the one-minute retry-delay ceiling in http.ts:81.

Also checked the changed provider/model, timestamp, punctuation, settings visibility, credential, migration, sync/export, command, and panel claims against their source implementations.

Validation passed:

  • fnm exec --using 22.23.2 npm run docs:build. All internal links and all 112 legacy fragments resolve.
  • fnm exec --using 22.23.2 npm run format:check. Passed after npm ci installed the initially missing root dependencies.
  • fnm exec --using 22.23.2 npm run test:unit -- src/services/TranscriptionService.test.ts src/services/transcription/cues.test.ts src/settingsMigrations.test.ts src/settingsTransfer.test.ts. Type checking passed, and 269 tests passed across four files.

The requested fnm selector resolves to Node v22.23.4 on this host. No real API keys, provider network calls, or Obsidian runtime were used. Screenshots were not regenerated in this round. Working tree remains clean.

@chhoumann

Copy link
Copy Markdown
Owner Author

PASS

Reviewed head 7060f8f1cb665908e5d56ef8ab8c006c82ecb336 for documentation accuracy against released PodNotes 2.25.0. No remaining factual contradictions found in the changed docs pages.

Read AGENTS.md and docs/STYLE.md first. Checked out the requested commit. GitHub reports this as the PR head and 2.25.0 as the latest published release. git diff --exit-code 2.25.0 HEAD -- src/ passes. The complete diff from 49c7c748 contains only the two corrections in docs/src/content/docs/transcripts.md.

Both previous findings are resolved:

  1. transcripts.md:86 now qualifies the Scribe v2 public-URL request with a feed duration of 30 minutes or less. This matches the duration gate in transcribe.ts:79 and Scribe v2's 1,800-second cap in openrouter.ts:15. The existing 1,800/1,801-second boundary tests passed.
  2. transcripts.md:114 now names an OpenAI-compatible server refusing both requested response formats. This matches the HTTP 400 format classification in openaiCompatible.ts:58, the JSON retry in transcribe.ts:66, and fatal handling at lines 31 and 111. The existing tests for JSON fallback, refusal of both formats, and subsequent parts using JSON passed. Non-JSON HTTP 2xx responses remain retried server failures through http.ts:134, consistent with the FAQ.

Rechecked the previous round's nine items against this head:

Item Result and evidence
Screenshot fixture turns Still correct. .claude/skills/verify/net.mjs:237 parses --turns, watchSource uses those turns, and line 80 restores the previous watcher before replacement. docs/scripts/screenshots.mjs:802 passes the seed's four turns at 0, 8, 19, and 25 seconds. These files are unchanged since the previous review. This round rechecked the wiring in source, without regenerating screenshots.
Offline buttons and commands Still correct. transcripts.md:48 matches TranscriptPanel.svelte:188 and :279. Both palette commands require online status at commands.ts:283.
URL delivery, downloads, and caps Still correct. transcription/audioSource.ts checks public feed membership and the episode URL independently of a local download. transcribe.ts:79 applies duration limits. ElevenLabs and Deepgram profiles retain their documented one-request caps. The Scribe v2 qualification is now consistent across pages.
Speaker numbers across parts Still correct. transcription/cues.ts:84 assigns episode-wide numbers to distinct part/speaker keys, with matched voices sharing a number. The docs correctly describe new numbers for unmatched voices.
No speaker tags Still correct. faq.md:125 matches labels.size === 0 at transcribe.ts:169.
Catalog caching and fallback Still correct. transcription-providers.md:81 and :84 match registry.ts's successful in-memory one-day cache, retry after failed reads, and fallback to the first offered model.
Recoverable versus fatal failures Correct after the second fix above. The fatal list matches ENDS_THE_JOB; recoverable part failures produce markers, and an all-failed job saves no note.
Server-address notice Still correct. faq.md:133 matches TranscriptionService.ts:147, including the prohibition on a user name or password.
Retry count Still correct. faq.md:147 matches MAX_SENDS = 3 and the 60,000 ms retry-delay ceiling in http.ts.

Also checked the changed provider/model descriptions, timestamp rendering, punctuation handling, server address normalization, settings visibility and defaults, credentials, migration, sync/export, command, and player-panel claims against src/. No additional findings.

Validation passed:

  • fnm exec --using 22.23.2 npm ci installed the initially missing root dependencies.
  • fnm exec --using 22.23.2 npm run docs:build passed. All internal links and all 112 legacy fragments resolve.
  • fnm exec --using 22.23.2 npm run format:check passed.
  • fnm exec --using 22.23.2 npm run test:unit -- src/services/TranscriptionService.test.ts src/services/transcription/cues.test.ts src/settingsMigrations.test.ts src/settingsTransfer.test.ts src/ui/PodcastView/TranscriptPanel.test.ts src/ui/settings/PodNotesSettingsTab.test.ts passed type checking and all 353 tests across six files.

The requested fnm selector resolves to Node v22.23.4 on this host. No real API keys or provider network calls were used. This was a source review with mocked unit/component tests, not a new Obsidian runtime or visual verification. No tracked files were changed, and nothing was pushed. The working tree remains clean.

@chhoumann
chhoumann merged commit 2f9e8d7 into master Nov 17, 2026
18 checks passed
@chhoumann
chhoumann deleted the docs/transcription-guide branch November 17, 2026 22:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant