usb-audio-transcriber 1.1.0__tar.gz

usb_audio_transcriber-1.1.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+- 
+
+## Safety and privacy
+
+- Source deletion behavior changed: no
+- Cloud data flow changed: no
+- Credential handling changed: no
+- Existing `config.env` compatibility changed: no
+
+## Verification
+
+- [ ] `python3 -m py_compile bin/*.py usb_audio_transcriber/*.py`
+- [ ] `bash -n install.sh uninstall.sh bootstrap.sh bin/run-cycle.sh`
+- [ ] `python3 -m unittest discover -s tests -v`
+- [ ] `git diff --check`
+
+## Manual testing
+
+Describe any USB, desktop, model, or real-audio validation. Do not attach private recordings or transcripts.

usb_audio_transcriber-1.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Local configuration and credentials
+config.env
+config.env.*
+!config.example.env
+
+# Python environments, caches, and package builds
+venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+
+# Runtime data: recordings, transcripts, logs, progress, and deduplication state
+var/
+archive/
+queue/
+vault/
+transcripts/
+*.sqlite
+*.sqlite-*
+
+# Imported media and generated transcript artifacts
+*.wav
+*.mp3
+*.m4a
+*.json
+*.txt
+!requirements.txt
+!requirements-diarization.txt
+
+# Editor and OS artifacts
+.DS_Store
+.vscode/
+.idea/

usb_audio_transcriber-1.1.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [1.1.0] - 2026-09-06
+
+The control panel becomes a real desktop window, summaries can use a tool you already pay for, and the program is a pipx package.
+
+### Added
+
+- The control panel is a desktop window: `bin/app.py`, a native GTK 4 / libadwaita app with the same pages as the web panel (home, sessions, recordings, search, settings, tools), talking to the panel server's local API. The app-menu entry and `panel.py open` start it when the GTK bindings are installed (`python3-gi gir1.2-gtk-4.0 gir1.2-adw-1`) and fall back to the web page otherwise; `--page` opens on a given page, `--web` and `--browser` choose the web page. `GET /api/link` returns the private link for another device.
+- pipx and PyPI packaging (#10): `pyproject.toml` builds a wheel whose `usb-audio-transcriber` command wraps every script (`install`, `uninstall`, `update`, `cycle`, `panel`, `doctor`, `setup`, `sessions`, `search`, `model-cache`, `benchmark`, `paths`). `usb-audio-transcriber install` writes the same units and menu entry as `install.sh`, against the same `~/.local/share/usb-audio-transcriber/config.env`, so the two install paths are interchangeable. The version is the git tag, CI installs the built wheel with pipx, and the Release workflow gains a PyPI `publish` job that runs once trusted publishing is configured. `USB_AUDIO_TRANSCRIBER_ROOT` moves the data folder; `install.sh` and `bootstrap.sh` are unchanged for users.
+- The control panel (`bin/panel.py`, an app-menu entry, and `usb-audio-transcriber-panel.service`): a token-protected local web app with the pipeline's state, sessions with a Summarize button and backend picker, recordings, search, every setting as a validated form (with "Find my Obsidian vault"), and tools for the doctor, search index, model cache, session rebuilds, and the log. `sessions.py summarize --id` and `--backend` back its actions from the terminal. Every button shows its result, streamed while it runs, in an Activity box on the page where it was pressed, and the panel opens as its own window when Chrome, Chromium, Brave, or Edge is installed (`panel.py open --browser` forces a tab).
+- Summary backends (`SUMMARY_BACKEND`): summaries can now come from a command-line AI tool you already pay for (`command`: Codex, Claude Code, Gemini CLI, your own agent), any OpenAI-compatible server such as a local Ollama (`openai`), or OpenRouter (`openrouter`). The setup wizard asks which, `sessions.py test-backend` checks it, and empty keeps the old OpenRouter-if-key behaviour.
+- `SESSION_BACKFILL_DAYS` (default 7): on an installation with history, sessions that ended more than that many days ago get notes without an automatic AI summary, and a cycle that writes more than three session notes sends one notification instead of one per note. `sessions.py retry` summarizes older sessions on demand.
+- Full-text search across all transcripts (`bin/search.py`): an FTS5 index in the state database, refreshed every cycle, with `--since`, `--speaker`, prefix, `--raw`, and `--json` options. (#11)
+- `WHISPER_TASK="translate"` translates speech in other languages straight into English instead of transcribing it; the task is validated by the doctor and recorded in each note's front matter (#13, contributed by @anni-x1).
+
+### Fixed
+
+- The desktop window keeps one instance per session (a second launch raises the window), carries the app icon in the dock (the menu entry and icon are now named after the window's id, `io.github.aaacharlie.UsbAudioTranscriber`), and got a face: a status card on Home with the icon, the pipeline's state in one line, a progress bar while transcribing, and icons on every row; page titles use the desktop's accent colour.
+- Clicking the app while its window is buried now raises the window. The menu entry asks the desktop for an activation token (`StartupNotify=true`), `panel.py open` becomes the window process instead of spawning it, and the window carries its id as its X11 class, so the desktop treats the click as permission to take focus rather than showing "USB Audio Transcriber is ready".
+- The menu entry names the icon by its full path, the installer bumps the icon theme folder and refreshes a stale `icon-theme.cache`, so the microphone shows in the menu and the dock right after an update; a leftover cache had turned it into a gear.
+- Updating restarts a running panel server (`systemctl --user try-restart`), so the new code is what the window talks to straight away.
+- The panel's status no longer walks every mounted drive on every refresh: the "on the recorder" count is refreshed in the background at most every 30 seconds, `bin/ingest.py` skips hidden and system folders and looks at most four levels deep for the recorder's folder, and the window never stacks status requests, keeps the last good values, and reports an outage only after two failures in a row. Before, an external drive with many files made `/api/status` time out ("Panel unreachable") and kept the disk busy.
+
+## [1.0.0] - 2026-09-05
+
+First tagged release. Everything below is new relative to the initial public code.
+
+### Added
+
+- One-command installer (`bootstrap.sh`) that clones or updates the source and runs `install.sh`.
+- First-run setup wizard (`bin/setup.py`) that finds Obsidian vaults (native, Flatpak, and Snap installs) and writes `VAULT_DIR`, the summary subject, and an optional OpenRouter key into `config.env` without touching anything else.
+- Session notes (`bin/sessions.py`): recordings less than `SESSION_GAP_MIN` minutes apart become one note with `[[wikilinks]]` to every transcript and a combined transcript in order; with a key, an AI summary generated from `prompts/session-summary.md`. `list`, `retry`, and `rebuild --date` commands.
+- Plug-in trigger: a systemd user path unit starts a cycle seconds after a drive mounts; `run-cycle.sh --wait` waits for a running cycle instead of skipping.
+- Folder watching (`WATCH_DIRS`): recursive scanning of synced or shared folders; sources found there are never deleted.
+- Desktop notifications with click-to-open (`NOTIFY`), including a failure notice.
+- Headless mode (`HEADLESS`): the progress window is skipped without a display, `zenity` is optional, and the doctor warns when user lingering is off.
+- Optional speaker labels with pyannote.audio (`DIARIZATION`, `./install.sh --with-diarization`).
+- `FILE_SUMMARY` switch for per-recording summaries, and a shared OpenRouter client in `bin/llm.py`.
+- Documentation: Obsidian guide, session notes, headless and Raspberry Pi setup, speaker labels, a README rewrite with the recorder test and the summary workflow, and hero and social preview images.
+- Release workflow (`.github/workflows/release.yml`) and this changelog.
+
+### Changed
+
+- `zenity` is optional at install time; missing desktop tools are warnings in the doctor.
+- The doctor reports the plug-in trigger and validates every new setting.
+
+### Fixed
+
+- Every successful run was recorded as "Transcription failed" in the progress state because the catch-all handler also caught `SystemExit`, so the desktop window could show the failure text at the end of a good run.

usb_audio_transcriber-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Contributions are welcome when they preserve the project's local-first and source-safe behavior.
+
+## Before opening a change
+
+1. Search existing issues and pull requests.
+2. Keep the change focused; avoid unrelated refactors.
+3. Do not include recordings, transcripts, API keys, local configuration, model weights, caches, or runtime state.
+4. For destructive or privacy-affecting behavior, explain the safety boundary explicitly.
+
+## Development workflow
+
+```bash
+git switch -c fix/short-description
+# make the change
+python3 -m py_compile bin/*.py usb_audio_transcriber/*.py
+bash -n install.sh uninstall.sh bootstrap.sh bin/run-cycle.sh
+python3 -m unittest discover -s tests -v
+git diff --check
+```
+
+Use a conventional commit subject such as `fix: preserve queue item after model failure` or `docs: clarify recorder discovery`.
+
+## Tests
+
+Behavior changes should include deterministic tests under `tests/`. Mock expensive model execution and external APIs. Never make CI depend on private audio, API keys, model downloads, desktop access, or a mounted USB device.
+
+If you perform a real-audio test, report hardware, model, device/compute configuration, audio duration, and elapsed time. Do not publish the source or transcript unless you have permission.
+
+## Pull requests
+
+Include:
+
+- what changed and why
+- safety/privacy implications
+- compatibility implications for existing `config.env` files
+- exact verification commands and results
+- screenshots only when the desktop UI changed and the image contains no private information
+
+By contributing, you agree that your contribution is licensed under the repository's MIT license.

usb_audio_transcriber-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aaacharlie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usb_audio_transcriber-1.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: usb-audio-transcriber
+Version: 1.1.0
+Summary: Plug in a voice recorder, walk away, come back to timestamped, searchable notes and a session summary. Local faster-whisper pipeline for Linux.
+Project-URL: Homepage, https://github.com/aaacharlie/usb-audio-transcriber
+Project-URL: Documentation, https://github.com/aaacharlie/usb-audio-transcriber/blob/main/docs/README.md
+Project-URL: Changelog, https://github.com/aaacharlie/usb-audio-transcriber/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/aaacharlie/usb-audio-transcriber/issues
+Author: aaacharlie
+License-Expression: MIT
+License-File: LICENSE
+Keywords: faster-whisper,obsidian,speech-to-text,systemd,transcription,usb,voice-recorder,whisper
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: faster-whisper<2,>=1.2.1
+Requires-Dist: requests>=2.31
+Provides-Extra: diarization
+Requires-Dist: pyannote-audio<4,>=3.1; extra == 'diarization'
+Description-Content-Type: text/markdown
+
+# USB Audio Transcriber
+
+**Plug in a voice recorder. Walk away. Come back to timestamped, searchable notes and a summary of the whole session.**
+
+A free, open-source Linux utility that turns a cheap USB voice recorder (or any synced folder of voice memos) into a hands-off note-taking system. Plug the recorder in and, within seconds, it finds the new recordings, copies them to a checksum-verified archive, transcribes them locally with faster-whisper, and writes timestamped Markdown notes straight into your Obsidian vault or any notes folder. Recordings that a voice-activated recorder split into a dozen files are stitched back into one session note in the right order, with an optional AI summary from a tool you already pay for (Codex, Claude Code), a local Ollama model, or OpenRouter.
+
+Nothing is uploaded: transcription runs on your own CPU, no GPU required.
+
+## Install
+
+```bash
+sudo apt install pipx ffmpeg zenity libnotify-bin      # Debian/Ubuntu names
+pipx install usb-audio-transcriber
+usb-audio-transcriber install
+```
+
+`install` creates `~/.local/share/usb-audio-transcriber/config.env`, asks where your notes should go (it finds your Obsidian vaults), enables the background service and the plug-in trigger, and adds **USB Audio Transcriber** to your app menu: a control panel with the pipeline's state, sessions with a Summarize button, search, and every setting as a form. Everything in the panel is also a command:
+
+```bash
+usb-audio-transcriber doctor            # check the installation
+usb-audio-transcriber sessions list     # session notes
+usb-audio-transcriber search roof leak  # every matching moment, newest first
+usb-audio-transcriber panel open        # the control panel
+usb-audio-transcriber update            # pipx upgrade, then install again
+```
+
+Speaker labels need the optional extra: `pipx install "usb-audio-transcriber[diarization]"`.
+
+Full documentation, the recorder that was tested, and the summary workflow: <https://github.com/aaacharlie/usb-audio-transcriber>.

usb_audio_transcriber-1.1.0/README.md

@@ -0,0 +1,263 @@
+# USB Audio Transcriber
+
+[![CI](https://github.com/aaacharlie/usb-audio-transcriber/actions/workflows/ci.yml/badge.svg)](https://github.com/aaacharlie/usb-audio-transcriber/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Platform: Linux](https://img.shields.io/badge/platform-Linux-informational.svg)](#requirements)
+
+**Plug in a voice recorder. Walk away. Come back to timestamped, searchable notes and a summary of the whole session.**
+
+<p align="center">
+  <img src="docs/assets/how-it-works.svg" alt="Step 1: record with any USB voice recorder, phone, or synced folder. Step 2: plug it in; Whisper transcribes on your own CPU seconds after the drive mounts, nothing is uploaded. Step 3: timestamped notes and session summaries land in your Obsidian vault." width="100%">
+</p>
+
+USB Audio Transcriber is a free, open-source Linux utility that turns a cheap voice recorder into a hands-off note-taking system. Plug the recorder in and, within seconds, it finds the new recordings, copies them to a checksum-verified archive, transcribes them locally with faster-whisper, and writes timestamped Markdown notes straight into your Obsidian vault or any notes folder. When a voice-activated recorder has split a meeting or a class into a dozen files, it stitches them back into one session note in the right order and, if you want, has an AI write the executive summary.
+
+There is no subscription, no per-minute pricing, and no uploading of your audio. Transcription runs on your own CPU with no GPU required, the source recordings stay on the device, and nothing leaves your machine unless you explicitly turn on the optional cloud summary.
+
+## Quick start
+
+On Debian or Ubuntu (other distributions: the same packages under their own names):
+
+```bash
+sudo apt install python3-venv ffmpeg zenity libnotify-bin git
+curl -fsSL https://raw.githubusercontent.com/aaacharlie/usb-audio-transcriber/main/bootstrap.sh | bash
+```
+
+The installer creates a private virtual environment, asks where your notes should go (it finds your Obsidian vaults for you), and enables the background service. Then plug in the recorder. Run the same line again later to update.
+
+Prefer pipx? The same program is a Python package with a `usb-audio-transcriber` command:
+
+```bash
+sudo apt install pipx ffmpeg zenity libnotify-bin
+pipx install git+https://github.com/aaacharlie/usb-audio-transcriber   # pipx install usb-audio-transcriber once it is on PyPI
+usb-audio-transcriber install
+```
+
+Prefer to read the code first? Clone the repository and run `./install.sh`; see [Install](#install).
+
+## What you get
+
+- **Zero-touch workflow.** A systemd user service watches for the recorder. A cycle starts the moment the drive mounts, with a one-minute timer as the safety net. You never run a command after setup.
+- **Session notes with an executive summary.** Recordings less than 20 minutes apart become one session note: links to every transcript, one combined transcript in order, and an AI summary written from a prompt you can edit. The stitching works offline; the summary can use a tool you already pay for (Codex, Claude Code), a local Ollama model, or OpenRouter.
+- **Any folder, not only USB.** Point `WATCH_DIRS` at a Syncthing, Nextcloud, or Dropbox folder and phone voice memos are transcribed too. Files there are never deleted.
+- **Built for Obsidian.** The setup wizard finds your vault. Notes carry YAML front matter and tags, session notes use `[[wikilinks]]`, so backlinks and the graph view just work, and Obsidian Sync or Syncthing carry everything to your phone.
+- **Private by default.** Audio never leaves your computer. Optional summaries send transcript text only, and only to the backend you choose; with Ollama even that stays local.
+- **Never loses a recording.** Every copy is SHA-256 verified before it enters the queue, duplicates are detected by content rather than filename, and the USB source is never deleted unless you opt in.
+- **Speaker labels, optionally.** Turn on pyannote diarization for `Speaker 1` / `Speaker 2` labels, computed locally.
+- **Desktop-friendly.** A progress window with a time estimate, and a notification you can click to open the finished note.
+- **Runs headless.** No desktop? Put it on a Raspberry Pi or a home server and let the notes land in a synced folder.
+- **Search everything from the terminal.** `search.py roof leak` finds every matching moment across all your recordings, newest first, with the timestamp and speaker.
+- **A control panel.** A real desktop window (GTK 4) from your app menu, and a web page for your phone if you like, with the pipeline's state, sessions with a Summarize button, search, and every setting as a form. Everything in it is also a terminal command.
+- **Pick your speed.** `fast` transcribed a 58-minute recording in about 17 minutes on a plain CPU. `accurate` is there for hard audio, and `both` gives you an A/B comparison from the same file.
+
+Good fits: lectures and classes, meetings and site visits, interviews, long phone calls on speaker, and voice memos you would otherwise never listen to again.
+
+## The control panel
+
+<p align="center">
+  <img src="docs/assets/panel-home.png" alt="The control panel window on its Home page: timer and plug-in trigger state, last activity, queue, library counts, and buttons to run a cycle or pause automatic runs" width="100%">
+</p>
+
+Install adds a **USB Audio Transcriber** entry to your app menu. It opens the control panel, a native desktop window (GTK 4 / libadwaita; the same thing is also a web page for your phone or a machine without the GTK bindings): what the pipeline is doing right now, every session with a Summarize button that sends it to the AI tool you choose, search across everything, and every setting as a form with a "Find my Obsidian vault" button. It runs on your machine behind a private link, and each button maps to a script you could run yourself. Details in [the panel guide](docs/panel.md).
+
+## Real-world test: a $50 recorder from Amazon
+
+This project was built around, and tested with, an inexpensive magnetic voice-activated recorder that sells on Amazon for about $50. The listing is titled "136GB(9800H) Magnetic Voice Recorder - Zutiifeu Voice Activated Recorder with DSP5.0 Noise Cancellation HD Recording Device for Classe/Meeting/Lecture". It has been used with this pipeline with lots of success, and the combination is the whole point of the project: a budget recorder plus a Linux box you already own gives you a complete recording-to-notes system.
+
+What it looks like in practice:
+
+1. Record with the device. Voice activation means it can sit for hours and only capture the parts where someone is talking.
+2. Plug it into your Linux machine's USB port. The recorder mounts like an ordinary flash drive and a cycle starts within seconds.
+3. The progress window shows what was found and how long it expects to take. When it is done, a notification appears; click it to open the notes.
+4. Open your vault. Every recording has a dated, timestamped transcript note, and the whole sitting has a session note that ties them together.
+
+Any recorder, phone, or SD card that mounts as a drive and saves into a folder should work the same way. Point `RECORDER_DIR` at the folder your device saves into (the default is `RECORD`) and add your device's file extension to `AUDIO_EXTS` if it is not `mp3`, `wav`, or `m4a`. Recorders other people have tried are collected in the repository's Discussions; please add yours.
+
+This project has no affiliation with the recorder's manufacturer or with Amazon. It is simply the hardware the pipeline was tested on.
+
+## The transcript looks rough? Don't be discouraged
+
+Raw Whisper output from a pocket recorder can look underwhelming at first glance: no paragraphs, misheard names, a sentence that trails off where the voice activation paused, and long sessions split across several files. That is normal, and it is not the finished product.
+
+The raw transcript is the input to the last step. Give the transcripts of a session to a current frontier model (tested with GPT 5.6 Sol) and ask it to put them in order and summarize them. The model reads straight through the transcription noise, reconstructs the flow of the conversation, and returns a very high quality executive summary of the whole session.
+
+The pipeline can do this for you, and it does not need a pay-per-token bill: point `SUMMARY_BACKEND` at a command-line AI tool you already subscribe to (Codex with a ChatGPT plan, Claude Code, Gemini CLI), at a local Ollama model, or at OpenRouter, and tell it what your recordings are about in `SESSION_SUBJECT`. The setup wizard asks exactly these questions and can be re-run any time. Every session note then opens with the summary, generated from [`prompts/session-summary.md`](prompts/session-summary.md), which you can edit.
+
+To do it by hand instead, or with a model of your own choosing:
+
+1. Open the session note in your vault. Its `## Combined transcript` section already has every recording in order. (Without session notes, collect the transcript notes for the sitting; their filenames start with the recording's date and time, so the order is in the names.)
+2. Paste it into one chat with the model.
+3. Use a prompt like this one, replacing the bracketed part with the topic of the recording:
+
+```text
+You are the world's best transcript reader and interpreter, and you are very
+knowledgeable in [insert subject matter]. Can you take all of these audio
+transcript files and put them in the correct order and summarize it completely?
+Make it an amazing, coherent transcript summary in the proper order. Make it
+something better than other AI services like Otter.
+```
+
+Tips that make the summary better:
+
+- Name the subject matter precisely ("commercial real estate financing", "organic chemistry lecture", "quarterly planning meeting"). It helps the model fix misheard jargon and names.
+- Turn on speaker labels, or tell the model who was in the room, so it can attribute what was said.
+- Ask for decisions, action items, and open questions as separate sections if you want a meeting-style report. The bundled prompt already does.
+- Use a model with a large context window so a whole day's notes fit in one request.
+
+Either way, remember that pasting a transcript into a cloud AI sends its text to that provider. Keep sensitive recordings local.
+
+## Documentation
+
+- [Documentation wiki](docs/README.md)
+- [Usage guide](docs/usage.md): workflow, outputs, folder watching, session notes, speaker labels, headless machines
+- [Obsidian](docs/obsidian.md): the setup wizard, what lands in the vault, sync
+- [Configuration reference](docs/configuration.md)
+- [Whisper model profiles and measured trade-offs](docs/model-profiles.md)
+- [Architecture and data lifecycle](docs/architecture.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Privacy and security](docs/privacy-and-security.md)
+- [Development guide](docs/development.md) and [changelog](CHANGELOG.md)
+
+## What it does
+
+1. A user-level systemd path unit starts a cycle when a drive mounts under `/media/$USER`, `/run/media/$USER`, or `/mnt`; a timer also runs a cycle about once per minute.
+2. The cycle finds supported audio files inside the recorder directory (default `RECORD`) on mounted media, plus anything in `WATCH_DIRS`.
+3. It copies new recordings to a local archive and verifies the copy with SHA-256.
+4. It deduplicates future scans using SQLite, then transcribes queued recordings locally with faster-whisper, optionally labelling speakers.
+5. It writes `.json` segments, `.txt` text, a Markdown transcript note, and a `.complete.json` marker that confirms all outputs finished.
+6. It groups the finished recordings into sessions and writes one session note per sitting, with an AI summary when a key is configured.
+7. During transcription a desktop progress dialog shows the active file, number of files, percentage, and ETA; a notification announces the finished notes.
+
+## Privacy and safety
+
+- Transcription and speaker labelling are local. Audio is not uploaded by this project.
+- AI summaries are off until you pick a backend. Then transcript text, never audio, goes to that backend: your own machine with Ollama, the provider behind a subscription tool such as Codex or Claude Code, or OpenRouter.
+- Source audio on the USB drive is never deleted by default (`PURGE_DEVICE=0`), and files in `WATCH_DIRS` are never deleted at all.
+- Do not commit `config.env`: it can contain API keys. The included `.gitignore` excludes it and all runtime data.
+
+## Requirements
+
+- Linux with a user systemd session (desktop or headless)
+- Python 3.10+
+- `ffmpeg` for audio decoding
+- `git` for the one-line installer
+- Optional: `zenity` for the progress window, `libnotify-bin` for notifications, `python3-gi gir1.2-gtk-4.0 gir1.2-adw-1` for the control panel window (already present on most desktops; otherwise the panel opens in a browser)
+- Optional: `pipx` for the package install
+- Internet access the first time faster-whisper downloads the configured model
+
+On Ubuntu/Debian:
+
+```bash
+sudo apt install python3-venv ffmpeg zenity libnotify-bin git
+```
+
+## Install
+
+Three ways to the same installation. Whichever you pick, settings live in `~/.local/share/usb-audio-transcriber/config.env` (`config.example.env` documents every option), the timer and the plug-in trigger become user systemd units, and **USB Audio Transcriber** lands in your app menu.
+
+**The one-line installer** from [Quick start](#quick-start): clones the source under `~/.local/share/usb-audio-transcriber/src`, creates a virtual environment, runs the setup wizard on a fresh configuration, and enables the units. Run it again to update.
+
+**From a clone:**
+
+```bash
+git clone https://github.com/aaacharlie/usb-audio-transcriber.git
+cd usb-audio-transcriber
+./install.sh                      # add --with-diarization for speaker labels
+```
+
+**With pipx**, which keeps the program in its own environment and gives you a `usb-audio-transcriber` command:
+
+```bash
+sudo apt install pipx ffmpeg zenity libnotify-bin
+pipx install git+https://github.com/aaacharlie/usb-audio-transcriber   # or, once published: pipx install usb-audio-transcriber
+usb-audio-transcriber install     # add --with-diarization for speaker labels
+```
+
+`usb-audio-transcriber install` does what `install.sh` does apart from the virtual environment (pipx made one): the data folder, `config.env`, the doctor gate, the wizard, the units, and the menu entry. Every script is then a subcommand: `usb-audio-transcriber doctor`, `sessions list`, `search roof leak`, `model-cache status both`, `panel open`, `setup`, `cycle`, `paths`.
+
+### Update an existing installation
+
+One-line installer or clone:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/aaacharlie/usb-audio-transcriber/main/bootstrap.sh | bash
+# or, in the clone: git pull --ff-only && ./install.sh
+```
+
+pipx:
+
+```bash
+usb-audio-transcriber update      # pipx upgrade, then install again
+```
+
+Either way the installed `config.env` is preserved.
+
+### Uninstall
+
+```bash
+./uninstall.sh                    # one-line installer or clone
+usb-audio-transcriber uninstall && pipx uninstall usb-audio-transcriber   # pipx
+```
+
+This removes deployed code, the virtual environment, and the user systemd units. It deliberately preserves `config.env`, runtime state, archives, transcripts, and model caches so uninstalling cannot silently erase user data.
+
+## Status and logs
+
+```bash
+systemctl --user status usb-audio-transcriber.timer
+systemctl --user status usb-audio-transcriber-plug.path
+systemctl --user status usb-audio-transcriber.service
+journalctl --user-unit=usb-audio-transcriber.service -f
+```
+
+The pipeline also logs to `~/.local/share/usb-audio-transcriber/var/logs/pipeline.log`.
+
+Run the built-in diagnostic after installation or whenever setup fails:
+
+```bash
+~/.local/share/usb-audio-transcriber/venv/bin/python \
+  ~/.local/share/usb-audio-transcriber/bin/doctor.py
+```
+
+It checks configuration, required commands and Python packages, writable output locations, the timer, and the plug-in trigger without creating recordings or transcript data.
+
+## Configuration
+
+`config.example.env` documents all options. The ones people change:
+
+- `VAULT_DIR`: where Markdown notes go; the wizard points it at a folder inside your Obsidian vault.
+- `WATCH_DIRS`: extra folders to scan, colon-separated, for synced phone memos or shares.
+- `RECORDER_DIR` and `AUDIO_EXTS`: the folder name and file types your recorder uses.
+- `WHISPER_MODEL_PROFILE`: `fast`, `accurate`, or `both`.
+- `SUMMARY_BACKEND` and its companions: optional AI summaries through a subscription command-line tool, a local Ollama model, or OpenRouter; `SESSION_SUBJECT` tells the model the topic.
+- `SESSION_GAP_MIN`: how long a silence has to be before a new session starts (20 minutes).
+- `DIARIZATION` and `HF_TOKEN`: optional speaker labels.
+- `HEADLESS` and `NOTIFY`: desktop window and notifications, `auto` by default.
+- `PANEL_BIND` and `PANEL_PORT`: where the control panel listens; `0.0.0.0` lets your phone open it.
+- `PURGE_DEVICE`: leave at `0` unless you explicitly want copied recordings removed from the USB device.
+
+### Whisper model choices
+
+| Profile | Model | Pros | Cons |
+| --- | --- | --- | --- |
+| `fast` | `distil-large-v3` | Fastest supported option; lower disk, RAM, and CPU cost | Can be less reliable on distant, overlapping, or otherwise difficult speech |
+| `accurate` | `large-v3` | Best accuracy-oriented option; more robust on difficult audio | Substantially slower on CPU; about 2.9 GiB of disk cache |
+| `both` | both models | Produces a direct A/B comparison from the same recording | Takes the combined runtime and disk space of both models |
+
+In one real CPU benchmark of a 57m 45s recording, `distil-large-v3` finished in 16m 56s while `large-v3` took 89m 57s: 5.31 times longer. That run was CPU-only on a GEEKOM X16 laptop (NX16AM): an Intel Core Ultra 9 185H (16 cores / 22 threads), 32 GB RAM, integrated graphics, running Ubuntu 26.04 LTS with GNOME — a consumer laptop, not a GPU workstation. Treat it as one hardware/audio data point, not a universal benchmark. See [Whisper model profiles](docs/model-profiles.md) for the complete result and interpretation.
+
+Models are loaded into RAM only while they are being used, and downloaded weights stay in the Hugging Face disk cache. Manage them with `bin/model-cache.py status|download|remove`, and compare models on one file without touching the live queue with `bin/benchmark-models.py`; both are described in the [usage guide](docs/usage.md).
+
+## Development checks
+
+```bash
+python3 -m py_compile bin/*.py
+bash -n install.sh uninstall.sh bootstrap.sh bin/run-cycle.sh
+python3 -m unittest discover -s tests -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a change. Report security issues privately according to [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

usb_audio_transcriber-1.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy
+
+## Supported version
+
+Security fixes are applied to the current `main` branch and included in the next tagged release. Only the latest release and `main` are supported; there are no separate support windows for older versions.
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting feature for this repository when available. If it is unavailable, contact the repository owner privately through their GitHub profile rather than opening a public issue.
+
+Include:
+
+- affected component and commit
+- reproduction steps using non-sensitive test data
+- realistic impact
+- suggested mitigation, if known
+
+Do not attach API keys, private recordings, transcripts, local configuration, filesystem listings containing sensitive names, or other personal data.
+
+## Expected response
+
+This is a small open-source project without a guaranteed response SLA. Reports will be acknowledged and evaluated as availability permits. Confirmed issues should be fixed privately before coordinated disclosure when practical.
+
+## Scope reminders
+
+A report is especially relevant when it concerns unintended audio/transcript disclosure, unsafe source deletion, command execution, credential exposure, path traversal, or bypass of deduplication/archive integrity guarantees. General upstream issues in faster-whisper, CTranslate2, requests, Hugging Face, OpenRouter, Python, systemd, or Zenity should also be reported to the affected upstream project.