call-copilot 0.2.0__py3-none-any.whl

call_copilot-0.2.0.dist-info/METADATA

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: call-copilot
+Version: 0.2.0
+Summary: Call Copilot — silently record meeting audio in the background, then transcribe locally to clean markdown.
+Author-email: Anisur Rahman <pshakilwizard@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Anisur Rahman
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/AnisurRahmann/call-copilot
+Project-URL: Repository, https://github.com/AnisurRahmann/call-copilot
+Project-URL: Issues, https://github.com/AnisurRahmann/call-copilot/issues
+Project-URL: Changelog, https://github.com/AnisurRahmann/call-copilot/releases
+Keywords: audio,transcription,whisper,meeting,recorder,macos,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: audiotap>=0.0.2
+Requires-Dist: soundfile>=0.12
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Call Copilot
+
+> One thing. Done really well. Record meetings. Save transcripts. Don't break audio.
+
+Call Copilot is a terminal command (`rec`) that records your meeting audio and, when you
+stop it, transcribes locally and saves a clean markdown transcript. **Everything runs on
+your machine** — no cloud, no API keys, no account. Audio and transcripts never leave the
+computer.
+
+![Call Copilot demo](docs/demo.gif)
+
+```
+$ rec setup         # one-time: verify macOS + grant capture permission
+$ rec start         # starts recording, you keep working
+$ rec stop          # stops, transcribes, saves markdown
+$ rec list          # shows past recordings
+```
+
+## How it captures audio (no BlackHole, no Multi-Output Device)
+
+By default, `rec` captures **both the microphone (your voice) AND system audio (other
+participants / anything apps play)** — so a real meeting where *you* speak gets recorded,
+not just the audio coming out of your speakers. Both sources are tapped directly via
+Apple's Core Audio taps API (macOS 14.2+) using the [`audiotap`](https://pypi.org/project/audiotap/)
+library. There is:
+
+- **no virtual audio driver** to install (no BlackHole),
+- **no Multi-Output Device** to create in Audio MIDI Setup,
+- **no system output device** to switch and restore,
+- and therefore **no silent-recording failure** that the old driver-based approaches
+  produce when routing breaks.
+
+The mic and system streams are recorded as **two separate WAVs** (each at its own true
+rate), transcribed separately, and merged into one transcript with `[Mic]` / `[System]`
+labels so you can tell who said what. Want just one source? `rec start --mic-only` or
+`--system-only`.
+
+### Grant capture permission (one-time, per terminal app)
+
+macOS ties capture permission to the app you run `rec` from (Terminal, iTerm, **Warp**,
+VS Code, …). You need **two** grants:
+
+1. **Microphone** (your voice): System Settings → Privacy & Security → **Microphone** →
+   enable your terminal app.
+2. **System audio** (grouped under Screen Recording on macOS 14.2+): System Settings →
+   Privacy & Security → **Screen Recording** → enable your terminal app, then **quit and
+   reopen it** (required for the change to take effect).
+
+Until mic is granted, `rec start` records system audio only and skips the mic (it tells
+you so). `rec setup` checks the current mic-permission status.
+
+After `rec stop` (or Ctrl+C from `rec start`), the recording(s) are transcribed locally
+with [faster-whisper](https://github.com/SYSTRAN/faster-whisper) (CPU, int8 — no API, no
+data leaves your machine) and written to a markdown transcript.
+
+```
+recording.wav ──> faster-whisper (local, free) ──> transcript.md
+```
+
+## Requirements
+
+- **macOS 14.2 or later** (Sonoma — the Core Audio process taps API `rec` records through
+  landed in 14.2). Apple Silicon recommended. Intel works.
+- **Python 3.11+** only needed for the `pipx` install; the Homebrew formula brings its own.
+
+No virtual audio driver (no BlackHole), no Multi-Output Device, no manual Audio MIDI Setup.
+The tap reads system output directly. `rec` checks the macOS version itself and refuses to
+run below 14.2 with a one-line message — you don't have to guess.
+
+## Install
+
+**Homebrew** (recommended — no Python to manage):
+
+```bash
+brew install AnisurRahmann/tap/call-copilot
+```
+
+**pipx** (if you prefer a plain Python install, no Homebrew):
+
+```bash
+pipx install call-copilot
+```
+
+Either way you get a `rec` command on your `PATH`. Then jump to
+[One-time setup](#one-time-setup).
+
+> Using `rec` on a machine below macOS 14.2 prints `Error: rec requires macOS 14.2 or
+> later ...` and exits — no traceback, no mystery. See
+> [docs/HOMEBREW.md](docs/HOMEBREW.md) if you're setting up the tap yourself.
+
+## Recording consent & privacy
+
+Call Copilot records audio from your meetings, which may include **other participants**.
+Recording laws vary by jurisdiction and many require the consent of everyone being
+recorded (one-party vs. all-party consent). **Obtaining that consent is your
+responsibility** — check your local laws and your organization's policy before recording.
+
+On the technical side, your data stays put:
+
+- Transcription runs **100% locally** with faster-whisper (CPU, int8) — no API, no cloud.
+- **Audio and transcripts never leave your machine.** The only network access is the
+  first run of a given Whisper model, which downloads its weights from Hugging Face;
+  after that it's fully offline.
+- Recordings live under `~/.local/share/rec/sessions/` (XDG data home), outside any repo.
+
+## One-time setup
+
+```bash
+rec setup
+```
+
+Verifies your macOS version, that the `audiotap` library + its bundled dylib load, saves
+your config, and tells you about the one-time capture permission prompt.
+
+## Recording a meeting
+
+```bash
+rec start                          # mic + system (default); Ctrl+C to stop & transcribe
+rec start --system-only            # just what apps play (not your voice)
+rec start --mic-only               # just your voice (not system audio)
+rec list                           # browse past sessions
+rec transcribe 2026-07-27_14-30-00 --model medium    # re-transcribe at higher quality
+rec diagnose 2026-07-27_14-30-00                      # bundle debug info for an AI agent
+```
+
+By default `rec start` records **both** your microphone and system audio; the transcript
+labels each line `[Mic]` or `[System]`. Use `--system-only` / `--mic-only` to narrow.
+
+**`rec start`** shows a live indicator while recording:
+
+```
+● REC  2026-07-28_14-30-00
+elapsed 03:47   size 18.2 MB
+press Ctrl+C to stop & transcribe
+```
+
+Press **Ctrl+C** when your meeting ends — it stops the recording and transcribes in the
+same command, then prints the transcript path. One command, start to finish.
+
+Want the old background behavior instead? `rec start --detach` spawns the recorder and
+exits immediately; stop it later from another terminal with `rec stop` (or check progress
+with `rec status`).
+
+> **Tip:** if a transcript comes back empty, the recording was silent — nothing was
+> playing, or the capture permission was revoked. `rec start` (and `rec stop`) warn you
+> about this immediately, and `rec diagnose <session>` bundles the audio levels + logs.
+
+## Configuration
+
+Stored at `~/.config/rec/config.json` (XDG). Recordings live under
+`~/.local/share/rec/sessions/{id}/`. Override the XDG roots with `XDG_CONFIG_HOME` /
+`XDG_DATA_HOME` if needed.
+
+```json
+{
+  "sample_rate": 16000,
+  "channels": 1,
+  "whisper_model": "base",
+  "capture": "system",
+  "sessions_dir": "~/.local/share/rec/sessions"
+}
+```
+
+16 kHz mono float32 is Whisper's native input format — no resampling, smallest files
+(~7.5 MB/min), best transcription accuracy.
+
+### A note on sample rate (why your recordings play at the right speed)
+
+`audiotap`'s `sample_rate` parameter is **not honored** — the tap always delivers
+audio at your output device's native rate (typically 48 kHz), regardless of what
+we request. `rec` handles this transparently: the recorder **measures the true
+capture rate** when the tap starts and writes the WAV at that rate (so playback
+is the correct speed), and the transcriber **resamples to 16 kHz** before
+feeding Whisper (so transcription is accurate). You don't need to do anything;
+this section exists to explain the `capture_sample_rate` field in `session.json`
+(which may differ from the `sample_rate` in your config).
+
+### A note on VAD (voice activity detection)
+
+Transcription runs **without** faster-whisper's Silero VAD pre-filter by default.
+The VAD is tuned for close-mic speech and aggressively rejects system-audio
+capture (speakers/headphones via a tap, which has a different character) — we've
+seen it discard 100% of a clearly-audible recording and return an empty
+transcript. Whisper's own `no_speech_threshold` handles silence adequately
+without that risk.
+
+If you have clean close-mic input and want long silences skipped (faster,
+cleaner output), enable it per run:
+
+```bash
+rec stop --vad              # VAD on for this transcription
+rec transcribe <id> --vad   # re-transcribe with VAD
+```
+
+## Stack
+
+| Tool | Role |
+|------|------|
+| [`audiotap`](https://github.com/graphaelli/audiotap) | Core Audio taps → captures system audio directly (macOS 14.2+) |
+| [`soundfile`](https://github.com/bastibe/python-soundfile) | Streams WAV chunks to disk (constant memory) |
+| [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) | Local speech-to-text (CPU int8) |
+| [`rich`](https://github.com/Textualize/rich) + [`click`](https://click.palletsprojects.com/) | Terminal UI + CLI |
+
+Everything is free and open-source. Transcription runs 100% locally — no API cost, no
+data leaves the machine. (The first run of a given whisper model downloads its weights
+from Hugging Face; after that it's offline.)
+
+## Logging & debugging
+
+Every activity — the audio tap lifecycle, chunk writes, transcription, formatting, each
+CLI decision — is logged. Logs flow to three destinations:
+
+| Destination | Path | Level | What it's for |
+|---|---|---|---|
+| **Console (stderr)** | your terminal | WARNING* | User-facing; clean by default |
+| **Global log** | `~/.local/share/rec/logs/rec.log` | DEBUG | Monitor surface — `tail -f` it |
+| **Session log** | `~/.local/share/rec/sessions/<id>/recorder.log` | DEBUG | Per-session post-mortem |
+
+\* WARNING by default: `-v` → INFO, `-vv` → DEBUG, `--quiet` → CRITICAL, `REC_LOG_LEVEL=DEBUG`.
+
+Every command failure is logged at `ERROR` with the reason + exit code; unexpected
+crashes include the full traceback.
+
+### Hand a session to an AI agent to debug
+
+```bash
+rec list                                 # find the session id
+rec diagnose 2026-07-27_14-30-00        # → writes sessions/<id>/diagnose.md
+rec diagnose 2026-07-27_14-30-00 --stdout | <your-ai-tool>   # pipe straight to an agent
+```
+
+The bundle contains the session metadata, the daemon's `recorder.log`, the global-log
+lines tagged with that session, the transcript if it exists, and the config — followed
+by a debugging checklist. (`rec diagnose` accepts a unique prefix too, e.g. `2026-07-27`.)
+
+> **Note on the recording loop:** the audio callback runs on Core Audio's real-time
+> thread and deliberately logs nothing — it copies each chunk to a queue and a writer
+> thread does the disk I/O. The daemon logs only at tap start/stop and on signals.
+
+## Development
+
+You only need this if you're hacking on `rec` itself. End users should use the
+[Install](#install) commands above.
+
+```bash
+git clone https://github.com/AnisurRahmann/call-copilot.git && cd call-copilot
+make install          # creates .venv and installs `rec` in editable mode + dev deps
+make test             # unit tests (offline — no audio device or model download needed)
+make run              # rec start, using the dev venv's rec
+```
+
+`make install` requires Python 3.11+ on your `PATH` (it pins `python3.11` for the
+venv). For everything else — releasing, the Homebrew tap, code style — see
+[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/HOMEBREW.md](docs/HOMEBREW.md).
+
+## Contributing
+
+Issues and pull requests are welcome at
+[github.com/AnisurRahmann/call-copilot](https://github.com/AnisurRahmann/call-copilot).
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR, and report security
+issues privately per [SECURITY.md](SECURITY.md).
+
+## What this is NOT
+
+- Not a real-time transcription tool (transcription happens after you stop).
+- Not a meeting summarizer (just the transcript).
+- Not a Zoom/Meet plugin (it captures system audio generically).
+- Not cross-platform (macOS 14.2+ only).
+
+## License
+
+MIT — see [LICENSE](LICENSE). © Anisur Rahman.

call_copilot-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+call_copilot-0.2.0.dist-info/licenses/LICENSE,sha256=GAQRXFSYf-N4Xte18w24Mm3rfj3IHt6SxG4201fCX6s,1070
+rec/__init__.py,sha256=lP3lBk7eIk7Dkc74Yl4P8wfHAj_PLAi3sEVqL3cXkwM,312
+rec/audio_check.py,sha256=Q5DwJT94_Rffjy1zz29Prx8aGqNTWjq2IWpAiQWdJJY,4905
+rec/cli.py,sha256=u-Xi5yJR0Gq_QDAL5QGbDMYi0exP12Nr6Uu7AY_04ak,36277
+rec/config.py,sha256=yuwEYmya3qYIgt8ynaNDWX0UokmRk4xnxoxwMoTN_jU,4834
+rec/envcheck.py,sha256=ZWEEgGqePfYTIJNZajjw1dmK9i1DSDyXK83nMK9e8Cs,3694
+rec/formatter.py,sha256=VYnKIqpAeq4XHIDgNpOASbzq_m7PGuKYDZpjsvXji0U,3719
+rec/log.py,sha256=YddB8rWgtmEAEqnyWUDS4nE29K8GuIDrhhEUM0wLWpA,8942
+rec/recorder.py,sha256=byz-5FpuKNllF6RrC30p78b3mPF3e4D2L3888E9hoIg,26922
+rec/session.py,sha256=8bGu6LdsjbsoTlI-DjfQ2PL_xYAz1LBPjaZoTwrHiPM,5715
+rec/transcriber.py,sha256=eh5SCrOM9ahvdIjE_XXGI3BKY0SBtjFbB1tnw6HIGq8,6809
+call_copilot-0.2.0.dist-info/METADATA,sha256=7weV4mq-zBN5jdHZVMAEfbrwNERMnZCZtwTm513YOhE,14540
+call_copilot-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+call_copilot-0.2.0.dist-info/entry_points.txt,sha256=DZ2FBOrZFejlVOEjlA6kNZOj-VNt4jC5h1ETW-l_qUk,37
+call_copilot-0.2.0.dist-info/top_level.txt,sha256=aAhpQ5vNKbO1qVtzOviIHI79AYUz7beFknFX6PYLHUQ,4
+call_copilot-0.2.0.dist-info/RECORD,,

call_copilot-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

call_copilot-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rec = rec.cli:main

call_copilot-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anisur Rahman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

call_copilot-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rec

rec/__init__.py

@@ -0,0 +1,8 @@
+"""Call Copilot — a terminal meeting recorder (command: `rec`).
+
+Records system audio in the background via macOS Core Audio taps (the
+`audiotap` library — zero degradation of what you hear, no virtual audio
+driver) and transcribes locally with faster-whisper into clean markdown.
+"""
+
+__version__ = "0.1.0"

rec/audio_check.py

@@ -0,0 +1,114 @@
+"""Audio level analysis — detect silent / near-silent recordings.
+
+A silent recording is the #1 failure mode for system-audio capture: the tap
+is running but no app is playing audio (or the permission was revoked mid-
+stream), the recorder faithfully writes a file of zeros, and Whisper's VAD
+strips everything → an empty transcript.
+
+Catching this immediately after `rec stop` (before Whisper runs) saves the
+user a full transcription cycle and points them at the real problem. Analysis
+streams the file in chunks so it's constant-memory for multi-hour recordings.
+
+The recorder writes 32-bit float WAV (audiotap delivers float32 PCM), so we
+read as float64 for headroom in the sum-of-squares and compare peak against a
+normalized threshold (float samples are in the range -1.0..1.0).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .log import get_logger
+
+log = get_logger(__name__)
+
+# A recording is "silent" if peak amplitude is below this. float samples are
+# in [-1.0, 1.0]; real speech peaks well above 0.01 even when quiet. Below
+# ~0.001 is effectively the digital noise floor.
+SILENCE_PEAK_THRESHOLD = 0.001
+
+# Chunk size for streaming analysis (frames). 1M frames ≈ 62s at 16kHz.
+_ANALYSIS_CHUNK = 1_000_000
+
+
+@dataclass
+class AudioLevels:
+    """Streaming amplitude statistics over a WAV file."""
+
+    peak: float = 0.0          # max absolute sample value (0.0..1.0 for float)
+    rms: float = 0.0           # root-mean-square (overall loudness)
+    frames: int = 0            # total frames analyzed
+    sample_rate: int = 0
+    silent: bool = False       # peak below SILENCE_PEAK_THRESHOLD
+
+    @property
+    def duration_seconds(self) -> float:
+        return self.frames / self.sample_rate if self.sample_rate else 0.0
+
+
+def analyze_wav(wav_path: str | Path) -> AudioLevels | None:
+    """Stream a WAV and compute peak + rms. Returns None if unreadable/empty.
+
+    Reads as float64 (soundfile normalizes PCM/float to double for us). The
+    recorder writes float32, so values land in [-1.0, 1.0]. Streams in chunks
+    for constant memory on long recordings.
+    """
+    import numpy as np
+    import soundfile as sf
+
+    path = Path(wav_path)
+    if not path.exists():
+        log.warning("audio check: wav not found %s", path)
+        return None
+
+    try:
+        with sf.SoundFile(str(path), mode="r") as f:
+            sr = f.samplerate
+            peak = 0.0
+            sum_sq = 0.0
+            total = 0
+            for block in f.blocks(blocksize=_ANALYSIS_CHUNK, dtype="float64"):
+                arr = block.reshape(-1) if block.ndim > 1 else block
+                abs_arr = np.abs(arr)
+                peak = max(peak, float(abs_arr.max(initial=0.0)))
+                sum_sq += float((abs_arr ** 2).sum())
+                total += arr.size
+    except Exception as e:  # pragma: no cover — defensive
+        log.warning("audio check: could not read %s (%r)", path, e)
+        return None
+
+    rms = (sum_sq / total) ** 0.5 if total else 0.0
+    silent = peak < SILENCE_PEAK_THRESHOLD
+    levels = AudioLevels(peak=peak, rms=rms, frames=total, sample_rate=sr, silent=silent)
+
+    if silent:
+        # Distinguish the two causes of silence. A tap that ran (frames > 0)
+        # but produced *literal* zeros (peak exactly 0.0) almost always means
+        # macOS is not honoring the capture permission for the running app:
+        # the tap is invoked with real frame counts but every sample is 0.
+        # A genuinely quiet-but-live source usually leaves some dither noise
+        # (peak > 0 but < threshold). Tailor the guidance accordingly.
+        if total > 0 and peak == 0.0:
+            log.error(
+                "RECORDING IS SILENT: peak=%.6f rms=%.6f over %.1fs (%d frames). "
+                "The tap ran but captured literally zero samples — this is the "
+                "macOS capture-permission signature, not a quiet source. Toggle "
+                "Screen Recording ON for your terminal app in System Settings > "
+                "Privacy & Security, then FULLY QUIT and reopen the app (a running "
+                "process keeps getting zero buffers until restarted). Re-check with "
+                "`rec setup`.",
+                peak, rms, levels.duration_seconds, total,
+            )
+        else:
+            log.error(
+                "RECORDING IS SILENT: peak=%.6f rms=%.6f over %.1fs — "
+                "the audio tap captured no usable signal. Either nothing was "
+                "playing, or macOS revoked the system-audio capture permission. "
+                "Run `rec setup` to re-check permissions, then record again while "
+                "audio is actually playing.",
+                peak, rms, levels.duration_seconds,
+            )
+    else:
+        log.info("audio levels OK: peak=%.4f rms=%.4f over %.1fs", peak, rms, levels.duration_seconds)
+    return levels