Skip to content

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

Open
chhoumann wants to merge 59 commits into
masterfrom
docs/transcription-guide
Open

chhoumann wants to merge 59 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 multi-provider transcription with provider selection, server setup, and docs

  • Adds ElevenLabs, OpenRouter, and OpenAI-compatible server providers alongside the existing OpenAI and Deepgram. A new registry (registry.ts) resolves the saved provider, model, and server URL into a runnable choice, and a rewritten TranscriptionService delegates audio splitting, retries, speaker labeling, and request sending to the new transcribe.ts module.
  • Reworks the Transcripts settings tab (PodNotesSettingsTab.ts) with provider, model, server-address, credential, and speaker-label rows, and adds credential metadata for all five kinds in Credentials.ts.
  • Migrates pre-2.25.0 settings: migrateTranscriptSettings in settingsMigrations.ts infers a provider from legacy diarization choices and OpenAI-key presence, and the codec/import logic in settingsTransfer.ts and settingsCodec.ts handles all registered credential kinds.
  • Rewrites the transcripts documentation for provider choice, keys, server setup, and a 2.25.0 update guide (transcripts.md).
  • Risk: default provider changes to ElevenLabs with speaker labels enabled (constants.ts); getEpisodeAudioBuffer and readVaultAudio in downloadEpisode.ts no longer return a basename field; the diarization provider is no longer sanitized during transcript migration, and the raw bundle budget rises to 334,096 bytes (size.mjs).

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.

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.
…an episode

OpenRouter takes at most 18 MB and 1,800 s a request, so a long upload goes
in parts, and each part numbers its speakers on its own. On the 54 min E231
in three parts, those labels agreed with a whole-file run 0.344 of the time.

After the parts, Grok STT 2.0 now gets one more request: a reel with a clip
of each part's every speaker label, from its longest turn of at least 2.6 s,
0.2 s in and at most 9 s, cut at MP3 frame starts and joined by 1.5 s of
silent frames. Each speaker the reel's answer names is credited with the
seconds it speaks over each clip, part labels whose clips go to one speaker
become one, and a label with no clip stays its own. Measured through
OpenRouter with Grok, this took E231 from 0.344 to 0.995 against a
whole-file run, and NPR's Planet Money in 300 s parts from 0.367 to 0.949
against its human transcript, beside 0.942 for whole-file Grok.

A model profile turns the reel on with mergeSpeakers. Scribe v2 stays off,
because its reel heard the 10 voices of a Planet Money episode as 4, and so
does MAI-Transcribe 2, which is not measured. Audio decoded to WAV parts
sends no reel. A reel that fails keeps the parts' labels and the warning
that they restart in each part, which the note no longer gets otherwise.
…measures

The branch this builds on leaves main.js at 106,065 gzip bytes, built with
the same vite command from an export of its head. Cutting the reel, merging
labels from its answer and the mergeSpeakers profile add 808, which takes it
to 106,873 and over the 106,162 budget. The budget rises by those 808 bytes
to 106,970, so the 97 bytes of headroom stay as they were.
… a model would

The fixture provider answered every OpenRouter request with the same two
speakers, so a reel's answer could not say which part labels are one voice.
It now decodes Grok's MP3 uploads with Chromium's decoder and hears a tone
under 500 Hz as one speaker and a higher tone as another, numbered in the
order they sound in each request. The log records each upload's decoded
seconds and the speakers heard, and audio the decoder refuses is answered
with a 400. Multipart and WAV uploads keep the fixed answer.

The transcripts recipe writes a 70 min MP3 of two tones that take turns
every 45 s, whose second part starts with the high tone, and checks three
part requests, one 61.56 s reel and one number per voice in the note.
A provider can offer models with and without speaker labels, so the notice
names the model, as the Speaker labels row already does.
… OpenRouter

Voxtral answers timed segments and no words, so a segments answer becomes
cues timed from the episode's start, as words do. Both models take parts of
12 MB and 900 s, because 20 MB took 33 to 35 s to answer.
…t and save timed notes

The OpenRouter stub answers them as they were measured: Voxtral with segments,
or a 400 when asked for word times, and Qwen3 ASR with words and no speakers.
… ASR measure

The branch this builds on leaves main.js at 106,873 gzip bytes, built with the
same vite command from an export of its head. The two OpenRouter models and
reading Voxtral's segment times add 211, which takes it to 107,084 and over
the 106,970 budget. The budget rises by those 211 bytes to 107,181, so the 97
bytes of headroom stay as they were.
…were measured

The fixture provider answers Voxtral with segments, or a 400 when asked for
word times, and Qwen3 ASR with words and no speakers. The transcripts recipe
covers both on a 70 min MP3.
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: a96df75
Status: ✅  Deploy successful!
Preview URL: https://5799e1ab.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

This branch has not been deployed

No deployments
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