dictawhisper 0.1.15 → 0.1.17

package/README.md

@@ -4,9 +4,11 @@
 
 # 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 searchable voice journal on your computer.** This local web app lets you record or import voice notes, find them later, read the transcript, and replay the recording. Optional cleanup and MayDos help you turn a note into readable text and suggested actions to review.
 
-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.
+Transcribe locally with **Bark Pro** (English, default) or [faster-whisper](https://github.com/SYSTRAN/faster-whisper). Cleanup uses [ollanet](https://ollanet.dev) with the host you configure. Each recording and its neighboring `.json` form a journal entry; a synced phone folder is optional.
+
+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)
 
@@ -18,7 +20,7 @@ Actual Inbox showing three fictional entries. The transcript, timestamps, and ac
 
 ## 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
 
@@ -27,11 +29,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.
 
@@ -46,7 +50,7 @@ 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
 
@@ -54,7 +58,7 @@ Record opens the compact capture panel and requests the microphone. Stop keeps a
 
 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, unfinished work appears as Interrupted and requires explicit resume; existing transcripts remain readable.
+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.
 
 ## Read, search, and listen
 
@@ -62,6 +66,26 @@ Select a card to read its full entry in the right pane. The entry list and detai
 
 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.
 
+## Improve difficult recordings
+
+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.
+
+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).
+
+## Retranscribe an existing library
+
+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.
+
+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.
+
+## Choose the default model
+
+**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.
+
+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.
+
+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).
+
 ## Review MayDos and extract older entries
 
 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.
@@ -78,7 +102,7 @@ Backfill scope and acknowledged outcomes are saved on disk; extracted actions re
 
 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. 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.
+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).
 

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) };
+}

package/dist/lib/audioImprovementStorageLib.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { allowedRoots, resolveAllowedPath } from "./pathAllowLib.js";
+/** Called only by confirmed permanent Trash deletion. Validate every target before unlinking. */
+export function purgeAudioImprovementHistory(entryId) {
+    const files = [], directories = [];
+    function exact(file) {
+        const allowed = resolveAllowedPath(file);
+        if (!allowed.ok)
+            throw new Error(allowed.error);
+        const canonical = (value) => process.platform === 'win32' ? path.resolve(value).toLowerCase() : path.resolve(value);
+        if (canonical(allowed.path) !== canonical(file))
+            throw new Error('Audio improvement storage redirects elsewhere. Saved files were kept.');
+        return allowed.path;
+    }
+    for (const root of [...new Set(allowedRoots())]) {
+        const base = exact(path.join(root, '.dictawhisper', 'audio-improvements'));
+        if (!fs.existsSync(base))
+            continue;
+        for (const id of fs.readdirSync(base)) {
+            if (!/^[a-f0-9-]{36}$/.test(id))
+                continue;
+            const directory = exact(path.join(base, id)), manifest = exact(path.join(directory, 'job.json'));
+            if (!fs.existsSync(manifest))
+                continue;
+            const job = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+            if (job.entryId !== entryId)
+                continue;
+            if (job.id !== id || !/^\.(webm|mp3|m4a|wav|ogg)$/i.test(job.sourceExt))
+                throw new Error('Invalid audio improvement manifest. Saved files were kept.');
+            for (const name of ['source' + job.sourceExt, 'enhanced.wav', 'candidate.json', 'previous.json', 'job.json']) {
+                const file = exact(path.join(directory, name));
+                if (fs.existsSync(file)) {
+                    if (!fs.statSync(file).isFile())
+                        throw new Error('Unexpected audio improvement artifact.');
+                    files.push(file);
+                }
+            }
+            directories.push(directory);
+        }
+    }
+    for (const file of files)
+        fs.unlinkSync(file);
+    for (const directory of directories)
+        if (!fs.readdirSync(directory).length)
+            fs.rmdirSync(directory);
+}

package/dist/lib/audioLib.js

@@ -46,6 +46,15 @@ export function audioContentType(filePath) {
 export function findAudioForSidecar(jsonFile) {
     const parsed = path.parse(jsonFile);
     const base = path.join(parsed.dir, parsed.name);
+    try {
+        const id = JSON.parse(fs.readFileSync(jsonFile, 'utf8'))?.audioEnhancement?.versionId;
+        if (typeof id === 'string' && /^[a-f0-9-]{36}$/.test(id)) {
+            const enhanced = `${base}_enhanced-${id}.wav`;
+            // Missing enhanced audio must not silently play an older, differently timed file.
+            return fs.existsSync(enhanced) ? enhanced : null;
+        }
+    }
+    catch { /* Legacy sidecars have no enhanced version. */ }
     for (const ext of audioExtensions) {
         const candidate = `${base}.${ext}`;
         if (fs.existsSync(candidate))
@@ -112,7 +121,7 @@ export function probeAudioFile(filePath) {
         return Promise.resolve({ ok: false, reason: `too small (${size} bytes)`, size });
     }
     return new Promise((resolve) => {
-        const child = spawn('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'json', filePath], { windowsHide: true });
+        const child = spawn('ffprobe', ['-v', 'error', '-select_streams', 'a:0', '-show_entries', 'format=duration:stream=channels', '-of', 'json', filePath], { windowsHide: true });
         let stdout = '';
         let stderr = '';
         const timer = setTimeout(() => {
@@ -141,12 +150,13 @@ export function probeAudioFile(filePath) {
                 return;
             }
             try {
-                const duration = Number(JSON.parse(stdout || '{}')?.format?.duration);
+                const parsed = JSON.parse(stdout || '{}');
+                const duration = Number(parsed?.format?.duration);
                 if (!Number.isFinite(duration) || duration <= 0) {
                     resolve({ ok: false, reason: 'no duration', size });
                     return;
                 }
-                resolve({ ok: true, reason: `${duration.toFixed(1)}s`, durationSec: duration, size });
+                resolve({ ok: true, reason: `${duration.toFixed(1)}s`, durationSec: duration, channels: Number(parsed.streams?.[0]?.channels) || 1, size });
             }
             catch {
                 resolve({ ok: false, reason: 'ffprobe json', size });