Skip to content
m0x6APublic

About

Record what is said, transcribe it, and rewrite it into a Markdown note in a format you define

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

saidwork

Record what is said (microphone and/or what the computer plays), transcribe it with a speech-to-text model, and let a second model rewrite the transcript into a Markdown note in a format you define.

saidwork            # interactive terminal UI
saidwork record     # headless: Enter stops, note path is printed

How it works

  1. Capture – microphone and system audio (the default sink's monitor) are captured through PipeWire's PulseAudio interface, resampled to 16 kHz mono and mixed.
  2. Transcribe – the WAV is posted to an OpenAI-compatible /v1/audio/transcriptions endpoint (whisper.cpp whisper-server, faster-whisper, Groq, OpenAI, …).
  3. Rewrite – the transcript plus the chosen format template are sent to a chat model (Ollama /api/chat or OpenAI-compatible /v1/chat/completions).
  4. Save – the note lands in your notes directory as YYYYMMDD-HHMMSS-<format>-<title>.md. The raw WAV and transcript are kept under the data directory so a note can be regenerated with another format (saidwork rewrite).

Local servers can be started on demand: give a provider a launch block and saidwork spawns it when it is not answering, waits for the health check, and stops it on exit.

Install

Each GitHub release ships x86_64 Linux packages that pull in the one runtime library, libpulse, for you, and a Windows zip:

sudo dnf install ./saidwork-*.x86_64.rpm      # Fedora, RHEL, openSUSE (zypper install)
sudo apt install ./saidwork_*_amd64.deb       # Debian, Ubuntu
./install.sh                                  # from the tarball, any other distro
.\install.ps1                                 # from the Windows zip, in PowerShell

Then pick a configuration and let saidwork tell you what else to install:

saidwork config presets                        # local, whisper-ollama, openai
saidwork config init                           # writes ~/.config/saidwork/saidwork.toml + formats
saidwork doctor                                # checks audio, providers and their dependencies

docs/INSTALL.md is the full guide: building from source, what each preset needs and how to install it, where files live, and troubleshooting.

Edit the providers in saidwork.toml (see config/saidwork.example.toml and config/presets/), then:

saidwork providers status        # probe endpoints
saidwork devices                 # list microphones and system-audio monitors
saidwork formats list            # the Markdown formats in ~/.config/saidwork/formats
saidwork                         # start the TUI: r record/stop, ↑/↓ format, n/e/o editor, q quit

Logs go to ~/.local/share/saidwork/saidwork.log (RUST_LOG=debug for more). Set SAIDWORK_HOME=/some/dir to keep config, data and notes under one directory.

Local models (the default configuration)

The example config is wired for a fully local, Swedish-first setup:

  • Transcription: Klang Pianissimo (KlangAI/pianissimo-sv, a Parakeet v3 fine-tune, CC BY 4.0) served by tools/pianissimo-server/server.py (installed as /usr/share/saidwork/pianissimo-server/server.py), a small OpenAI-compatible server around onnx-asr and Klang's int8 ONNX export. It runs on the CPU at roughly 35× realtime, splits long recordings at pauses with Silero VAD, and needs only uv: saidwork starts it with uv run {share}/pianissimo-server/server.py --port 8178 and the first start downloads about 660 MB.
  • Rewriting: Gemma 4 12B on llama.cpp through an OpenAI-compatible llama-server on port 8080, started on demand with -hf ggml-org/gemma-4-12B-it-GGUF:Q4_0 (downloaded on the first start) and --reasoning-budget 0 so the answer is the note itself rather than its reasoning.

Swap either for whisper.cpp, Ollama or a hosted API by editing the provider block, or start from another preset (saidwork config presets); config/presets/ shows the shapes.

Formats

A format is a Markdown file with YAML frontmatter:

---
name: Meeting notes
description: Structured minutes from a meeting or call.
when_to_use: Several people discussing topics, decisions and work items.
---
# {{title}}
## Summary
...

The body is handed to the rewriting model as the template to follow; {{date}} and {{title}} are filled in. when_to_use is reserved for a future selector that lets the LLM pick the format from the transcript.

The built-in formats (conversation, the default, plus meeting-notes, journal-entry and task-list) are written to the formats directory at startup if they have never been installed there, so new built-ins arrive with upgrades. Installed ones are tracked in .installed-builtins in that directory, so a built-in you delete stays deleted. One you have edited is never overwritten; saidwork warns that it differs from the shipped version, and saidwork formats reset <id> puts the shipped version back (or brings back a deleted one).

Editing in your editor

Formats and notes open in $VISUAL, else $EDITOR, else nvim:

saidwork formats new             # start from a skeleton; the id comes from `name`
saidwork formats edit task-list  # edit an existing format
saidwork formats reset task-list # restore a built-in to the shipped version
saidwork record --review         # open the finished note when it is saved (also `rewrite`)

In the TUI, n defines a new format, e edits the selected one and o opens the note that was just saved; the interface comes back when you quit the editor.

Formats are edited as drafts under the data directory and only saved when they still parse, so a mistake never breaks the format list. A rejected draft is kept and reopened the next time, and saving a draft unchanged does nothing.

Architecture

A modular monolith: one Cargo workspace, one crate per vertical slice, hexagonal ports/adapters inside each slice, and an application crate that composes them.

crates/kernel         clock, paths, secrets, retry, url helpers (no business rules)
crates/formats        Format templates: parsing, filesystem repository, selector port
crates/providers      Provider registry, API keys, health probe, on-demand launcher
crates/transcription  Transcriber port + OpenAI-compatible adapter
crates/rewriting      Rewriter port, prompt builder, OpenAI-chat and Ollama adapters
crates/capture        AudioBackend port, mixer, WAV, Pulse (Linux), WASAPI (Windows), fake
crates/notes          NoteStore port + filesystem adapter
crates/app            Config, bootstrap, the record→transcribe→rewrite→save pipeline
crates/tui            ratatui UI (Elm-style model / update / view)
crates/saidwork       clap binary: TUI by default, headless subcommands

Slices never depend on each other; app maps between their models. Other platforms (macOS) compile without a native audio backend today; adding one means implementing AudioBackend (the Windows one uses cpal) in crates/capture/src/adapters.

Development

just check     # cargo fmt --check, clippy -D warnings (pedantic), cargo test
cargo test -p saidwork-capture -- --ignored    # hardware smoke test against the sound server

Tests use fakes for audio, transcription and rewriting, wiremock for the HTTP adapters, insta snapshots for prompts and screens, and proptest for the mixer.

CI (.github/workflows/ci.yml) runs the same checks on Linux and Windows plus an MSRV build on every push and pull request. Pushing a v* tag builds the x86_64 Linux tarball, .deb and .rpm (packaging/install.sh, [package.metadata.deb] and [package.metadata.generate-rpm] in crates/saidwork/Cargo.toml) and the Windows zip (packaging/install.ps1), and attaches them with one SHA256SUMS to a GitHub release:

git tag v0.1.0 && git push origin v0.1.0

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

About

Record what is said, transcribe it, and rewrite it into a Markdown note in a format you define

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages