Skip to content
lightheadedPublic

About

Local, diarized speech-to-text for Apple Silicon Macs. First-class Estonian and English.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

kuula

kuula (Estonian: "listen!") is local, diarized speech-to-text for Apple Silicon Macs, with first-class Estonian and English support.

Point it at an audio file, a video, or your Apple Voice Memos library and get a clean, speaker-labelled transcript in markdown. Everything runs on-device with MLX and Core ML; no audio, text or telemetry ever leaves your machine, and no accounts or API keys are needed.

Speaker 1 (00:00): Good morning everyone. Let's get started with the quarterly review.
Speaker 2 (00:10): Thanks for having me. I reviewed the numbers last night...

Quickstart

brew install lightheaded/tap/kuula
kuula setup

Or with uv (PyPI release pending; install from GitHub):

brew install ffmpeg
uv tool install --python 3.13 git+https://github.com/lightheaded/kuula
kuula setup

Then:

kuula memos --latest        # transcribe your newest Voice Memo
kuula meeting.m4a           # transcribe any audio/video file

kuula setup walks you through everything interactive: model downloads, Voice Memos access, and the Finder right-click Quick Action. kuula doctor re-checks the installation any time.

Why kuula

  • Private by construction. Recordings of meetings and 1-1s are sensitive. kuula never uploads anything, anywhere.
  • Estonian is a first-class citizen. Generic multilingual models garble Estonian and mixed Estonian/English speech. kuula auto-detects the language and routes Estonian audio to TalTech's verbatim Estonian Whisper model, which handles code-switched English embedded in Estonian speech remarkably well.
  • Speakers are labelled. Diarization is on by default via senko - no Hugging Face account, no gated models, works offline.
  • Voice Memos without friction. kuula memos reads your Voice Memos library directly (titles, dates, durations), so "transcribe yesterday's 1-1" is one command. No exporting, no dragging files.
  • Fast. Roughly 8-10x real time for diarized transcription on an M-series Pro - a 30-minute meeting takes about 3 minutes. The opt-in parakeet engine is faster still.

Usage

kuula memos                          # list recordings, newest first
kuula memos --latest                 # transcribe the newest
kuula memos "standup"                # transcribe by title match
kuula memos "standup" --all          # ...all matches
kuula transcribe interview.mp3       # any audio or video file
kuula interview.mp3                  # shorthand for the above
kuula call.m4a -f srt                # subtitle output
kuula call.m4a --stdout -f json      # JSON to stdout for scripting
kuula call.m4a -l et                 # force Estonian
kuula call.m4a -d none               # skip diarization (faster)

Transcripts from files land next to the file; transcripts from Voice Memos land in ~/Downloads. Override with -o.

Output formats: md (default, with a YAML provenance header - disable with --no-frontmatter), txt, srt, vtt, json.

Right-click transcription

kuula setup installs a Finder Quick Action: right-click any audio/video file -> Quick Actions -> Transcribe with kuula. Notifications report progress; the transcript appears next to the file. See integrations/quick-action.

For transcribing straight from the Voice Memos app via the share sheet, see integrations/shortcuts.

Claude Code skill

The repo ships a skill that teaches Claude Code to drive kuula ("transcribe my latest voice memo and summarise the decisions"). Install:

ln -sfn "$(pwd)/skills/kuula" ~/.claude/skills/kuula

Languages, engines and models

Audio Engine Model
Estonian (incl. mixed ET/EN) mlx-whisper TalTechNLP/whisper-large-v3-turbo-et-verbatim-2604 (MIT)
Everything else mlx-whisper mlx-community/whisper-large-v3-turbo (MIT)
--engine parakeet (opt-in) parakeet-mlx nvidia/parakeet-tdt-0.6b-v3 (CC-BY-4.0)

Whisper output is lightly normalised (fillers dropped, tidy punctuation), which reads better for meeting notes. Parakeet is faster and fully verbatim - "uh"s and all - covering English and 24 other European languages; reach for it with --engine parakeet when speed or strict verbatimness matters.

With --lang auto (the default) kuula samples a few windows of the audio with a small Whisper model and votes on the language; Estonian wins ties because mixed Estonian/English meetings transcribe far better on the Estonian model than the other way round. Models are downloaded on first use (or ahead of time by kuula setup) and cached; the Estonian checkpoint is converted to MLX format once, locally.

Diarization

  • senko (default): narcotic-sh/senko, Core ML-accelerated, MIT-licensed, no accounts or tokens. Language-agnostic acoustics.

  • pyannote (optional upgrade): the strongest open diarization, pyannote/speaker-diarization-community-1. The model is free but gated on Hugging Face, so it stays opt-in:

    uv tool install --python 3.13 'kuula[pyannote]'
    # accept the terms at https://huggingface.co/pyannote/speaker-diarization-community-1
    # create a read token at https://huggingface.co/settings/tokens
    export HF_TOKEN=...            # your own token; kuula never stores it
    kuula meeting.m4a --diarizer pyannote --speakers 2

Requirements

  • Apple Silicon Mac (the ASR engines are MLX-based)
  • macOS 13+; kuula memos tested against the current Voice Memos database format
  • Python 3.11-3.13 (uv handles this for you), ffmpeg
  • kuula memos needs your terminal to have Full Disk Access (System Settings -> Privacy & Security); kuula setup guides you there. Transcribing ordinary files needs no special permissions.

How it works

input -> ffmpeg (16 kHz mono wav) -> language probe (whisper-base)
      -> ASR (parakeet-mlx | mlx-whisper) -> segments
      -> diarizer (senko | pyannote)      -> speaker turns
      -> overlap merge -> md / txt / srt / vtt / json

The Voice Memos integration reads a temporary copy of the library's SQLite database (never the live one, never writing into Apple's folder). If Apple changes the schema, kuula falls back to plain file listing.

Licence and attribution

kuula itself is MIT. It stands on excellent open work, downloaded at runtime and never redistributed here:

About

Local, diarized speech-to-text for Apple Silicon Macs. First-class Estonian and English.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages