dictawhisper 0.1.14 → 0.1.16

package/README.md

@@ -1,18 +1,24 @@
 <p align="center">
-  <img src="site/static/logo.png" alt="DictaWhisper logo" width="128" />
+  <img src="https://dictawhisper.com/logo.png" alt="DictaWhisper logo" width="128" />
 </p>
 
 # DictaWhisper
 
-**A local voice journal.** Record in the browser, drop a file, or (optionally) sync a phone folder. Transcribe on your GPU with [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Clean the note with [ollanet](https://ollanet.dev). The `.json` next to each recording is the journal.
+**A local voice journal.** Record in the browser, drop a file, or (optionally) sync a phone folder. Transcribe locally with **Bark Pro** (English, default) or [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Clean the note with [ollanet](https://ollanet.dev). The `.json` next to each recording is the journal.
 
-Install from a Git checkout ([below](#from-a-checkout)). Starting with 0.1.11, the npm package ships compiled JavaScript and the inbox UI. Earlier releases through 0.1.10 do not start from npm installations. Python and faster-whisper remain separate prerequisites.
+Install from a Git checkout ([below](#from-a-checkout)). Starting with 0.1.11, the npm package ships compiled JavaScript and the inbox UI. Earlier releases through 0.1.10 do not start from npm installations. The selected model and its Python runtime remain separate prerequisites.
 
 **Docs:** [dictawhisper.com/docs](https://dictawhisper.com/docs) · **Site:** [dictawhisper.com](https://dictawhisper.com)
 
+## Find the note after you record it
+
+![DictaWhisper Inbox with a searchable library on the left and the selected Kitchen repair plan transcript, timestamps, audio controls, and MayDos tab on the right.](https://raw.githubusercontent.com/Catalyst-Forge-LLC/dictawhisper/main/site/static/screenshots/dictawhisper-inbox.jpg)
+
+Actual Inbox showing three fictional entries. The transcript, timestamps, and action suggestions are synthetic fixture data; this capture does not demonstrate transcription or cleanup quality. Select an entry to read it beside the library, search for it later, or review its suggested actions in MayDos.
+
 ## Before you clone
 
-Exercised path: Windows, Node 22.13+ (checkout scripts use `--experimental-strip-types`), pnpm, Python with [faster-whisper](https://github.com/SYSTRAN/faster-whisper), and an NVIDIA GPU with CUDA. `ffmpeg` is required when denoise is on. macOS and Linux are unverified. CPU mode works and is slow. Cleanup via [ollanet](https://ollanet.dev) is optional.
+Exercised path: Windows, Node 22.13+ (checkout scripts use `--experimental-strip-types`), pnpm, and an NVIDIA GPU with CUDA. Bark Pro uses an isolated Python 3.11 / CUDA 12.8 / BF16 runtime; Whisper uses Python with [faster-whisper](https://github.com/SYSTRAN/faster-whisper). `ffmpeg` and `ffprobe` are required for audio assessment and preparation, including unfiltered mode. macOS and Linux are unverified. Bark CPU mode is available but unverified; Whisper CPU mode is slower. Cleanup via [ollanet](https://ollanet.dev) is optional.
 
 ## From a checkout
 
@@ -21,11 +27,13 @@ git clone https://github.com/Catalyst-Forge-LLC/dictawhisper.git
 cd dictawhisper
 cp config.example.json config.json
 pnpm install
+# Set up Bark Pro first (PowerShell; use your Python 3.11 path):
+# & ./scripts/setup-bark.ps1 -Python C:/path/to/Python311/python.exe
 pnpm run doctor
 pnpm dev
 ```
 
-Ready signal: `pnpm run doctor` exits 0, or only warnings remain. Then open [http://localhost:7777](http://localhost:7777). Point `whisper.python` at the interpreter that has CUDA Whisper. Cleanup host and model are optional; raw transcripts still work.
+Ready signal: `pnpm run doctor` exits 0, or only warnings remain. Then open [http://localhost:7777](http://localhost:7777). For Whisper instead, set `transcription.model` to `large-v3` or `turbo` and point `whisper.python` at its interpreter. Once running, change the default in **Settings → Transcription**. Cleanup host and model are optional; raw transcripts still work.
 
 LocalSlip is optional. `pnpm dev` and `pnpm serve` read existing `dictawhisper` and `dictawhisper-api` claims when available; they do not create claims. Without LocalSlip, the UI uses 7777 and the API uses `http.port` (8008 by default). Startup names both endpoints and gives the UI proxy the same API port. Claim ports separately if you want named assignments.
 
@@ -40,38 +48,45 @@ Hit Record, or drag an audio file onto the page. Flags, HTTP, MCP, and `retransc
 
 ## What you get
 
-Files are the database. Each note is the recording plus a neighboring `.json`. The Whisper model stays loaded. Audio and transcript files stay on this computer. Cleanup sends transcript text only to the host in `ollanet.machine`, and is skipped when that is empty. Search indexing embeds note text on this computer by default; it goes to another host only if you set `journal.embedHost` (`machine`, a host name, or `any`). With no embedding model on an allowed host, or with `journal.search` set to `lex`, nothing is embedded and search matches words only; doctor says which. The inbox is loopback by default; `http.tailscale` puts the same page on your tailnet. Playback follows cleaned paragraphs using Whisper word times. If cleanup is skipped or fails, the inbox shows **raw only** or **cleanup failed**, and **Retry** is available. Transcription itself still needs faster-whisper.
+Files are the database. Each note is the recording plus a neighboring `.json`. Bark loads per recording; Whisper keeps a worker loaded between its jobs. Audio and transcript files stay on this computer. Cleanup sends transcript text only to the host in `ollanet.machine`, and is skipped when that is empty. Search indexing embeds note text on this computer by default; it goes to another host only if you set `journal.embedHost` (`machine`, a host name, or `any`). With no embedding model on an allowed host, or with `journal.search` set to `lex`, nothing is embedded and search matches words only; doctor says which. The inbox is loopback by default; `http.tailscale` puts the same page on your tailnet. Playback follows cleaned paragraphs using the transcription engine’s word timing estimates. If cleanup is skipped or fails, the inbox shows **raw only** or **cleanup failed**, and **Retry** is available. Transcription requires the selected engine’s local runtime.
+
+## Capture and Activity
+
+Record opens the compact capture panel and requests the microphone. Stop keeps a draft in the current tab; Save recording sends it, and Discard releases it without saving. Failed saves retain playback, download, and retry. Download unsaved audio before leaving the tab if you need to keep it.
+
+Import accepts multiple WebM, MP3, M4A, WAV, or OGG files up to 80 MiB each, with two simultaneous uploads and per-file outcomes. Saved means the server acknowledged the audio bytes; transcription and cleanup continue separately. Imports never overwrite an existing audio file or sidecar. Stable upload identities let retries reconcile an unknown previous outcome.
+
+Activity shows actual processing stages, sync eligibility deadlines, failures with specific recovery actions, recent completions, and bulk-job progress. Open a newly saved entry there to play it before its transcript is ready. System diagnostics run when expanded or explicitly refreshed. After a server restart, files still waiting to finish syncing are rechecked automatically against their latest write time. Queued or running processing appears as Interrupted and requires explicit resume; existing transcripts remain readable.
 
-## Browsing and MayDos
+## Read, search, and listen
 
 Select a card to read its full entry in the right pane. The entry list and detail pane scroll separately. On narrow screens, **Back to entries** returns to the cards. Hover over a transcript passage (or focus it with the keyboard) to copy its text; its timestamp still plays the audio.
 
 Library and search results load in pages of 50. **Load more** keeps the current reading position, and reader **Next** continues onto the next page. Word searches show an exact matching count and sort the full matching set before paging. Meaning searches label their bounded ranked results; **Search words only** switches to exhaustive word matching. If results change or a ranked snapshot expires, **Refresh results** keeps the selected entry open.
 
-HTTP callers can opt into the page contract with `GET /notes/search?page=1`: `items`, `total`, `countKind` (`exact` or `ranked`), `hasMore`, `nextCursor`, and actual `mode`. Ranked responses also include `candidateLimit` (500) and `expiresAt` (60 seconds). Pass `cursor` with the same query/filter/sort parameters to continue. Cursor errors return `invalid_cursor` (400) or `cursor_expired` (409); refresh by omitting the cursor. Without `page=1`, the legacy `{ hits, count }` response remains available; its `count` is the returned array length, not a corpus total. Existing MCP search keeps its array response.
+## Improve difficult recordings
 
-Cleanup also extracts **MayDos**: possible actions stated in the transcript, including tentative intentions. Each starts as **Suggested** and can become **Selected**, **Done**, or **Dismissed**. Its source quote and available audio timing stay with it. Re-extraction preserves IDs and your status choices, keeping decided items even when the model omits them. Filter entries by any MayDos or a particular status.
+New imports automatically measure audio levels over time, then keep adequate audio unfiltered, boost quiet speech, or level uneven volume. Preparation preserves pauses and timestamps in a PCM WAV working copy. The configured model is used (default **Bark Pro**) with speech gating off to include faint speech. Sidecars record preparation, source identity, model and pipeline version. Suspect passages have listening signals; Whisper can also produce up to three short alternate passes. The reader's **Transcription details** disclosure exposes the evidence. These signals are not an accuracy score. Automatic noise reduction remains off; the manual preset is available below. Set `audio.preprocess` to false for unfiltered preparation.
 
-Existing entries have an **Extract MayDos** action in their detail pane. **Tools → MayDo backfill** processes the library serially using the configured cleanup host and model. Optionally restrict it to a year. It skips entries already extracted from unchanged text unless refresh is enabled, shows progress and errors, and stops after the current entry when requested. Starting it again skips completed work. Progress is held in memory; results are saved in the sidecars.
+For quiet, uneven, or noisy recordings, use the reader's **More → Improve audio & retranscribe…** action. Prepare an audio preview from the original when available, switch between original and enhanced at the same position, then create a candidate with **Bark Pro**, **Whisper large-v3** or **turbo**. The action starts with your saved default. Review and accept the candidate or keep your current version. Preparation uses FFmpeg and a lossless working copy without trimming silence. Your title, stars, tags, MayDo decisions, and original recordings remain saved. Existing MayDo timings are cleared until refreshed against the new transcript. Reopen the action to check progress or undo acceptance before further transcript changes. Readable cleanup is a separate action after acceptance. See [audio improvement behavior and verification](docs/AUDIO_IMPROVEMENT.md).
 
-Sidecars store a `mayDos` array (ID, title, verb, source quote, audio start/end, status, and timestamps), plus `mayDoExtraction` version, source hash, model, host, and timestamp. Failures set `mayDoError` without replacing existing actions. ExoMetaCortex synchronization is a future step.
+## Retranscribe an existing library
 
-<!-- xfacts-label -->
+Open **Settings → Transcription → Retranscribe library** (also in Data and maintenance). Select a year or all years, Bark Pro, large-v3 or turbo, and older-pipeline entries, flagged entries, or all entries. **Preview eligible entries** reads sidecars and source metadata without running models. Already-current entries and missing sources are accounted for. Prepared audio and saved versions require extra disk space.
 
-## xFacts label
+Choose **Review before replacing**, or explicitly choose **Replace entries without review signals** to update unflagged entries with saved previous versions while holding flagged candidates for review. Optionally queue readable text, tags and MayDos for replacements. Then Start the previewed batch. Progress and candidate review are available in **Activity**; only 50 result summaries load at a time. Stop finishes the current entry. Restart never automatically starts a saved batch: Resume continues its checkpoints and Retry failed only targets failures. Current titles, stars, tags and MayDo decisions are retained. Undo is conditional on no later transcript/cleanup changes; earlier sidecars remain saved even when automatic Undo is blocked. A first import has no earlier transcript to undo.
 
-- **AppFacts:** [viewer](https://appfacts.dev/v#af1.eNpVkltr3DAQhf-KmKcWtGvyqqeASaG5lFDnrZQwK0-8imVJaMbemGX_e5H31n0Tc74ZnTnSHiYwdxoCDgQGWmcFd1vHiTJokDmV6o42ClNS35rm93fQwIIyMhhAK24i0OCdpcCFffn5diRsD2YPHkM3YleUtzlRY7NLotUjTng-v86yjQE05DGIW2z8ii2tP_k_7SPjQLuYezDQTOSFnpxo9fCVMjEvN87eha7IddNoVTcNaEAHBj6QhfLqtJZW0XsMJKDBxmEYg7MoLgYwwNH2JGsX4aChpcRg_uyhKPe8XPrJVe9KZypzcwxCoVVXcwd9xOniq4AbtH3hmPJE-QLd-jqxkjHwkoyLQVHoXKBLx9V5Qb0flF0siEo5WmIuCZzh6zJHPBP6VQlY3a595u-H2JJfBn5JylGijb7itj_1v9Sv6lxWPKYUs8Dhr4bN6HxbHjuh7bGj9wEDdpTBQAppKFlmSpGdxDyDga1IYlNVnZPtuFnbOFQ1CvqZZfUj5o5Wz891dfMVD_8Ay7foKw) · [raw](https://github.com/Catalyst-Forge-LLC/dictawhisper/blob/main/APP_FACTS.md)
-- **ToolFacts:** [viewer](https://toolfacts.dev/v#tf1.eNrFlE1v2zAMhv-KoHM-1h2zY4YCA1JgQAfsUBSBKjG2WltyKdppEOS_76XSYB9Yz7kksfiSLx_G1NFOdnUzs8n1ZFf2a_TifraxDMTmbv3d3BNPxHZmA03UZRxDtXbiukMRc5u5IQQhKTEnhD4tbhafcVLEyVhw4LzESTVd9JSKmtx9-4Hnl5gCHno_zMvFhMckURs5WnojP8q5aJe96-YDZ0-lQCbsUhkyC2JFQsz2NLOeKRDSXVc0n-l1jDiyq4dHRKlhzUVAqKOehA9ITjlRZSsSk1O38q6XnLXOw_EymaCT2Z8nsy3k2LeKGQNtabcjLwrL5IJikEMUXrvYUcGgqNdOPcan4USyz_zy2_-djFBih_YJ_qjbD1kAZFfCI0E08pDr_O6ru5kyJmoSRMU8HQxKhjIz4hp8Zjbqrb1_MUwycipmcNIiFhwyLkKXgnGmtBimGZimSHsM8__UDclW7a7FfUsCbKRWaGXWNrzjSqbMY4qvIyKu_IPuO3KJghF6k8qs9B-CdrHItiquRLpBA7VFE5ORlsxzBobrzD4C1GesycfdM3ktes3WE-1Jv-q7uYuM37XzPOiOgQNs9W8I7mCwzA3p6yq4RezpcWbb3NPgGi3XigxltVz-Sbjwua8gsIyS6yZfdA1sxidVLC-31LzeUvPNZv1XlXqPjMljG8IZ4_QLRYvHeA) · [raw](https://github.com/Catalyst-Forge-LLC/dictawhisper/blob/main/TOOL_FACTS.md)
+## Choose the default model
 
-## Capture and Activity
+**Settings → Transcription → Default transcription model → Save default model** chooses Bark Pro (English), Whisper large-v3 (multilingual) or Whisper turbo. Bark Pro is the default when `transcription.model` is absent. Saving persists to the loaded config and takes effect for the next transcription without restarting. Imports, browser captures, Activity retries and the retranscribe CLI use that choice. Improvement attempts and new batches start with it; running jobs and saved batch scopes retain their selected model. `DICTA_TRANSCRIPTION_MODEL` can explicitly override and lock the choice for a process; `WHISPER_MODEL` no longer selects the default engine.
 
-Record opens the compact capture panel and requests the microphone. Stop keeps a draft in the current tab; Save recording sends it, and Discard releases it without saving. Failed saves retain playback, download, and retry. Download unsaved audio before leaving the tab if you need to keep it.
+Bark has native estimated word and passage timing. Timed candidates—including earlier comparison-only candidates—can be accepted with **Use new audio & transcript**, followed by optional Readable cleanup or Undo. Untimed candidates remain available for listening and export but cannot replace an entry. A normal import without usable timing fails safely and retains the audio for retry; select Whisper in Settings if needed. No automatic fallback or library-wide retranscription happens when you change the default.
 
-Import accepts multiple WebM, MP3, M4A, WAV, or OGG files up to 80 MiB each, with two simultaneous uploads and per-file outcomes. Saved means the server acknowledged the audio bytes; transcription and cleanup continue separately. Imports never overwrite an existing audio file or sidecar. Stable upload identities let retries reconcile an unknown previous outcome.
+Install once in PowerShell with `& ./scripts/setup-bark.ps1 -Python 'C:/path/to/Python311/python.exe'`, then restart DictaWhisper. The separate `.venv-bark` uses pinned PyTorch/Transformers and model weights; it does not change the Whisper runtime. The exercised setup uses NVIDIA CUDA/BF16. Full setup, limitations and test evidence: [Bark setup and behavior guide](docs/BARK_EXPERIMENT.md).
 
-Activity shows actual processing stages, sync eligibility deadlines, failures with specific recovery actions, recent completions, and bulk-job progress. Open a newly saved entry there to play it before its transcript is ready. System diagnostics run when expanded or explicitly refreshed. After a server restart, unfinished work appears as Interrupted and requires explicit resume; existing transcripts remain readable. Activity history is stored in an internal `.dictawhisper/activity.json` beneath the configured index's directory. Resumable bulk backfill is tracked separately in the UX upgrade spec.
+## Review MayDos and extract older entries
 
-## MayDo review and backfill
+Cleanup also extracts **MayDos**: possible actions stated in the transcript, including tentative intentions. Each starts as **Suggested** and can become **Selected**, **Done**, or **Dismissed**. Its source quote and available audio timing stay with it. Re-extraction preserves IDs and your status choices, keeping decided items even when the model omits them. Filter entries by any MayDos or a particular status.
 
 The MayDos view shows entries with Suggested or Selected actions by default. Cards and reader tabs distinguish active actions from all saved actions. Open the MayDos tab to Select, Mark done, Reopen, or Restore an action; More offers every status, and Undo is available for five seconds. Source quote expands to selectable text and Copy; Play source appears only when timing is grounded.
 
@@ -79,7 +94,15 @@ Extract again refreshes suggestions while retaining stable IDs and selected, com
 
 Use **MayDos → More → Extract from older entries** or **Tools** for backfill. Preview the scope and configured model, then Start. Unchanged entries are skipped by default. Activity and the MayDos view expose progress and recovery. Stop finishes the current entry; Resume continues saved scope; Retry failed processes only failures. Restarted work shows Interrupted and requires explicit Resume. Closing a panel does not stop extraction.
 
-API clients retain `mayDoCount` and numeric `skipped` compatibility. Summaries also expose `mayDoTotalCount`, `mayDoStatusCounts`, and `skipReasons`. `POST /tools/may-dos/backfill` accepts `action: start | stop | resume | retry_failed`, plus `id` for stale-job protection; Start accepts `year` and `refresh`. `GET /notes/may-dos/capabilities` reports configuration availability without calling the model.
+Backfill scope and acknowledged outcomes are saved on disk; extracted actions remain in each entry’s sidecar. Resume continues unfinished work and retries failed entries from that saved scope. Retry failed targets failures only. If progress cannot be saved, the job stops with a storage error so you can repair it before continuing.
+
+## Recover entries and check settings
+
+Reader More → Move to Trash waits for a verified whole-entry bundle receipt, then offers eight-second Undo. Settings → Data and maintenance restores later; collisions keep both. Replacement requires a preview and saves the existing bundle in Trash. Assign recording date moves all variants together and records confirmed date provenance. New entries and edits receive stable IDs; explicit legacy backfill is available in maintenance.
+
+Settings shows effective folders, models, processing destinations, search coverage, and MCP configuration. The default transcription model is editable here and saves immediately. Edit the loaded file and restart for other configuration options. Maintenance includes scoped MayDo extraction, reviewed cleanup retries, tag merge preview/apply, and check-only audio scanning with separate reviewed marking. Help follows search, reading/listening, capture, MayDos, and recovery tasks. On small screens access Help through Settings. No ExoMetaCortex synchronization is active.
+
+For HTTP pagination, sidecar fields, and backfill actions, see the [HTTP reference](https://dictawhisper.com/docs/http).
 
 ## Development
 
@@ -92,14 +115,15 @@ pnpm site:dev
 
 Site (FilePress + docs mount): `pnpm --dir site ship`
 
-## License
+<!-- xfacts-label -->
 
-MIT · [Catalyst Forge LLC](https://www.catalystforge.com)
+## xFacts label
 
-[See the rest of the Catalyst Forge shelf.](https://catalystforge.com/tools/)
+- **AppFacts:** [viewer](https://appfacts.dev/v#af1.eNpVkltr3DAQhf-KmKcWtGvyqqeASaG5lFDnrZQwK0-8imVJaMbemGX_e5H31n0Tc74ZnTnSHiYwdxoCDgQGWmcFd1vHiTJokDmV6o42ClNS35rm93fQwIIyMhhAK24i0OCdpcCFffn5diRsD2YPHkM3YleUtzlRY7NLotUjTng-v86yjQE05DGIW2z8ii2tP_k_7SPjQLuYezDQTOSFnpxo9fCVMjEvN87eha7IddNoVTcNaEAHBj6QhfLqtJZW0XsMJKDBxmEYg7MoLgYwwNH2JGsX4aChpcRg_uyhKPe8XPrJVe9KZypzcwxCoVVXcwd9xOniq4AbtH3hmPJE-QLd-jqxkjHwkoyLQVHoXKBLx9V5Qb0flF0siEo5WmIuCZzh6zJHPBP6VQlY3a595u-H2JJfBn5JylGijb7itj_1v9Sv6lxWPKYUs8Dhr4bN6HxbHjuh7bGj9wEDdpTBQAppKFlmSpGdxDyDga1IYlNVnZPtuFnbOFQ1CvqZZfUj5o5Wz891dfMVD_8Ay7foKw) · [raw](https://github.com/Catalyst-Forge-LLC/dictawhisper/blob/main/APP_FACTS.md)
+- **ToolFacts:** [viewer](https://toolfacts.dev/v#tf1.eNrFlE1v2zAMhv-KoHM-1h2zY4YCA1JgQAfsUBSBKjG2WltyKdppEOS_76XSYB9Yz7kksfiSLx_G1NFOdnUzs8n1ZFf2a_TifraxDMTmbv3d3BNPxHZmA03UZRxDtXbiukMRc5u5IQQhKTEnhD4tbhafcVLEyVhw4LzESTVd9JSKmtx9-4Hnl5gCHno_zMvFhMckURs5WnojP8q5aJe96-YDZ0-lQCbsUhkyC2JFQsz2NLOeKRDSXVc0n-l1jDiyq4dHRKlhzUVAqKOehA9ITjlRZSsSk1O38q6XnLXOw_EymaCT2Z8nsy3k2LeKGQNtabcjLwrL5IJikEMUXrvYUcGgqNdOPcan4USyz_zy2_-djFBih_YJ_qjbD1kAZFfCI0E08pDr_O6ru5kyJmoSRMU8HQxKhjIz4hp8Zjbqrb1_MUwycipmcNIiFhwyLkKXgnGmtBimGZimSHsM8__UDclW7a7FfUsCbKRWaGXWNrzjSqbMY4qvIyKu_IPuO3KJghF6k8qs9B-CdrHItiquRLpBA7VFE5ORlsxzBobrzD4C1GesycfdM3ktes3WE-1Jv-q7uYuM37XzPOiOgQNs9W8I7mCwzA3p6yq4RezpcWbb3NPgGi3XigxltVz-Sbjwua8gsIyS6yZfdA1sxidVLC-31LzeUvPNZv1XlXqPjMljG8IZ4_QLRYvHeA) · [raw](https://github.com/Catalyst-Forge-LLC/dictawhisper/blob/main/TOOL_FACTS.md)
 
-## Recovery and effective settings
+## License
 
-Reader More → Move to Trash waits for a verified whole-entry bundle receipt, then offers eight-second Undo. Settings → Data and maintenance restores later; collisions keep both. Replacement requires a preview and saves the existing bundle in Trash. Assign recording date moves all variants together and records confirmed date provenance. New entries and edits receive stable IDs; explicit legacy backfill is available in maintenance.
+MIT · [Catalyst Forge LLC](https://www.catalystforge.com)
 
-Settings shows effective folders, models, processing destinations, search coverage, and MCP configuration. Configuration is read-only here: edit the loaded file and restart. Maintenance includes scoped MayDo extraction, reviewed cleanup retries, tag merge preview/apply, and check-only audio scanning with separate reviewed marking. Help follows search, reading/listening, capture, MayDos, and recovery tasks. On small screens access Help through Settings. No ExoMetaCortex synchronization is active.
+[See the rest of the Catalyst Forge shelf.](https://catalystforge.com/tools/)

package/config.example.json

@@ -13,6 +13,9 @@
     "recursiveYears": true,
     "createMissingRoots": false
   },
+  "transcription": {
+    "model": "bark-pro"
+  },
   "whisper": {
     "python": "python",
     "model": "large-v3",

package/dist/apiRoutes.js

@@ -1,4 +1,7 @@
 import { ollanetIsConfigured } from "./lib/ollanetReadyLib.js";
+import { audioRescueRoutes } from "./audioRescueRoutes.js";
+import { createTranscriptionBatchRoutes } from "./transcriptionBatchRoutes.js";
+import { getTranscriptionBatch } from "./lib/transcriptionBatchLib.js";
 import multer from 'multer';
 import { process, countStatus, getTranscriptionFilename, listNoteSummaries, patchTranscription, readTranscription, skipCleanup, emitNotesIndex } from "./lib/transcriptionLib.js";
 import { journalStats, journalTags, journalYears, listInboxNotes, notesIndexPayload, searchJournalIndex, searchJournalPage, } from "./lib/journalService.js";
@@ -23,6 +26,7 @@ import { BundleError, listTrash, moveToTrash, previewRestore, restoreTrash, purg
 import { organizationPreview, organizeEntry } from "./lib/entryOrganizationLib.js";
 import { backfillEntryIds } from "./lib/entryIdentityLib.js";
 import { effectiveSettings } from "./lib/settingsLib.js";
+import { createTranscriptionSettingsRoutes } from "./settingsRoutes.js";
 import { rebuildJournalIndex } from "./lib/journalService.js";
 const upload = multer({
     storage: multer.memoryStorage(),
@@ -52,6 +56,9 @@ function requireAllowedFile(req, res) {
     return allowed.path;
 }
 export const apiRoutes = [
+    ...createTranscriptionSettingsRoutes(),
+    ...audioRescueRoutes,
+    ...createTranscriptionBatchRoutes(),
     { path: '/tools/probe/mark', method: 'POST', handler: async (req, res) => { try {
             res.json(await markReviewedAudio(req.body?.files));
         }
@@ -110,7 +117,7 @@ export const apiRoutes = [
             res.json({ found: Boolean(item), item });
         } },
     { path: '/notes/activity', method: 'GET', handler: (_req, res) => {
-            res.json({ ...activity.snapshot(), mayDoBackfill: getMayDoBackfill(), queues: { transcription: { queued: q.transcription?.length() || 0, running: q.transcription?.running() || 0 }, cleanup: { queued: q.processing?.length() || 0, running: q.processing?.running() || 0 } } });
+            res.json({ ...activity.snapshot(), mayDoBackfill: getMayDoBackfill(), transcriptionBatch: getTranscriptionBatch().summary(), queues: { transcription: { queued: q.transcription?.length() || 0, running: q.transcription?.running() || 0 }, cleanup: { queued: q.processing?.length() || 0, running: q.processing?.running() || 0 } } });
         } },
     { path: '/notes/activity/retry', method: 'POST', handler: async (req, res) => {
             const item = activity.byId(String(req.body?.id || ''));
@@ -187,6 +194,7 @@ export const apiRoutes = [
                 host: config.http.host,
                 port: config.http.port,
                 whisper: resolveWhisperModel(),
+                transcription: report.transcription,
                 whisperWorker: report.whisper.worker,
                 device: report.whisper.device,
                 ollanet: {

package/dist/audioRescueRoutes.js

@@ -0,0 +1,61 @@
+import { audioRescue } from "./lib/audioRescueService.js";
+import { audioContentType } from "./lib/audioLib.js";
+const failure = (res, error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    res.status(message.includes('outside configured watch roots') ? 403 : 409).json({ error: message });
+};
+export function createAudioRescueRoutes(service = audioRescue) {
+    return [
+        { path: '/notes/audio-improvement/summaries', method: 'POST', handler: (req, res) => {
+                const files = req.body?.files;
+                if (!Array.isArray(files) || files.length > 100 || files.some(file => typeof file !== 'string' || file.length > 4096)) {
+                    res.status(400).json({ error: 'Choose up to 100 entry paths.' });
+                    return;
+                }
+                res.setHeader('Cache-Control', 'private, no-store');
+                res.json({ items: [...new Set(files)].map(file => {
+                        try {
+                            return { file, ...service.summary(file) };
+                        }
+                        catch {
+                            return { file, error: 'Version status is unavailable.' };
+                        }
+                    }) });
+            } },
+        { path: '/notes/audio-improvement', method: 'GET', handler: (req, res) => {
+                try {
+                    res.json(service.status(String(req.query.file || ''), typeof req.query.id === 'string' ? req.query.id : undefined));
+                }
+                catch (error) {
+                    failure(res, error);
+                }
+            } },
+        { path: '/notes/audio-improvement/audio', method: 'GET', handler: (req, res) => {
+                try {
+                    const audio = service.audio(String(req.query.file || ''), String(req.query.id || ''), String(req.query.variant || ''));
+                    res.setHeader('Content-Type', audioContentType(audio.path));
+                    res.setHeader('Cache-Control', 'private, no-store');
+                    res.sendFile(audio.relative, { root: audio.root, dotfiles: 'allow' });
+                }
+                catch (error) {
+                    failure(res, error);
+                }
+            } },
+        ...['prepare', 'transcribe', 'apply', 'restore', 'discard'].map(action => ({
+            path: `/notes/audio-improvement/${action}`, method: 'POST', handler: async (req, res) => {
+                try {
+                    const file = String(req.body?.file || ''), id = String(req.body?.id || '');
+                    const result = action === 'prepare' ? service.prepare(file, req.body || {})
+                        : action === 'transcribe' ? service.transcribe(file, id)
+                            : action === 'apply' ? await service.apply(file, id, req.body?.reviewToken)
+                                : action === 'restore' ? await service.restore(file, id) : service.discard(file, id);
+                    res.status(['prepare', 'transcribe'].includes(action) ? 202 : 200).json(result);
+                }
+                catch (error) {
+                    failure(res, error);
+                }
+            },
+        })),
+    ];
+}
+export const audioRescueRoutes = createAudioRescueRoutes();

package/dist/cli.js

@@ -28,7 +28,7 @@ Config (first hit wins):
   ./config.json
   ~/.dictawhisper/config.json
 
-Requires Node 22.13+ and a Python with faster-whisper. See dictawhisper.com
+Requires Node 22.13+ and a local Bark Pro or faster-whisper runtime. See dictawhisper.com
 `;
 }
 function fail(message, code = 1) {
@@ -62,7 +62,7 @@ function init(home) {
     mkdirSync(path.dirname(dest), { recursive: true });
     copyFileSync(exampleConfig, dest);
     console.log(`Wrote ${dest}`);
-    console.log('Edit whisper.python, then: dictawhisper doctor');
+    console.log('Install Bark Pro (scripts/setup-bark.ps1), or set transcription.model to large-v3/turbo and configure whisper.python. Then: dictawhisper doctor');
 }
 function runNode(script, extraEnv) {
     const nodeArgs = script.endsWith('.ts') ? ['--experimental-strip-types', script] : [script];
@@ -80,7 +80,7 @@ function runNode(script, extraEnv) {
 function start() {
     const configFile = resolveExistingConfig();
     if (!configFile) {
-        fail('No config.json. Run: dictawhisper init\nThen edit whisper.python and run: dictawhisper doctor');
+        fail('No config.json. Run: dictawhisper init\nThen set up the selected transcription model and run: dictawhisper doctor');
     }
     if (!existsSync(uiDir)) {
         console.warn(`[ui] no packaged inbox at ${uiDir} — API only. In a checkout: pnpm --dir client build`);

package/dist/config.js

@@ -4,6 +4,7 @@ import path from 'path';
 import { z } from 'zod';
 import { localslipGet } from "./lib/localslipGet.js";
 import { resolveApiListenPort } from "./lib/devPorts.js";
+import { transcriptionModels } from "./lib/asrModels.js";
 export { resolveApiListenPort } from "./lib/devPorts.js";
 export function resolveConfigPath(env = process.env, cwd = process.cwd(), home = os.homedir()) {
     const fromEnv = env.DICTA_CONFIG?.trim();
@@ -79,6 +80,7 @@ export const dictaConfigFileSchema = z
     http: httpSchema,
     watch: watchSchema,
     whisper: whisperSchema,
+    transcription: z.object({ model: z.enum(transcriptionModels).default('bark-pro') }).default({}),
     audio: z.object({ preprocess: z.boolean().default(true) }).default({}),
     queues: queuesSchema,
     ollanet: ollanetSchema,
@@ -116,6 +118,7 @@ export function loadConfig(configPath = resolveConfigPath()) {
     const parsed = dictaConfigFileSchema.parse(readJson(configPath));
     const configDir = path.dirname(path.resolve(configPath));
     const config = {
+        transcription: { model: z.enum(transcriptionModels).parse(process.env.DICTA_TRANSCRIPTION_MODEL?.trim() || parsed.transcription.model) },
         http: {
             host: process.env.HOST?.trim() || parsed.http.host,
             port: resolveListenPort(process.env.PORT, localslipGet('dictawhisper'), localslipGet('dictawhisper-api'), parsed.http.port, servePackagedUi(), process.env.DICTA_UI_PORT),

package/dist/lib/activityLib.js

@@ -5,7 +5,7 @@ const unfinished = new Set(['waiting_for_file', 'queued_transcription', 'transcr
 export const isWorkingStage = (stage) => unfinished.has(stage);
 export const isFailureStage = (stage) => stage.startsWith('failed_') || stage === 'interrupted';
 const fileKey = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
-/** Durable summaries, never a queue replay. Restarted work requires explicit recovery. */
+/** Durable summaries, never a queue replay. Watchers recheck waiting files; interrupted processing requires explicit recovery. */
 export class ActivityStore {
     items = new Map();
     emit = () => { };
@@ -23,7 +23,17 @@ export class ActivityStore {
                 for (const item of saved.items) {
                     if (!item.id || !item.jsonFile || !item.audioFile)
                         continue;
-                    if (unfinished.has(item.stage)) {
+                    if (item.stage === 'waiting_for_file' || item.stage === 'interrupted' && item.resumeStage === 'waiting_for_file') {
+                        // No model work started. Let the watcher reconstruct the timer from
+                        // the current mtime, including waits stranded by older versions.
+                        item.stage = 'waiting_for_file';
+                        delete item.resumeStage;
+                        delete item.error;
+                        delete item.eligibleAt;
+                        item.reason = 'Checking file stability after restart.';
+                        item.updatedAt = Date.now();
+                    }
+                    else if (unfinished.has(item.stage)) {
                         item.resumeStage = item.stage;
                         item.stage = 'interrupted';
                         item.error = 'Server stopped before processing finished. Resume explicitly.';
@@ -47,7 +57,7 @@ export class ActivityStore {
         const jsonFile = file.replace(/\.[^.\\/]+$/, '.json');
         const item = { id: old?.id || randomUUID(), audioFile: old?.audioFile || file,
             jsonFile: old?.jsonFile || jsonFile, createdAt: old?.createdAt || Date.now(), hasTranscript: old?.hasTranscript || false,
-            ...old, eligibleAt: undefined, error: undefined, reason: undefined, ...patch, stage, updatedAt: Date.now() };
+            ...old, eligibleAt: undefined, error: undefined, reason: undefined, resumeStage: undefined, ...patch, stage, updatedAt: Date.now() };
         this.items.set(item.id, item);
         const completed = [...this.items.values()].filter(row => !unfinished.has(row.stage) && !isFailureStage(row.stage)).sort((a, b) => b.updatedAt - a.updatedAt);
         for (const row of completed.slice(200))

package/dist/lib/alignLib.js

@@ -1,16 +1,6 @@
+import { readableParagraphs as splitCleanedSections } from "../shared/readableParagraphs.js";
+export { readableParagraphs as splitCleanedSections } from "../shared/readableParagraphs.js";
 const FILLERS = new Set(['uh', 'um', 'umm', 'hmm', 'yeah', 'like']);
-export function splitCleanedSections(cleaned) {
-    const trimmed = String(cleaned || '').trim();
-    if (!trimmed)
-        return [];
-    const paras = trimmed.split(/\n{2,}/).map((part) => part.trim()).filter(Boolean);
-    if (paras.length >= 2)
-        return paras;
-    const sentences = trimmed.split(/(?<=[.!?])\s+/).map((part) => part.trim()).filter(Boolean);
-    if (sentences.length >= 2)
-        return sentences;
-    return [trimmed];
-}
 function normWord(text) {
     return String(text || '')
         .toLowerCase()
@@ -101,13 +91,16 @@ export function ensurePlaybackCues(json) {
     const sections = cleaned ? splitCleanedSections(cleaned) : [];
     if (words.length && cleaned && sections.length) {
         const existing = json.playbackCues;
+        // Text can change without the paragraph count changing, and a new ASR pass
+        // can move word timestamps without changing text. Validate both.
+        const aligned = alignCleanedToWords(cleaned, words);
         if (json.playbackCuesSource === 'words' &&
             Array.isArray(existing) &&
-            existing.length === sections.length &&
-            existing.every((cue) => cue && typeof cue.text === 'string')) {
+            existing.length === aligned.length &&
+            existing.every((cue, index) => cue && cue.text === aligned[index].text && cue.start === aligned[index].start && cue.end === aligned[index].end)) {
             return false;
         }
-        json.playbackCues = alignCleanedToWords(cleaned, words);
+        json.playbackCues = aligned;
         json.playbackCuesSource = 'words';
         return true;
     }

package/dist/lib/asrModels.js

@@ -0,0 +1,7 @@
+export const transcriptionModels = ['bark-pro', 'large-v3', 'turbo'];
+export function isTranscriptionModel(model) {
+    return transcriptionModels.includes(model);
+}
+export function asrModelLabel(model) {
+    return model === 'bark-pro' ? 'Bark Pro' : `Whisper ${model}`;
+}

package/dist/lib/audioAssessmentLib.js

@@ -0,0 +1,93 @@
+import { spawn } from 'node:child_process';
+import { probeAudioFile } from "./audioLib.js";
+const db = (value) => Math.max(-120, 20 * Math.log10(Math.max(value, 1e-6)));
+const rounded = (n) => Math.round(n * 100) / 100;
+const percentile = (sorted, p) => sorted[Math.floor((sorted.length - 1) * p)] ?? -120;
+/** One-second energy windows, not speech recognition or an intelligibility score. */
+export function assessWindows(windows, peak, channelEnergy, frames, nearFullScale) {
+    const sorted = windows.slice().sort((a, b) => a - b);
+    const threshold = Math.max(-65, percentile(sorted, .9) - 35);
+    const active = sorted.filter(level => level > threshold);
+    const median = percentile(active, .5), spread = percentile(active, .9) - percentile(active, .1);
+    const mean = db(Math.sqrt(channelEnergy.reduce((sum, n) => sum + n, 0) / Math.max(1, frames * channelEnergy.length)));
+    const channelDb = channelEnergy.map(sum => db(Math.sqrt(sum / Math.max(1, frames))));
+    const channelDifference = Math.max(...channelDb) - Math.min(...channelDb);
+    const peakDb = db(peak), warnings = [], reasons = [];
+    let preset = 'original';
+    if (peakDb < -65 || !active.length)
+        warnings.push('Very little signal was detected. Amplification cannot recover speech that was not captured.');
+    else if (spread >= 14 && percentile(active, .1) < -30) {
+        preset = 'uneven';
+        reasons.push('Audible levels vary substantially across the recording.');
+    }
+    else if (median < -28) {
+        preset = peakDb < -4 ? 'quiet' : 'uneven';
+        reasons.push(preset === 'quiet' ? 'Consistently low levels have room for a clean gain increase.' : 'Quiet passages and loud peaks need different gain.');
+    }
+    else
+        reasons.push('Levels are adequate; keep the signal unfiltered.');
+    if (channelDifference > 18)
+        warnings.push('The decoded channels have very different levels. Listen for a missing or weak channel.');
+    if (nearFullScale / Math.max(1, frames * channelEnergy.length) > .001)
+        warnings.push('Frequent near-full-scale samples may indicate distortion. Normalization cannot repair clipping.');
+    const ranges = [];
+    windows.forEach((level, second) => {
+        if (level <= threshold)
+            return;
+        const last = ranges.at(-1);
+        if (last && last.end === second)
+            last.end = second + 1;
+        else
+            ranges.push({ start: second, end: second + 1 });
+    });
+    return { version: 1, durationSec: frames / 16000, meanDb: rounded(mean), peakDb: rounded(peakDb), activeMedianDb: rounded(median), activeSpreadDb: rounded(spread), channelDifferenceDb: rounded(channelDifference), nearFullScaleFraction: nearFullScale / Math.max(1, frames * channelEnergy.length), energeticRanges: ranges.slice(0, 2000), suggestedPreset: preset, reasons, warnings };
+}
+/** Decode to a bounded streaming PCM buffer; retain only one number per second. */
+export async function assessAudio(file) {
+    const probe = await probeAudioFile(file);
+    if (!probe.ok)
+        throw new Error('Audio assessment failed: ' + probe.reason);
+    const channels = probe.channels || 1;
+    if (!Number.isInteger(channels) || channels < 1 || channels > 32)
+        throw new Error('Unsupported audio channel count.');
+    return new Promise((resolve, reject) => {
+        const child = spawn('ffmpeg', ['-v', 'error', '-nostdin', '-i', file, '-map', '0:a:0', '-vn', '-ar', '16000', '-ac', String(channels), '-f', 'f32le', 'pipe:1'], { windowsHide: true });
+        let tail = Buffer.alloc(0), stderr = '', frames = 0, peak = 0, near = 0, windowEnergy = 0, windowFrames = 0, timedOut = false;
+        const energy = Array(channels).fill(0), windows = [];
+        const timer = setTimeout(() => { timedOut = true; child.kill(); }, 30 * 60_000);
+        child.stderr.on('data', data => { stderr = (stderr + data).slice(-800); });
+        child.stdout.on('data', (chunk) => {
+            const buffer = tail.length ? Buffer.concat([tail, chunk]) : chunk;
+            const end = buffer.length - buffer.length % (channels * 4);
+            for (let i = 0; i < end; i += channels * 4) {
+                for (let channel = 0; channel < channels; channel++) {
+                    const sample = buffer.readFloatLE(i + channel * 4), square = sample * sample;
+                    energy[channel] += square;
+                    windowEnergy += square;
+                    peak = Math.max(peak, Math.abs(sample));
+                    if (Math.abs(sample) >= .999)
+                        near++;
+                }
+                frames++;
+                windowFrames++;
+                if (windowFrames === 16000) {
+                    windows.push(db(Math.sqrt(windowEnergy / (windowFrames * channels))));
+                    windowEnergy = 0;
+                    windowFrames = 0;
+                }
+            }
+            tail = Buffer.from(buffer.subarray(end));
+        });
+        child.on('error', error => { clearTimeout(timer); reject(error); });
+        child.on('close', code => {
+            clearTimeout(timer);
+            if (timedOut || code !== 0 || !frames) {
+                reject(new Error(`Audio assessment failed: ${timedOut ? 'timed out' : stderr || 'no decoded samples'}`));
+                return;
+            }
+            if (windowFrames)
+                windows.push(db(Math.sqrt(windowEnergy / (windowFrames * channels))));
+            resolve(assessWindows(windows, peak, energy, frames, near));
+        });
+    });
+}

package/dist/lib/audioEnhancementLib.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { audioExtensions, probeAudioFile } from "./audioLib.js";
+import { assessAudio } from "./audioAssessmentLib.js";
+export const enhancementPresets = ['auto', 'quiet', 'uneven', 'noise', 'original'];
+/** Originals may have a different container from the working MP3. Never enhance an enhancement. */
+export function findOriginalAudio(jsonFile) {
+    const base = jsonFile.replace(/\.json$/i, '');
+    for (const suffix of ['_original', ''])
+        for (const ext of audioExtensions) {
+            const file = `${base}${suffix}.${ext}`;
+            if (fs.existsSync(file))
+                return { file, original: suffix === '_original' };
+        }
+    return null;
+}
+export function ffmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ffmpeg', ['-hide_banner', '-nostdin', ...args], { windowsHide: true });
+        let output = '', timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; child.kill(); }, 30 * 60_000);
+        child.stderr.on('data', data => { output = (output + data.toString()).slice(-65536); });
+        child.on('error', error => { clearTimeout(timer); reject(error); });
+        child.on('close', code => {
+            clearTimeout(timer);
+            if (timedOut)
+                reject(new Error('Audio preparation timed out. Your current entry is unchanged.'));
+            else if (code !== 0)
+                reject(new Error(`Audio preparation failed: ${output.slice(-800)}`));
+            else
+                resolve(output);
+        });
+    });
+}
+export async function measureAudio(file) {
+    const probe = await probeAudioFile(file);
+    if (!probe.ok)
+        throw new Error(`Cannot read source audio: ${probe.reason}`);
+    const log = await ffmpeg(['-i', file, '-vn', '-af', 'volumedetect', '-f', 'null', '-']);
+    const meanDb = Number(log.match(/mean_volume:\s*(-?[\d.]+) dB/)?.[1]);
+    const peakDb = Number(log.match(/max_volume:\s*(-?[\d.]+) dB/)?.[1]);
+    if (!Number.isFinite(meanDb) || !Number.isFinite(peakDb))
+        throw new Error('Could not measure audio levels.');
+    return { meanDb, peakDb, durationSec: probe.durationSec };
+}
+export function enhancementFilter(preset, levels) {
+    const gainDb = Math.max(0, Math.min(30, -22 - levels.meanDb, -1 - levels.peakDb));
+    const leveling = 'dynaudnorm=f=250:g=15:p=0.89:m=10';
+    const filter = preset === 'quiet' ? `volume=${gainDb.toFixed(3)}dB`
+        : preset === 'uneven' ? leveling
+            : preset === 'noise' ? `highpass=f=80,afftdn=nr=8:nf=-50:tn=1,${leveling}` : null;
+    return { filter, gainDb: preset === 'quiet' ? gainDb : 0 };
+}
+/** PCM output: no silence removal, time stretching, MP3 encoding, or source writes. */
+export async function enhanceAudio(source, output, preset) {
+    if (!enhancementPresets.includes(preset))
+        throw new Error('Unknown audio preset.');
+    if (path.resolve(source) === path.resolve(output) || fs.existsSync(output))
+        throw new Error('Audio output must be a new file.');
+    const assessment = await assessAudio(source);
+    const levels = assessment;
+    const selectedPreset = preset === 'auto' ? assessment.suggestedPreset : preset;
+    const { filter, gainDb } = enhancementFilter(selectedPreset, { ...levels, meanDb: assessment.activeMedianDb });
+    await ffmpeg(['-n', '-i', source, '-map', '0:a:0', '-vn', ...(filter ? ['-af', filter] : []), '-ar', '16000', '-c:a', 'pcm_s16le', output]);
+    const result = await probeAudioFile(output);
+    if (!result.ok || Math.abs(result.durationSec - levels.durationSec) > 0.15)
+        throw new Error('Prepared audio did not preserve the recording duration.');
+    return { meanDb: levels.meanDb, peakDb: levels.peakDb, durationSec: levels.durationSec, gainDb, selectedPreset, assessment, suggestedPreset: assessment.suggestedPreset,
+        warning: assessment.warnings.join(' ') || (selectedPreset === 'quiet' && gainDb < 1 && levels.meanDb < -30 ? 'Loud peaks limit the boost. Try Uneven volume to lift quieter passages.' : undefined) };
+}