dictawhisper 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -182
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,213 +4,48 @@
|
|
|
4
4
|
|
|
5
5
|
# DictaWhisper
|
|
6
6
|
|
|
7
|
-
**[
|
|
7
|
+
**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.
|
|
8
8
|
|
|
9
9
|
The npm package is a name hold. Clone this repo to run it.
|
|
10
10
|
|
|
11
|
-
**
|
|
11
|
+
**Docs:** [dictawhisper.com/docs](https://dictawhisper.com/docs) · **Site:** [dictawhisper.com](https://dictawhisper.com)
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Open the UI at [http://localhost:7777](http://localhost:7777). On Tailscale, the same page is reachable from your phone. If [LocalBerth](https://www.npmjs.com/package/localberth) is installed, 7777 is the `dictawhisper` slip and 8008 is `dictawhisper-api` (loopback; not `--lan`).
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## Why it exists
|
|
20
|
-
|
|
21
|
-
Voice notes are easy to make and hard to keep. Phone recordings pile up as undated blobs. Cloud speech-to-text wants the audio. Desktop Whisper dumps a wall of filler words and repeated phrases. A journal you can reread needs three things:
|
|
22
|
-
|
|
23
|
-
1. **Capture that fits your tools:** record or drop a file in the browser. Syncthing from a phone is optional.
|
|
24
|
-
2. **Accurate, local transcription:** `large-v3` on CUDA, a prompt seeded with your own vocabulary, word times that survive cleanup.
|
|
25
|
-
3. **Usable notes:** cleaned prose, tags, playback that follows the cleaned paragraphs, files you can copy and back up.
|
|
26
|
-
|
|
27
|
-
By default the API binds to `127.0.0.1`. Turn on `http.tailscale` and the inbox also listens on this machine's Tailscale address (`100.x`, plus MagicDNS when you have it) so a phone on the same tailnet can open it. The API stays on loopback; Vite proxies to it. File APIs only accept paths under your watch roots. If cleanup is unavailable, you still get the raw transcript.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## Daily loop
|
|
32
|
-
|
|
33
|
-
1. Talk. Hit Record, or drag an audio file onto the page.
|
|
34
|
-
2. Browser files start immediately. Optional ffmpeg denoise, then Whisper (model loaded once) writes a sidecar `.json`.
|
|
35
|
-
3. ollanet cleans the text and adds tags onto the same JSON. Raw speech is kept.
|
|
36
|
-
4. Notes are grouped by month. Cleaned text is the default; raw speech is one click away. Playback follows the cleaned paragraphs.
|
|
37
|
-
|
|
38
|
-
If you also watch a phone folder ([Syncthing](https://syncthing.net) or any folder sync), those files wait 30 minutes after the last write so the transfer can finish, then dated names are filed into `YYYY/MM/` on that watch root.
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
Browser record/drop → drop folder → immediately ─────────────┐
|
|
42
|
-
Optional phone folder → watch roots → settle 30m → YYYY/MM/ ┼─→ whisper → sidecar.json → ollanet → UI
|
|
43
|
-
Force / retranscribe ─────────────────────────────────────────┘
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## What it is good at
|
|
49
|
-
|
|
50
|
-
**Files are the database.** Each note is `audio` + `audio.json`. You can rsync the tree, open a sidecar in an editor, or point `pnpm retranscribe` at one month. The file path is the note's identity, so there is nothing to export.
|
|
51
|
-
|
|
52
|
-
**The Whisper model stays loaded.** The worker loads the model once and keeps it for the next file. That is the normal path, not a special command.
|
|
53
|
-
|
|
54
|
-
**Audio never leaves this computer.** Faster-whisper runs here. If you point ollanet at Ollama on another machine on your own network, only the transcript text crosses the network. If ollanet is unreachable, doctor and `/health` report it and you still have the raw words.
|
|
55
|
-
|
|
56
|
-
**UI on the tailnet.** Default bind is localhost. Set `http.tailscale` (or `DICTA_TAILSCALE=1`) and `pnpm dev` listens on this machine's Tailscale IPv4 (`100.64.0.0/10`) and advertises `http://<magicdns>:7777` / `http://<100.x>:7777`. localhost:7777 still works. The inbox is not bound to `0.0.0.0` or your LAN. The app adds no login of its own.
|
|
57
|
-
|
|
58
|
-
**Playback aligned to word timestamps.** Cleanup drops fillers and collapses repeated phrases, but playback cues map back to Whisper word timestamps rather than being inferred from the cleaned wording. Copy uses the same sections the player shows.
|
|
59
|
-
|
|
60
|
-
**Custom vocabulary and stable tags.** `whisper.promptTerms` (a person, a company, a street) go into Whisper's initial prompt. Tags already in your inventory are fed into cleanup so the model does not spell them a new way every week, and a consolidate preview/apply pass merges near-duplicates when you ask.
|
|
61
|
-
|
|
62
|
-
---
|
|
63
|
-
|
|
64
|
-
## Privacy and network boundary
|
|
65
|
-
|
|
66
|
-
- **No telemetry.** Nothing contacts an external analytics or telemetry service.
|
|
67
|
-
- **Audio stays here.** Faster-whisper processes files on this GPU or CPU.
|
|
68
|
-
- **Text only, and only on your network.** If cleanup runs on another machine you already use, only the transcript text is sent there.
|
|
69
|
-
- **Loopback by default.** API (`8008`) and UI (`7777`) bind to `127.0.0.1`. With `http.tailscale`, the inbox also binds to this machine's Tailscale address, not to every interface.
|
|
70
|
-
- **Path allowlisting.** File routes resolve realpaths and reject anything outside `watch.roots` and `browserDropFolder` with a `403`.
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
## Requirements
|
|
75
|
-
|
|
76
|
-
- Node 20+ and [pnpm](https://pnpm.io)
|
|
77
|
-
- NVIDIA GPU + CUDA for local Whisper (or set `whisper.device` to `cpu`, which is far slower)
|
|
78
|
-
- Python with [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper): point `whisper.python` at that interpreter
|
|
79
|
-
- `ffmpeg` on PATH if denoise is on
|
|
80
|
-
- [ollanet](https://ollanet.dev) + an Ollama model for cleanup (localhost or another reachable host; optional for raw transcripts)
|
|
81
|
-
- Optional: [Tailscale](https://tailscale.com) if you want the UI from another device on your tailnet
|
|
82
|
-
- Optional: a watched folder ([Syncthing](https://syncthing.net), a shared drive, a dump directory) if you already record outside the browser
|
|
83
|
-
|
|
84
|
-
Record or drag files at [localhost:7777](http://localhost:7777). Run it on a computer you leave turned on.
|
|
85
|
-
|
|
86
|
-
---
|
|
87
|
-
|
|
88
|
-
## Setup
|
|
13
|
+
## Install
|
|
89
14
|
|
|
90
15
|
```bash
|
|
16
|
+
git clone https://github.com/Catalyst-Forge-LLC/dictawhisper.git
|
|
17
|
+
cd dictawhisper
|
|
91
18
|
cp config.example.json config.json
|
|
92
|
-
# edit whisper.python, whisper.promptTerms, ollanet.machine / cleanModel
|
|
93
|
-
# watch.roots is optional: record or drop files in the UI without Syncthing
|
|
94
19
|
pnpm install
|
|
95
20
|
pnpm run doctor
|
|
21
|
+
pnpm dev
|
|
96
22
|
```
|
|
97
23
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
`pnpm run doctor` and startup `/health` run the same probes: Node, config, watch roots, ffmpeg, `faster-whisper` import, CUDA vs CPU, ollanet reachability, and port availability. Failures refuse to start queues. Warnings (CPU mode, ollanet unreachable, port already in use) are reported without blocking startup.
|
|
101
|
-
|
|
102
|
-
Optional sanity check (machine can be this computer or another name ollanet already sees):
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
ollanet prompt YOUR-OLLANET-HOST YOUR-CLEAN-MODEL --format json "ping"
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
---
|
|
24
|
+
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.
|
|
109
25
|
|
|
110
|
-
##
|
|
26
|
+
## Quick start
|
|
111
27
|
|
|
112
28
|
```bash
|
|
113
29
|
pnpm dev # API + UI → http://localhost:7777
|
|
114
30
|
pnpm start # API only on 127.0.0.1:8008
|
|
115
|
-
pnpm ui # UI only
|
|
116
|
-
pnpm turbo # API with large-v3-turbo (bash)
|
|
117
31
|
```
|
|
118
32
|
|
|
119
|
-
|
|
33
|
+
Hit Record, or drag an audio file onto the page. Flags, HTTP, MCP, and `retranscribe` live in the [docs](https://dictawhisper.com/docs).
|
|
120
34
|
|
|
121
|
-
|
|
35
|
+
## What you get
|
|
122
36
|
|
|
123
|
-
|
|
124
|
-
"http": { "tailscale": true }
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
or `DICTA_TAILSCALE=1`. Doctor and startup print the MagicDNS / `100.x` URL. There is still no login: only devices on that tailnet should be able to open it.
|
|
37
|
+
Files are the database. The Whisper model stays loaded. Audio stays on this computer. The inbox is loopback by default; `http.tailscale` puts the same page on your tailnet. Playback follows cleaned paragraphs using Whisper word times.
|
|
128
38
|
|
|
129
|
-
|
|
39
|
+
## Development
|
|
130
40
|
|
|
131
41
|
```bash
|
|
132
|
-
pnpm
|
|
133
|
-
pnpm
|
|
134
|
-
pnpm
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
`--reclean` runs ollanet again after the new transcript. Without it, cleaned text and tags are kept; only words/times/raw text update. Each successful cleanup writes a `cleanup` record (text, time, model, host, prompt version, app version). The previous record, if any, is prepended to `cleanupHistory` (capped). `cleanedTranscription` remains the current text.
|
|
138
|
-
|
|
139
|
-
---
|
|
140
|
-
|
|
141
|
-
## MCP (read-only)
|
|
142
|
-
|
|
143
|
-
Agents can search the journal without managing it. `pnpm mcp` is a stdio server over the same sidecar files. No writes. The API does not need to be running.
|
|
144
|
-
|
|
145
|
-
Tools: `dictawhisper_search`, `dictawhisper_get_note`, `dictawhisper_list_tags`, `dictawhisper_recent`.
|
|
146
|
-
|
|
147
|
-
This repo ships `.cursor/mcp.json`. Elsewhere:
|
|
148
|
-
|
|
149
|
-
```json
|
|
150
|
-
{
|
|
151
|
-
"mcpServers": {
|
|
152
|
-
"dictawhisper": {
|
|
153
|
-
"command": "node",
|
|
154
|
-
"args": ["--experimental-strip-types", "src/mcp.ts"],
|
|
155
|
-
"cwd": "/absolute/path/to/dictawhisper"
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
}
|
|
42
|
+
pnpm test
|
|
43
|
+
pnpm typecheck
|
|
44
|
+
pnpm site:dev
|
|
159
45
|
```
|
|
160
46
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
## HTTP
|
|
164
|
-
|
|
165
|
-
| Method | Path | Purpose |
|
|
166
|
-
|---|---|---|
|
|
167
|
-
| GET | `/health` | Shared doctor report, queues, Whisper worker, ollanet reachability (`?fresh=1` to skip cache) |
|
|
168
|
-
| GET | `/status` | pending / raw / done counts |
|
|
169
|
-
| GET | `/notes/index` | Inbox summaries (path, tags, preview, search body) |
|
|
170
|
-
| GET | `/note?file=` | Full sidecar (allowlisted) |
|
|
171
|
-
| GET | `/audio?file=` | Stream allowlisted audio (sidecar or audio path) |
|
|
172
|
-
| POST | `/audio` | Multipart `file` (or `audio`) + optional `clipName` → drop folder, process immediately |
|
|
173
|
-
| POST | `/transcribe/force` | `{ "file": "..." }` retry transcription |
|
|
174
|
-
| POST | `/process/force` | Re-run cleanup on an existing note |
|
|
175
|
-
| POST | `/process/skip` | Leave the raw transcript; skip later cleanup |
|
|
176
|
-
| POST | `/holding/resolve` | `{ "file", "action": "overwrite" \| "rename" \| "unfile" }` |
|
|
177
|
-
| POST | `/tags/consolidate/preview` | Merge plan (`useModel`, default true) |
|
|
178
|
-
| POST | `/tags/consolidate/apply` | `{ "groups": [{ "keep", "drop" }] }` |
|
|
179
|
-
|
|
180
|
-
Force/delete/read only accept realpaths under configured watch roots.
|
|
181
|
-
|
|
182
|
-
---
|
|
183
|
-
|
|
184
|
-
## Config and env
|
|
185
|
-
|
|
186
|
-
| Env | Meaning |
|
|
187
|
-
|---|---|
|
|
188
|
-
| `HOST` / `PORT` | API bind (default `127.0.0.1:8008`; Tailscale mode does not change this) |
|
|
189
|
-
| `DICTA_TAILSCALE` | `1` / `true`: also bind the inbox to this machine's Tailscale address |
|
|
190
|
-
| `WHISPER_MODEL` | `large-v3` or `turbo` |
|
|
191
|
-
| `WHISPER_PYTHON` | Interpreter with faster-whisper |
|
|
192
|
-
| `WHISPER_DEVICE` | `cuda` or `cpu` |
|
|
193
|
-
| `VOICE_SETTLE_MINUTES` | Phone/watch settle; default 30 |
|
|
194
|
-
| `VOICE_BROWSER_SETTLE_MS` | Browser-drop settle; default 0 |
|
|
195
|
-
| `OLLANET_MACHINE` / `OLLANET_CLEAN_MODEL` | Cleanup host and model |
|
|
196
|
-
| `OLLAMA_PROMPT_TIMEOUT_MS` | ollanet abort; default 900000 (15m) |
|
|
197
|
-
|
|
198
|
-
Useful `config.json` knobs (see `config.example.json`):
|
|
199
|
-
|
|
200
|
-
- `watch.createMissingRoots`: create empty watch roots instead of failing doctor
|
|
201
|
-
- `whisper.promptTerms`: names and terms Whisper should prefer
|
|
202
|
-
- `whisper.computeType`: `float16`, or `int8_float16` if VRAM is tight
|
|
203
|
-
- `audio.preprocess`: ffmpeg denoise
|
|
204
|
-
- `queues.*.concurrency`: keep transcription at 1 on a single GPU
|
|
205
|
-
- `http.tailscale`: bind the inbox to this machine's Tailscale address and allow those origins for the UI
|
|
206
|
-
- `ollanet.required`: treat missing cleanup host/model as a failure (default false; raw transcripts still work)
|
|
207
|
-
|
|
208
|
-
---
|
|
209
|
-
|
|
210
|
-
## Site
|
|
211
|
-
|
|
212
|
-
Marketing site (FilePress): [`site/`](site/). `pnpm site:dev` / `pnpm site:build` / `pnpm ship`. Live: [dictawhisper.com](https://dictawhisper.com). Page copy follows [aiBreze](https://aibreze.com); see [`docs/aibreze-overlay.md`](docs/aibreze-overlay.md).
|
|
47
|
+
Site (FilePress + docs mount): `pnpm --dir site ship`
|
|
213
48
|
|
|
214
49
|
## License
|
|
215
50
|
|
|
216
|
-
MIT
|
|
51
|
+
MIT · [Catalyst Forge LLC](https://www.catalystforge.com)
|
package/package.json
CHANGED