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. ```bash 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](https://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](#google-calendar-setup-bring-your-own-oauth-client). <details> <summary>Prefer to install by hand?</summary> ```bash 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](docs/architecture.md). ## 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](https://soniox.com); 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](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. ```bash REPO="$HOME/Library/Application Support/Tamlil/repo" cd "$REPO" ``` ### Run the pipeline by hand ```bash 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 the cause (usually the Soniox key or balance) and re-run; `--skip-transcribe` reuses an existing merge and only redoes the cheap local stages. The pipeline, in order: look up the meeting roster and build recognition context; optionally denoise the mic track; transcribe both tracks concurrently; merge by timestamp with per-track speaker labels; suppress mic echo from the system track; apply learned lexicon rewrites; save clarification cards from low-confidence spans; and write `final/transcript.{json,md}`. ### Read meetings from an AI agent The connector (an MCP server) is read-only over the recording database and transcript files, exposing `list_meetings`, `get_meeting`, `get_transcript`, and `search_transcripts`. The installer registers it with Claude Code for you; to add it by hand: ```bash claude mcp add tamlil -- uv run --project "$REPO" tamlil-mcp ``` For Codex (`~/.codex/config.toml`), point it at an absolute path: ```toml [mcp_servers.tamlil] command = "uv" args = ["run", "--project", "/Users/<you>/Library/Application Support/Tamlil/repo", "tamlil-mcp"] ``` It honors `TAMLIL_DB_PATH` / `TAMLIL_RECORDINGS_ROOT` overrides and never writes — the database is opened read-only. ### Recording storage Each recording is a directory under `~/Recordings/Tamlil/<recording-id>/`: `raw/` holds the captured `mic.wav` and `system.wav`; `work/` holds pipeline intermediates (denoised audio, per-track transcripts, the merged draft, the echo report); `final/` holds `transcript.json` and `transcript.md`; `logs/` holds the pipeline log. `transcript.json` keeps segment text, speaker diarization, language IDs, word timings and confidence, low-confidence spans, and the echo report. ### Google Calendar setup (bring your own OAuth client) The calendar feature — meeting titles and attendee names, also fed to the recognizer as context — is **optional** and stays off until you register your own Google OAuth client and point Tamlil at it (Tamlil ships none of its own). It's a five-minute, one-time setup: see **[docs/google-calendar-setup.md](docs/google-calendar-setup.md)**. ### Source-first delivery Tamlil is built and installed from source, not shipped as a notarized binary. Two consequences are deliberate: - **Ad-hoc code signing.** `Tamlil/build.sh` signs the app with `codesign --sign -` (no Developer ID, no notarization). Because you build it yourself, macOS runs it without a Gatekeeper detour, and the microphone and system-audio permission grants — keyed to the bundle id — survive every rebuild as long as the signature stays consistent. - **Pull-and-rebuild updater.** **Check for updates** runs `scripts/update.sh`, which pulls the latest source into your checkout, rebuilds, reinstalls, and relaunches. There is no Sparkle feed or separate update channel to trust; the source you can read is the source that runs. Because the app runs from your checkout, its repo path is a first-run setting (**Settings → Pipeline → tamlil repo**); the installer sets it for you. ### Troubleshooting - **No permission prompts / silent recordings** — check Tamlil is enabled under System Settings → Privacy & Security → Microphone and System Audio Recording, then relaunch. Grants are keyed to the bundle id and need re-approval if it ever changes. - **`swift build` fails immediately** — install or update the Command Line Tools with `xcode-select --install`; the build needs CLT 16+ (Swift 6). `swift test` is not supported (the package defines no test target); use `make test-swift`, which runs the app's built-in self-check. - **Pipeline error on a meeting** — the audio is preserved under `raw/`; re-run `uv run tamlil-pipeline <dir>` after fixing the cause (usually the Soniox key or balance). - **Empty roster / no meeting titles** — run `uv run tamlil-auth` to connect your Google account; see the Google Calendar setup above. ### Contributing and stack See [CONTRIBUTING.md](CONTRIBUTING.md). The stack: `uv` (Python 3.12), Soniox `stt-async-v5`, `requests`, `numpy`, `static-ffmpeg`, SwiftUI, and SQLite. ## License Apache-2.0 — see [LICENSE](LICENSE). Bundled third-party components are credited in [NOTICE](NOTICE) and [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES). </content>