tamlil

<p align="center"> <img src="docs/assets/logo.png" width="140" alt="Tamlil"> </p> <h1 align="center">Tamlil</h1> <p align="center"> <strong>Automatic, private transcription for meetings that mix Hebrew and English.</strong> </p> <p align="center"> <a href="https://github.com/Steven17D/tamlil/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Steven17D/tamlil/ci.yml?branch=main&label=CI" alt="CI status"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License: Apache-2.0"></a> <a href="Tamlil/Package.swift"><img src="https://img.shields.io/badge/macOS-15%2B-black" alt="macOS 15+"></a> <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.12-blue" alt="Python 3.12"></a> </p>

Tamlil is a macOS menu-bar app that records your Zoom and Slack calls and turns them into clean, speaker-labeled transcripts — even when the conversation switches between Hebrew and English in the middle of a sentence. It starts recording on its own when a call begins, and the transcript is waiting for you the moment you hang up. Everything stays on your Mac; all that ever leaves it is the transcription request — the call audio plus a short recognition hint (meeting title, attendee names, learned terms) — and Tamlil deletes the upload from the provider as soon as the transcript comes back.

<p align="center"> <img src="docs/assets/hero.png" width="760" alt="Tamlil in the macOS menu bar: a popover showing a Hebrew-and-English meeting transcript with speaker labels and inline dual-track audio playback"> </p>

Why Tamlil

• It records itself. Join a Zoom call or a Slack huddle and Tamlil starts capturing; hang up and the transcript builds automatically. Nothing to launch, click, or remember to turn on.
• Built for Hebrew and English together. Most transcribers make you pick one language per meeting. Tamlil keeps up with real bilingual speech, tagging each word's language, so a sentence that starts in Hebrew and ends in English comes out right.
• Every speaker labeled — and playable. Your side and the other side are separated and named, and the finished recording plays back inline with a waveform, so you can jump to any line and hear exactly what was said.
• Correct it as you read; it remembers. Tamlil flags the words it was unsure of right in the transcript. Fix one and it learns the term for every future meeting, so your names, products, and jargon stop coming back wrong.
• Private by default. Recordings, transcripts, and your learned vocabulary live only on your Mac. Your API key sits in the Keychain, never in a file. After each meeting Tamlil deletes both the audio and the transcript from the provider, so nothing lingers off your device.
• Answers from your AI assistant. A read-only connector lets Claude Code or Codex read your finished meetings and answer questions or draft summaries.

A look inside

<table> <tr> <td width="50%" valign="top" align="center"> <img src="docs/assets/calls-log.png" alt="Tamlil menu-bar list of recorded meetings with their status"> <em>Every call in one list — recording, processing, or ready to read.</em> </td> <td width="50%" valign="top" align="center"> <img src="docs/assets/review.png" alt="A transcript with low-confidence words flagged inline for one-click correction"> <em>Unsure words are flagged inline; fix one and Tamlil learns it for good.</em> </td> </tr> </table>

Install

One command. You need macOS 15 (Sequoia) or later on an Apple-Silicon Mac and the Xcode Command Line Tools 16 or later (xcode-select --install; the build needs their Swift 6 toolchain); the installer handles everything else.

curl -fsSL https://raw.githubusercontent.com/Steven17D/tamlil/main/scripts/install.sh | zsh

It clones Tamlil, builds and installs the app, puts the transcript connector on your PATH, asks for your Soniox API key (from console.soniox.com), and launches. The first time a call records, macOS asks you to approve Microphone and System Audio Recording — say yes. Re-running the command updates an existing install. Optional meeting titles from Google Calendar need a one-time OAuth-client setup first — see Google Calendar setup.

<details> <summary>Prefer to install by hand?</summary>

git clone https://github.com/Steven17D/tamlil.git
cd tamlil
uv sync                                     # Python deps (install uv from astral.sh/uv)
make app                                    # build Tamlil.app
rm -rf /Applications/Tamlil.app && cp -R Tamlil/dist/Tamlil.app /Applications/
defaults write dev.dashevsky.tamlil repoPath "$PWD"
scripts/launch-agent.sh restart            # launch under crash supervision

# store your Soniox key in the Keychain (never in a file)
security add-generic-password -s tamlil-soniox -a soniox -w "<KEY>" -U

To read meetings from an AI agent, also put the connector on your PATH: uv tool install --force . then claude mcp add tamlil --scope user -- "$HOME/.local/bin/tamlil-mcp".

</details>

Updating. Click Check for updates in the menu, or re-run the install command — Tamlil pulls the latest, rebuilds from source, and relaunches.

How it works

1. Join a call. When a call app (Zoom, or a Slack call or huddle) starts using your microphone, Tamlil records two local tracks: your mic and the meeting's system audio.
2. Hang up. Recording stops with the call, and transcription runs automatically on the finished recording.
3. Read the transcript. The two tracks are transcribed, merged and speaker-labeled, cleaned of mic echo, and rewritten through your learned vocabulary. The finished transcript appears in the menu-bar app and is saved under ~/Recordings/Tamlil/.
4. Ask an agent (optional). Claude Code or Codex reads finished meetings over the read-only connector and writes its own summaries.

For how the menu-bar app, pipeline, transcription, lexicon, connector, and Google Calendar fit together, see the architecture overview.

Privacy and data handling

Tamlil records real meeting audio, so it is worth being precise about what leaves your machine and what does not. The transcription provider is Soniox; the facts below are grounded in Soniox's published Terms of Service and Privacy Policy (both last updated 2026-06-29). docs/soniox-data-processing.md has the full write-up and sources.

• What is captured. Two local audio tracks per meeting: your microphone (raw/mic.wav) and the meeting app's system audio (raw/system.wav). Recording starts automatically when a call app begins capturing your mic.
• What leaves your machine. Traffic to two services, nothing else. The two audio tracks are uploaded to Soniox's async speech-to-text API (default endpoint api.soniox.com), and each request carries a recognition hint — the meeting title, attendee names, and learned lexicon terms — so Soniox spells them correctly. If you connect Google Calendar, meeting titles and attendee names are read from it. The read-only connector serves agents locally and sends nothing anywhere.
• Training and secondary use. Soniox commits, in its binding Terms of Service and again in its Privacy Policy, that it does not use customer content to "train, fine-tune, evaluate, benchmark, or improve" its models or services, and that it does not sell it. This is the default; no opt-in is required.
• Retention. The async API is Soniox's storage service: uploaded audio and the resulting transcript are stored server-side with no automatic deletion, so cleanup is the caller's responsibility. After each run the pipeline deletes the stored transcription, which also removes the uploaded audio file, so under normal operation neither the audio nor the transcript text is retained by Soniox. (Deletion is best-effort: a failure is logged and does not fail the run. For a single-file tamlil-transcribe run, --keep-remote skips it.)
• Data residency. Because the pipeline calls the default api.soniox.com, audio and transcripts are processed and stored in the United States, unless a regional Soniox project (EU or Japan) was explicitly requested and configured.
• Legal basis. Usage is governed by Soniox's self-serve, click-through Terms of Service plus Privacy Policy. A data-processing agreement and a HIPAA BAA are available through the Soniox Console but are not automatic — unless one has been accepted for the account, neither is in force.
• Calendar scope. Roster lookup is read-only and optional. It requests the single scope https://www.googleapis.com/auth/calendar.events.readonly and reads only meeting titles and attendee names. The per-user refresh token lives in your macOS Keychain (tamlil-google); without it, meetings still record and transcribe, just without titles or attendee names.
• Local storage. Recordings, transcripts, and the learned lexicon stay on your Mac — recordings under ~/Recordings/Tamlil/<recording-id>/, the learned dictionary at the repo root. The Soniox API key lives in the Keychain (tamlil-soniox), never in a file. The connector opens the recording database read-only.
• Deletion. To delete a recording locally, remove its directory under ~/Recordings/Tamlil/. On Soniox, both the uploaded audio and the stored transcription are removed automatically after each run, so nothing needs to be deleted there by hand under normal operation.

To report a security issue, see SECURITY.md.

Recording consent

Tamlil records your microphone and the meeting app's system audio together, so every participant's voice is captured. Recording a conversation is regulated by wiretap and eavesdropping laws that turn on who agreed to be recorded, and those laws differ by jurisdiction.

• You are responsible for obtaining consent. Tamlil is a local tool that records on your behalf. The person running it — not the project's author and not the software — is responsible for obtaining whatever consent the law requires from everyone on the call, and for doing so before recording starts.
• All-party versus one-party. Jurisdictions differ on how many participants must consent. In one-party jurisdictions (much of the United States) your own consent is enough. In all-party jurisdictions — often called two-party — every participant must consent: California requires the consent of all parties to a confidential communication (Penal Code section 632), and the EU generally requires a lawful basis and the participants' consent under the GDPR and national law. A call that crosses borders can leave you bound by the strictest rule that applies to anyone on it.
• Not legal advice. The above is general information, not legal advice, and it is not exhaustive. Consent rules vary by country, state, and context and they change over time. Check the law in your own jurisdiction and in each participant's, and get your own legal advice, before you record.

For developers

Tamlil is two halves that share a recording database: a SwiftUI menu-bar app in Tamlil/ and a Python transcription pipeline in src/tamlil/ (run through uv). The commands below assume the checkout the installer creates at $HOME/Library/Application Support/Tamlil/repo; substitute your own path if you cloned elsewhere.

REPO="$HOME/Library/Application Support/Tamlil/repo"
cd "$REPO"

Run the pipeline by hand

uv run tamlil-pipeline ~/Recordings/Tamlil/<recording-id>

The mic track is labeled with your macOS first name; override with --me-name. Transcribe a single file with uv run tamlil-transcribe path/to/audio.wav. If a run fails, the audio is preserved under raw/ — fix t