millet-record 0.4.0__tar.gz

millet_record-0.4.0/LICENSE

@@ -0,0 +1,12 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+This package (meetscribe-record) is licensed under the GPL-3.0-or-later,
+the same license as the parent meetscribe-offline package.
+
+For the full license text, see:
+https://www.gnu.org/licenses/gpl-3.0.txt

millet_record-0.4.0/NOTICE

@@ -0,0 +1,47 @@
+meetscribe-record — NOTICE
+
+The macOS sidecar `meet-record-mac` (in `mac/`) adapts code from the Recap
+project under its MIT license:
+
+    https://github.com/RecapAI/Recap
+    Copyright (c) 2025 Rawand Ahmed Shaswar
+
+Specifically, the Core Audio Process Tap + Aggregate Device setup in
+`mac/Sources/MeetRecordMac/ProcessTap.swift` is based on:
+
+    Recap/Audio/Capture/Tap/ProcessTap.swift
+
+and the structural shape of the recording pipeline draws on:
+
+    Recap/Audio/Capture/MicrophoneCapture+AudioEngine.swift
+    Recap/Audio/Processing/RecordingCoordinator.swift
+
+The original MIT license text accompanying that source is preserved here:
+
+----------------------------------------------------------------------
+MIT License
+
+Copyright (c) 2025 Rawand Ahmed Shaswar
+
+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.
+----------------------------------------------------------------------
+
+The adapted Swift source files in `mac/Sources/MeetRecordMac/` are
+distributed as part of meetscribe-record under GPL-3.0-or-later, which is
+compatible with incorporating MIT-licensed source.

millet_record-0.4.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: millet-record
+Version: 0.4.0
+Summary: Lightweight capture-only subset of millet (formerly meetscribe-record): record dual-channel meeting audio (mic + system) with no transcription/diarization/summarization deps.  Named after the Ottoman millet system.  Part of the vezir ecosystem.
+Author: pretyflaco
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/pretyflaco/millet-record
+Project-URL: Repository, https://github.com/pretyflaco/millet-record
+Project-URL: Issues, https://github.com/pretyflaco/millet-record/issues
+Keywords: meeting,recording,audio,ffmpeg,pipewire,pulseaudio,core-audio,scribe,thin-client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: click>=8.0
+Requires-Dist: numpy>=1.20
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# millet-record
+
+Lightweight capture-only subset of [millet](https://github.com/pretyflaco/millet)
+(formerly meetscribe-record).
+
+Records dual-channel meeting audio — your microphone on the left
+channel, system/remote audio on the right — into a single stereo WAV
+via PipeWire or PulseAudio + ffmpeg. Ships none of millet's
+transcription, diarization, summarization, or PDF dependencies;
+install footprint is ~30 MB instead of ~3 GB.
+
+Full release history in [`CHANGELOG.md`](CHANGELOG.md).  Named after
+the Ottoman *millet system*.  Part of the
+[vezir](https://github.com/pretyflaco/vezir) ecosystem.
+
+## When to use which
+
+| Need | Install |
+|---|---|
+| Just record audio (e.g., for [vezir](https://github.com/pretyflaco/vezir) thin clients, or local archival) | `pip install millet-record` |
+| Record + transcribe + diarize + summarize + PDF | `pip install millet-pipeline` (depends on millet-record) |
+
+## Install
+
+```bash
+pip install millet-record
+```
+
+System deps (apt example):
+
+```bash
+sudo apt install ffmpeg pulseaudio-utils
+```
+
+## CLI
+
+```bash
+millet check                   # verify prerequisites
+millet devices                 # list audio sources
+millet record                  # record dual-channel WAV; Ctrl+C to stop
+millet archive                 # compress past WAV recordings to OGG/Opus
+millet request-permissions     # macOS Sequoia 15+: trigger Microphone /
+                               # System Audio Recording TCC prompts
+                               # (Apple removed the manual '+' button in
+                               # System Settings, so apps must request)
+```
+
+`millet record` writes to `~/millet-recordings/meeting-YYYYMMDD-HHMMSS/...wav`
+unless `-o` is passed. See `millet record --help` for options.
+
+When `millet-pipeline` is also installed, additional subcommands
+(`transcribe`, `run`, `label`, `sync`, `gui`, ...) become available
+under the same `millet` command via Click entry-points.
+
+### Legacy `meet` command
+
+The pre-rename `meet` console script keeps working for two minor
+versions (until `millet-record 0.6.0`).  It prints a deprecation
+warning on each invocation and forwards to the `millet` group.  Set
+`MILLET_SUPPRESS_DEPRECATION=1` to silence the warning during
+transition.
+
+## Architecture
+
+`millet-record` exposes a stable package `millet_record` containing:
+
+- `millet_record.capture` — ffmpeg-backed dual-channel capture
+  (RecordingSession, watchdog, drain buffer)
+- `millet_record.audio` — stereo channel reading + ffmpeg-based audio
+  compression
+- `millet_record.utils` — formatting helpers (HH:MM:SS, file sizes)
+- `millet_record.languages` — language constants used by capture flow
+- `millet_record.cli` — `millet` console-script entry point
+
+The legacy `meet_record` package name is still importable via a
+`sys.modules` alias + a meta-path finder, so existing
+`from meet_record.X import …` keeps working unchanged.  Removed in
+`millet-record 0.6.0`.
+
+`millet-pipeline` depends on this package and re-uses these modules,
+plus its own heavy modules (transcribe, label, voiceprint, summarize,
+sync, pdf, gui).
+
+## macOS (Apple Silicon)
+
+`pip install millet-record` on macOS 14.4+ Apple Silicon ships a
+bundled `meet-record-mac` Swift sidecar that captures via Core Audio
+Process Tap + AVAudioEngine — no PulseAudio, no BlackHole, no extra
+install.  `millet record` uses it by default.
+
+> **Note:** the Swift binary itself is still named `meet-record-mac`
+> for now — renaming would require macOS code-signing bundle-path
+> changes that aren't worth doing as part of the package rename.
+> Tracked as a follow-up; doesn't affect end users.
+
+First run prompts for Microphone and System Audio Recording permissions
+via the standard macOS TCC dialogs; both are required for full dual-
+channel capture (mic on left, system on right). See
+[`mac/README.md`](mac/README.md) for the sidecar's CLI surface, level
+analysis recipes, and environment variables.
+
+On **macOS Sequoia 15+**, Apple removed the manual `+` button from
+System Settings → Privacy → Microphone, so users can no longer add
+permissions before running the app.  The `millet request-permissions`
+subcommand explicitly calls `AVCaptureDevice.requestAccess(for: .audio)`
+to trigger the TCC dialog.  `millet check` will tell you which
+permission is missing and suggest running `request-permissions`.
+
+Set `MEET_RECORD_MAC=0` to force the legacy ffmpeg+PulseAudio path
+(diagnostic kill switch only — that path will fail on a stock macOS
+install because there is no PulseAudio device).  Intel Macs and
+macOS < 14.4 are unsupported.
+
+## License
+
+GPL-3.0-or-later, same as parent millet.

millet_record-0.4.0/README.md

@@ -0,0 +1,116 @@
+# millet-record
+
+Lightweight capture-only subset of [millet](https://github.com/pretyflaco/millet)
+(formerly meetscribe-record).
+
+Records dual-channel meeting audio — your microphone on the left
+channel, system/remote audio on the right — into a single stereo WAV
+via PipeWire or PulseAudio + ffmpeg. Ships none of millet's
+transcription, diarization, summarization, or PDF dependencies;
+install footprint is ~30 MB instead of ~3 GB.
+
+Full release history in [`CHANGELOG.md`](CHANGELOG.md).  Named after
+the Ottoman *millet system*.  Part of the
+[vezir](https://github.com/pretyflaco/vezir) ecosystem.
+
+## When to use which
+
+| Need | Install |
+|---|---|
+| Just record audio (e.g., for [vezir](https://github.com/pretyflaco/vezir) thin clients, or local archival) | `pip install millet-record` |
+| Record + transcribe + diarize + summarize + PDF | `pip install millet-pipeline` (depends on millet-record) |
+
+## Install
+
+```bash
+pip install millet-record
+```
+
+System deps (apt example):
+
+```bash
+sudo apt install ffmpeg pulseaudio-utils
+```
+
+## CLI
+
+```bash
+millet check                   # verify prerequisites
+millet devices                 # list audio sources
+millet record                  # record dual-channel WAV; Ctrl+C to stop
+millet archive                 # compress past WAV recordings to OGG/Opus
+millet request-permissions     # macOS Sequoia 15+: trigger Microphone /
+                               # System Audio Recording TCC prompts
+                               # (Apple removed the manual '+' button in
+                               # System Settings, so apps must request)
+```
+
+`millet record` writes to `~/millet-recordings/meeting-YYYYMMDD-HHMMSS/...wav`
+unless `-o` is passed. See `millet record --help` for options.
+
+When `millet-pipeline` is also installed, additional subcommands
+(`transcribe`, `run`, `label`, `sync`, `gui`, ...) become available
+under the same `millet` command via Click entry-points.
+
+### Legacy `meet` command
+
+The pre-rename `meet` console script keeps working for two minor
+versions (until `millet-record 0.6.0`).  It prints a deprecation
+warning on each invocation and forwards to the `millet` group.  Set
+`MILLET_SUPPRESS_DEPRECATION=1` to silence the warning during
+transition.
+
+## Architecture
+
+`millet-record` exposes a stable package `millet_record` containing:
+
+- `millet_record.capture` — ffmpeg-backed dual-channel capture
+  (RecordingSession, watchdog, drain buffer)
+- `millet_record.audio` — stereo channel reading + ffmpeg-based audio
+  compression
+- `millet_record.utils` — formatting helpers (HH:MM:SS, file sizes)
+- `millet_record.languages` — language constants used by capture flow
+- `millet_record.cli` — `millet` console-script entry point
+
+The legacy `meet_record` package name is still importable via a
+`sys.modules` alias + a meta-path finder, so existing
+`from meet_record.X import …` keeps working unchanged.  Removed in
+`millet-record 0.6.0`.
+
+`millet-pipeline` depends on this package and re-uses these modules,
+plus its own heavy modules (transcribe, label, voiceprint, summarize,
+sync, pdf, gui).
+
+## macOS (Apple Silicon)
+
+`pip install millet-record` on macOS 14.4+ Apple Silicon ships a
+bundled `meet-record-mac` Swift sidecar that captures via Core Audio
+Process Tap + AVAudioEngine — no PulseAudio, no BlackHole, no extra
+install.  `millet record` uses it by default.
+
+> **Note:** the Swift binary itself is still named `meet-record-mac`
+> for now — renaming would require macOS code-signing bundle-path
+> changes that aren't worth doing as part of the package rename.
+> Tracked as a follow-up; doesn't affect end users.
+
+First run prompts for Microphone and System Audio Recording permissions
+via the standard macOS TCC dialogs; both are required for full dual-
+channel capture (mic on left, system on right). See
+[`mac/README.md`](mac/README.md) for the sidecar's CLI surface, level
+analysis recipes, and environment variables.
+
+On **macOS Sequoia 15+**, Apple removed the manual `+` button from
+System Settings → Privacy → Microphone, so users can no longer add
+permissions before running the app.  The `millet request-permissions`
+subcommand explicitly calls `AVCaptureDevice.requestAccess(for: .audio)`
+to trigger the TCC dialog.  `millet check` will tell you which
+permission is missing and suggest running `request-permissions`.
+
+Set `MEET_RECORD_MAC=0` to force the legacy ffmpeg+PulseAudio path
+(diagnostic kill switch only — that path will fail on a stock macOS
+install because there is no PulseAudio device).  Intel Macs and
+macOS < 14.4 are unsupported.
+
+## License
+
+GPL-3.0-or-later, same as parent millet.

millet_record-0.4.0/millet_record/__init__.py

@@ -0,0 +1,76 @@
+"""millet-record — lightweight capture-only subset of millet (formerly meetscribe-record).
+
+Public modules:
+    millet_record.capture    — RecordingSession, dual-channel capture
+                             (Linux: ffmpeg+PulseAudio; macOS 14.4+
+                             arm64: meet-record-mac sidecar)
+    millet_record.audio      — stereo channel reading + ffmpeg compression
+    millet_record.utils      — formatting helpers
+    millet_record.languages  — language constants
+    millet_record.cli        — `millet` console-script entry point
+                             (with deprecation-aliased `meet` for two
+                              minor versions)
+
+Named after the Ottoman millet system.  Part of the vezir ecosystem.
+
+Version is the single source of truth here; pyproject.toml's
+[project] section pulls it dynamically via setuptools.dynamic.
+"""
+
+__version__ = "0.4.0"
+
+# ── Backward-compat: meet_record alias ──────────────────────────────────────
+# Existing code (e.g. older meetscribe-offline 0.8.3 compatibility shims,
+# third-party scripts) imports ``from meet_record.X import …``.  We register
+# this package as both ``millet_record`` (canonical) and ``meet_record``
+# (legacy) in sys.modules so both import paths resolve to the same package.
+# Submodules are also aliased lazily via a MetaPathFinder so we don't pay
+# the import cost up-front (capture pulls ffmpeg detection on Linux).
+#
+# Removed in millet-record 0.6.0 (matches the `meet` console-script
+# deprecation timeline).
+import sys as _sys
+import importlib as _importlib
+import importlib.abc as _abc
+import importlib.machinery as _machinery
+
+
+class _MeetRecordAliasFinder(_abc.MetaPathFinder):
+    """Resolve ``meet_record`` and ``meet_record.X`` to ``millet_record[.X]``."""
+
+    def find_spec(self, fullname, path, target=None):
+        if fullname == "meet_record":
+            return _machinery.ModuleSpec(
+                fullname,
+                loader=_MeetRecordAliasLoader(),
+                is_package=True,
+            )
+        if fullname.startswith("meet_record."):
+            new_name = "millet_record." + fullname[len("meet_record."):]
+            try:
+                mod = _importlib.import_module(new_name)
+            except ImportError:
+                return None
+            _sys.modules[fullname] = mod
+            return _machinery.ModuleSpec(
+                fullname,
+                loader=_MeetRecordAliasLoader(),
+                is_package=hasattr(mod, "__path__"),
+            )
+        return None
+
+
+class _MeetRecordAliasLoader(_abc.Loader):
+    def create_module(self, spec):
+        if spec.name == "meet_record":
+            return _sys.modules[__name__]
+        new_name = "millet_record." + spec.name[len("meet_record."):]
+        return _sys.modules.get(new_name) or _importlib.import_module(new_name)
+
+    def exec_module(self, module):  # noqa: D401 - aliased; nothing to exec
+        return None
+
+
+_sys.modules.setdefault("meet_record", _sys.modules[__name__])
+if not any(isinstance(f, _MeetRecordAliasFinder) for f in _sys.meta_path):
+    _sys.meta_path.append(_MeetRecordAliasFinder())

millet_record-0.4.0/millet_record/_bin/.gitignore

@@ -0,0 +1,11 @@
+# Ignore everything in this directory except this file.
+#
+# meet_record/_bin/ holds the macOS arm64 meet-record-mac binary in
+# the macOS wheel. The binary itself is built by mac.yml in CI and
+# copied here at wheel-build time by release.yml; it's never
+# committed. This .gitignore both keeps the directory present in the
+# tree (so setuptools.package-data can reference _bin/* during build)
+# and prevents accidental commits of a locally-built artefact.
+
+*
+!.gitignore

millet_record-0.4.0/millet_record/audio.py

@@ -0,0 +1,252 @@
+"""Audio utilities for meetscribe.
+
+Low-level helpers for reading stereo audio files, computing per-speaker
+channel energy, and compressing recordings.
+
+Extracted from label.py and transcribe.py to eliminate duplication.
+All I/O uses ffmpeg/ffprobe (via subprocess) so that any audio format
+supported by ffmpeg (WAV, OGG/Opus, FLAC, …) can be read transparently.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import NamedTuple
+
+import numpy as np
+
+log = logging.getLogger(__name__)
+
+
+class StereoChannels(NamedTuple):
+    """Parsed stereo audio data returned by :func:`read_stereo_channels`."""
+
+    mic: np.ndarray    # Left channel (your microphone), float32
+    system: np.ndarray # Right channel (system/remote audio), float32
+    sample_rate: int   # Frames per second
+    sampwidth: int     # Bytes per sample (always 2 — decoded to int16)
+
+
+def read_stereo_channels(audio_path: Path) -> StereoChannels | None:
+    """Read a stereo audio file and return separate mic and system channels.
+
+    Uses ffmpeg to decode to raw PCM, so any format ffmpeg supports
+    (WAV, OGG/Opus, FLAC, …) works transparently.
+
+    Returns None (instead of raising) if the file is mono, cannot be
+    opened, or decoding fails.  Callers should fall back to a safe
+    default in that case.
+
+    The returned arrays are float32 copies — safe to modify.
+    """
+    # Probe channel count first.
+    probe_cmd = [
+        "ffprobe", "-v", "quiet",
+        "-show_entries", "stream=channels,sample_rate",
+        "-of", "json",
+        str(audio_path),
+    ]
+    try:
+        probe = subprocess.run(probe_cmd, capture_output=True, text=True)
+        if probe.returncode != 0:
+            return None
+        info = json.loads(probe.stdout)
+        stream = info.get("streams", [{}])[0]
+        n_channels = int(stream.get("channels", 0))
+        sample_rate = int(stream.get("sample_rate", 0))
+    except Exception:
+        return None
+
+    if n_channels != 2 or sample_rate == 0:
+        return None
+
+    # Decode full file to raw s16le PCM via ffmpeg.
+    decode_cmd = [
+        "ffmpeg", "-v", "quiet",
+        "-i", str(audio_path),
+        "-f", "s16le",
+        "-acodec", "pcm_s16le",
+        "-ar", str(sample_rate),
+        "-ac", "2",
+        "-",   # write to stdout
+    ]
+    try:
+        result = subprocess.run(decode_cmd, capture_output=True)
+        if result.returncode != 0:
+            return None
+        raw = result.stdout
+    except Exception:
+        return None
+
+    if len(raw) == 0:
+        return None
+
+    samples = np.frombuffer(raw, dtype=np.int16)
+    if len(samples) % 2 != 0:
+        samples = samples[:-1]
+    samples = samples.reshape(-1, 2).astype(np.float32)
+
+    return StereoChannels(
+        mic=samples[:, 0],
+        system=samples[:, 1],
+        sample_rate=sample_rate,
+        sampwidth=2,
+    )
+
+
+# ─── Audio compression ─────────────────────────────────────────────────────
+
+def _get_audio_duration(path: Path) -> float | None:
+    """Return duration in seconds via ffprobe, or None on failure."""
+    cmd = [
+        "ffprobe", "-v", "quiet",
+        "-show_entries", "format=duration",
+        "-of", "csv=p=0",
+        str(path),
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode == 0 and result.stdout.strip():
+            return float(result.stdout.strip())
+    except Exception:
+        pass
+    return None
+
+
+def compress_audio(
+    wav_path: Path,
+    *,
+    keep_wav: bool = False,
+    bitrate: str = "48k",
+) -> Path:
+    """Compress a WAV file to OGG/Opus and optionally delete the original.
+
+    Args:
+        wav_path: Path to the stereo WAV recording.
+        keep_wav: If True, keep the WAV file after compression.
+        bitrate: Opus bitrate (default 48k — transparent for speech).
+
+    Returns:
+        Path to the compressed .ogg file.
+
+    Raises:
+        RuntimeError: If ffmpeg fails or duration validation fails.
+        FileNotFoundError: If the WAV file does not exist.
+    """
+    wav_path = Path(wav_path)
+    if not wav_path.exists():
+        raise FileNotFoundError(f"Audio file not found: {wav_path}")
+
+    ogg_path = wav_path.with_suffix(".ogg")
+
+    cmd = [
+        "ffmpeg", "-y", "-v", "quiet",
+        "-i", str(wav_path),
+        "-c:a", "libopus",
+        "-b:a", bitrate,
+        "-vn",
+        str(ogg_path),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        # Clean up partial output.
+        ogg_path.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"Audio compression failed (ffmpeg exit {result.returncode}): "
+            f"{result.stderr.strip()}"
+        )
+
+    # Validate: durations must match within 1 second.
+    wav_dur = _get_audio_duration(wav_path)
+    ogg_dur = _get_audio_duration(ogg_path)
+    if wav_dur is not None and ogg_dur is not None:
+        if abs(wav_dur - ogg_dur) > 1.0:
+            ogg_path.unlink(missing_ok=True)
+            raise RuntimeError(
+                f"Duration mismatch after compression: WAV={wav_dur:.1f}s "
+                f"vs OGG={ogg_dur:.1f}s (diff > 1s)"
+            )
+
+    # Gather sizes for logging before potentially deleting the WAV.
+    wav_size = wav_path.stat().st_size
+    ogg_size = ogg_path.stat().st_size
+    ratio = wav_size / ogg_size if ogg_size > 0 else 0
+
+    if not keep_wav:
+        wav_path.unlink()
+        log.info("Deleted %s after compression", wav_path.name)
+
+    log.info(
+        "Compressed %s -> %s (%.1f MB -> %.1f MB, %.0fx)",
+        wav_path.name, ogg_path.name,
+        wav_size / 1_048_576, ogg_size / 1_048_576, ratio,
+    )
+
+    return ogg_path
+
+
+def compute_speaker_channel_energy(
+    mic_ch: np.ndarray,
+    sys_ch: np.ndarray,
+    segments: list,          # list[Segment] — avoid circular import
+    sample_rate: int,
+) -> dict[str, float]:
+    """Compute the mic-channel energy ratio for each speaker.
+
+    For each speaker, accumulates RMS energy on the mic channel and on
+    the system channel across all their segments, then returns a dict
+    mapping ``speaker_id -> mic_ratio`` where::
+
+        mic_ratio = avg_mic_rms / (avg_mic_rms + avg_sys_rms)
+
+    A ratio > 0.5 means the speaker is dominant on the mic (i.e. YOU).
+    Speakers with no audio frames get a ratio of 0.5 (unknown).
+
+    Args:
+        mic_ch:      Float32 array of left-channel (mic) samples.
+        sys_ch:      Float32 array of right-channel (system) samples.
+        segments:    List of Segment objects with .start, .end, .speaker.
+        sample_rate: Frames per second (used to convert timestamps to indices).
+
+    Returns:
+        Dict mapping speaker ID to mic-ratio float in [0.0, 1.0].
+    """
+    n = len(mic_ch)
+    mic_energy: dict[str, float] = {}
+    sys_energy: dict[str, float] = {}
+    total_frames: dict[str, int] = {}
+
+    for seg in segments:
+        if not seg.speaker:
+            continue
+        start = max(0, min(int(seg.start * sample_rate), n))
+        end = max(0, min(int(seg.end * sample_rate), n))
+        if end <= start:
+            continue
+
+        mic_slice = mic_ch[start:end]
+        sys_slice = sys_ch[start:end]
+        count = end - start
+
+        mic_rms = float(np.sqrt(np.mean(mic_slice ** 2)))
+        sys_rms = float(np.sqrt(np.mean(sys_slice ** 2)))
+
+        spk = seg.speaker
+        mic_energy[spk] = mic_energy.get(spk, 0.0) + mic_rms * count
+        sys_energy[spk] = sys_energy.get(spk, 0.0) + sys_rms * count
+        total_frames[spk] = total_frames.get(spk, 0) + count
+
+    mic_ratio: dict[str, float] = {}
+    for spk, frames in total_frames.items():
+        if frames == 0:
+            mic_ratio[spk] = 0.5
+            continue
+        avg_mic = mic_energy.get(spk, 0.0) / frames
+        avg_sys = sys_energy.get(spk, 0.0) / frames
+        denom = avg_mic + avg_sys
+        mic_ratio[spk] = avg_mic / denom if denom > 0 else 0.5
+
+    return mic_ratio