Skip to content
BranchesTags

Repository files navigation

ownscribe

PyPI CI License: MIT Python 3.12+

Local-first meeting transcription and summarization CLI. Record, transcribe, and summarize meetings and system audio entirely on your machine – no cloud, no bots, no data leaving your device.

System audio capture requires macOS 14.2 or later. Other platforms can use the sounddevice backend with an external audio source.

Table of Contents

Privacy

ownscribe does not:

  • send audio to external servers
  • upload transcripts
  • require cloud APIs
  • store data outside your machine

All audio, transcripts, and summaries remain local.

ownscribe demo

Features

  • System audio capture — records all system audio natively via Core Audio Taps (macOS 14.2+), no virtual audio drivers needed
  • Microphone capture — records system + mic audio simultaneously by default (press m to mute/unmute, or use --no-mic)
  • WhisperX transcription — fast, accurate speech-to-text with word-level timestamps
  • Speaker diarization — optional speaker identification via pyannote (requires HuggingFace token)
  • Pipeline progress — live checklist showing transcription, diarization sub-steps, and summarization progress
  • Local LLM summarization — structured meeting notes with a built-in model (Phi-4-mini); also supports Ollama, LM Studio, or any OpenAI-compatible server
  • Summarization templates — built-in presets for meetings, lectures, and quick briefs; define your own in config
  • Ask your meetings — ask natural-language questions across all your meeting notes; uses a two-stage LLM pipeline with keyword fallback
    ownscribe ask demo
  • Silence auto-stop — automatically stops recording after sustained silence (default: 5 minutes, configurable)
  • One command — just run ownscribe, press Ctrl+C when done, get transcript + summary

Requirements

  • macOS 14.2+ on Apple Silicon (for system audio capture)
  • Python 3.12+
  • uv
  • ffmpeg — brew install ffmpeg
  • Xcode Command Line Tools (xcode-select --install)

Summarization works out of the box — a local model (Phi-4-mini, ~2.4 GB) downloads automatically on first run. Optionally, you can use Ollama, LM Studio, or any OpenAI-compatible server instead (see Configuration).

Works with any app that outputs audio through Core Audio (Zoom, Teams, Meet, etc.).

Apple Silicon only. The ownscribe-audio capture helper is published for arm64 only. On an Intel Mac, ownscribe says so and falls back to microphone-only recording; build the helper yourself with bash swift/build.sh to capture system audio there. Transcription and summarization work on any platform.

Tip: Your terminal app (Terminal, iTerm2, VS Code, etc.) needs Screen Recording permission to capture system audio. Open the settings panel directly with:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

Enable your terminal app, then restart it. Both capture modes need this permission, picker and all alike.

The microphone is recorded by default, so macOS also asks for Microphone permission on the first run. If you dismissed that prompt, enable your terminal app here:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone"

Recording fails to start while the microphone is unavailable — use --no-mic to capture system audio only.

Installation

Quick start with uvx

uvx ownscribe

On macOS, the Swift audio capture helper is downloaded automatically on first run.

Alternative summarization backends

The built-in local model works out of the box. If you'd rather call a hosted backend, install the matching extra:

uv add 'ownscribe[ollama]'   # use Ollama
uv add 'ownscribe[openai]'   # use any OpenAI-compatible server (LM Studio, llama-server, etc.)
uv add 'ownscribe[all]'      # install both

Homebrew

There is no brew formula: Homebrew builds Python dependencies from source, which doesn't work well for the PyTorch and llama-cpp-python stack. The closest thing is installing uv via brew and letting it manage a global ownscribe command:

brew install uv
uv tool install 'ownscribe[all]'

From source

# Clone the repo
git clone https://github.com/paberr/ownscribe.git
cd ownscribe

# Build the Swift audio capture helper (optional - auto-downloads if skipped)
bash swift/build.sh

# Install with all backends
uv sync --extra all

# Make the `ownscribe` command available globally (editable: changes to the
# checkout take effect without reinstalling)
uv tool install --editable .

When installed from source, the ownscribe command lives inside the project's virtual environment, so run it with uv run from the repo directory:

uv run ownscribe          # equivalent to the bare `ownscribe` used below

Alternatively, activate the environment once (source .venv/bin/activate) and then call ownscribe directly. The examples in Usage use the bare ownscribe form, which works after activation or via uvx ownscribe.

Usage

Record, transcribe, and summarize a meeting

ownscribe                    # records system audio + mic, Ctrl+C to stop

This will:

  1. Capture system audio and your microphone until you press Ctrl+C (or auto-stop after 5 minutes of silence); press m to mute/unmute the mic while recording
  2. Transcribe with WhisperX
  3. Summarize with your local LLM
  4. Save everything to ~/ownscribe/YYYY-MM-DD_HHMM/, renamed to ~/ownscribe/YYYY-MM-DD_HHMM_meeting-title/ once the summary produces a title

Note: By default, ownscribe records all system audio directly with no prompt. To show a macOS source picker on each launch instead, set capture_mode = "picker" in the [audio] config section.

On first run, WhisperX / pyannote and the summarization model may download model files. ownscribe shows a Preparing models step and best-effort download progress in the TUI while this happens. Use ownscribe warmup to pre-download all models.

Options

ownscribe --no-mic                            # capture system audio only (the mic is on by default)
ownscribe --mic-device "MacBook Pro Microphone" # capture system audio + a specific mic instead of the default one
ownscribe --device "MacBook Pro Microphone"   # use mic instead of system audio
ownscribe --no-summarize                      # skip LLM summarization
ownscribe --diarize                           # enable speaker identification
ownscribe --language en                       # set transcription language (default: auto-detect)
ownscribe --model large-v3                    # use a larger Whisper model
ownscribe --format json                       # output as JSON instead of markdown
ownscribe --no-keep-recording                 # auto-delete WAV files after transcription
ownscribe --template lecture                  # use the lecture summarization template
ownscribe --silence-timeout 600               # auto-stop after 10 minutes of silence
ownscribe --silence-timeout 0                 # disable silence auto-stop

Subcommands

ownscribe devices                  # list audio devices (uses native CoreAudio when available)
ownscribe apps                     # list running apps with PIDs for use with --pid
ownscribe warmup                   # prefetch WhisperX/pyannote models before a meeting
ownscribe transcribe recording.wav # transcribe an audio or video file: wav/mp3/mp4/mov/mkv (saved alongside)
ownscribe summarize transcript.md  # summarize a transcript (saves alongside the input)
ownscribe resume ./2026-02-20_1736 # resume a partial run, or process a folder's audio/video recording
ownscribe ask "question"           # search your meetings with a natural-language question
ownscribe config                   # open config file in $EDITOR
ownscribe cleanup                  # remove ownscribe data from disk

Video files work too. Anywhere ownscribe accepts an audio file it also accepts a video container (mp4, mov, mkv, m4v) — it extracts the audio track via ffmpeg. To turn a recording into full notes, drop it in a folder and run ownscribe resume ./that-folder/ (transcript + summary); use ownscribe transcribe meeting.mp4 for a transcript only.

Use warmup ahead of time to avoid first-run model download delays while recording:

ownscribe warmup                    # prefetch Whisper model (+ diarization if enabled in config)
ownscribe warmup --language en      # also prefetch alignment model for English
ownscribe warmup --with-diarization # force diarization warmup for this run

Searching Meeting Notes

Use ask to search across all your meeting notes with natural-language questions:

ownscribe ask "What did Anna say about the deadline?"
ownscribe ask "budget decisions" --since 2026-01-01
ownscribe ask "action items from last week" --limit 5

This runs a two-stage pipeline:

  1. Find — sends meeting summaries to the LLM to identify which meetings are relevant
  2. Answer — sends the full transcripts of relevant meetings to the LLM to produce an answer with quotes

If the LLM finds no relevant meetings, a keyword fallback searches summaries and transcripts directly.

Configuration

Config is stored at ~/.config/ownscribe/config.toml. Run ownscribe config to create and edit it.

[audio]
backend = "coreaudio"     # "coreaudio" or "sounddevice"
device = ""               # empty = system audio
mic = true                # also capture microphone input
mic_device = ""           # specific mic device name (empty = default)
capture_mode = "all"      # "all" = capture all system audio directly; "picker" = show source picker
silence_timeout = 300     # seconds of silence before auto-stop; 0 = disabled

[transcription]
model = "base"            # tiny, base, small, medium, large-v3
language = ""             # empty = auto-detect
threads = 0               # CPU threads for transcription; 0 = auto-detect from core count
# initial_prompt = ""     # prime Whisper with context: domain vocab, speaker names, expected phrases
# hotwords = ""           # comma-separated words to boost recognition (softer hint than initial_prompt)

[diarization]
enabled = false
hf_token = ""             # HuggingFace token for pyannote
telemetry = false         # allow HuggingFace Hub + pyannote metrics telemetry
device = "auto"           # "auto" (mps if available), "mps", or "cpu"

[summarization]
enabled = true
backend = "local"         # "local" (built-in, no server needed), "ollama", or "openai"
model = "phi-4-mini"      # local: "phi-4-mini", path to GGUF, or hf:owner/repo/file.gguf; ollama/openai: model name
# host = "http://localhost:11434"  # only for ollama/openai backends
# api_key = ""            # only for openai backend; required by servers like oMLX (or set OPENAI_API_KEY)
# template = "meeting"    # "meeting", "lecture", "brief", or a custom name
# context_size = 0        # context window in tokens; 0 = auto-detect (8192 for local). Longer
                          # transcripts are summarized in chunks and merged, whatever the size.

# Custom templates (optional):
# [templates.my-standup]
# system_prompt = "You summarize daily standups."
# prompt = "List each person's update:\n{transcript}"

[output]
dir = "~/ownscribe"
audio_dir = ""            # directory for audio recordings; empty = same as dir
format = "markdown"       # "markdown" or "json"
keep_recording = true     # false = auto-delete WAV after transcription

Precedence: CLI flags > environment variables (HF_TOKEN, OLLAMA_HOST, OPENAI_API_KEY) > config file > defaults.

Summarization Templates

Built-in templates control how transcripts are summarized:

Template Best for Output style
meeting Meetings, standups, 1:1s Summary, Key Points, Action Items, Decisions
lecture Lectures, seminars, talks Summary, Key Concepts, Key Takeaways
brief Quick overviews 3-5 bullet points

Use --template on the CLI or set template in [summarization] config. Default is meeting.

Define custom templates in config:

[templates.my-standup]
system_prompt = "You summarize daily standups."
prompt = "List each person's update:\n{transcript}"

Then use with --template my-standup or template = "my-standup" in config.

Long meetings

Transcripts that do not fit the model's context window are summarized in overlapping chunks split on segment boundaries, and the partial notes are then merged into one summary under the same template — custom templates included. Shorter meetings are summarized in a single pass as before. Set context_size in [summarization] if a model's window should not be auto-detected; for the local backend it also sets the window the model is loaded with.

Speaker Diarization

Speaker identification requires a HuggingFace token with access to the pyannote diarization model:

  1. Accept the terms for pyannote/speaker-diarization-community-1 on HuggingFace
  2. Create a token at https://huggingface.co/settings/tokens
  3. Set HF_TOKEN env var or add hf_token to config
  4. Run with --diarize

On Apple Silicon Macs, diarization automatically uses the Metal Performance Shaders (MPS) GPU backend for ~10x faster processing. Set device = "cpu" in the [diarization] config section to disable this.

Acknowledgments

ownscribe builds on some excellent open-source projects:

Contributing

See CONTRIBUTING.md for development setup, tests, and open contribution areas.

License

MIT

About

Local-first meeting transcription and summarization CLI

Topics

clilmstudiolocal-firstmacosmeeting-notesollamaprivacytranscriptionwhisper

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

97 stars

Watchers

1 watching

Forks

44 forks
Report repository

Releases

Packages

Contributors

Languages