🔁 LoopRec

Local-first dual-input meeting recorder for macOS
Capture your mic + system/meeting audio via BlackHole — no cloud, fully private.

Quick Start · Setup Guide · Limitations · Contribute

---

Why LoopRec?

Apple's built-in recording tools handle simple voice capture well, but fall short for a common workflow: recording a Zoom/Meet/Teams call where you need both your microphone and the meeting audio, entirely locally.

LoopRec fills that gap:

• 🎙️ Dual-path capture — records your microphone and system/meeting audio as separate streams via BlackHole
• 🔒 Privacy-first — everything stays on your Mac. No cloud upload, no telemetry, no accounts
• 📦 Single-file export — produces a time-aligned, uniquely named .m4a ready for transcription
• 🤖 AI-ready pipeline — output feeds directly into local tools like mlx_whisper and Ollama

LoopRec → .m4a → mlx_whisper (transcribe) → Ollama (summarize)
               ↑ all local, all private

Features

Feature	Description
Setup Wizard	Guided checks for BlackHole, microphone permission, sample rate, and loopback signal
Device Selection	Pick your microphone and loopback device from detected audio inputs
Live Signal Meters	Real-time RMS levels for both mic and system audio — verify signal before recording
One-click Recording	Arm → Start → Stop. Exports a merged, time-aligned .m4a automatically
Whisper Command	After each recording, shows a ready-to-paste mlx_whisper command for instant transcription
Aggregate Device Warning	Warns you if your mic selection is likely to cause echo/double-capture

Quick Start

Requirements

macOS	14.0 (Sonoma) or later
BlackHole 2ch	Install from existential.audio
Xcode / Swift 6.2+	Required for building from source

Build & Run

git clone https://github.com/pouuh/LoopRec.git
cd LoopRec
swift build
swift run

Build a Double-Clickable App

./scripts/build_app_bundle.sh

This produces dist/LoopRec.app — move it to /Applications or launch directly from Finder.

How It Works

┌────────────┐     ┌──────────────────────┐     ┌───────────┐
│ Your Mic   │────▶│                      │────▶│           │
│ (AirPods / │     │       LoopRec        │     │  .m4a     │
│  MacBook)  │     │   (AVCaptureSession   │     │  export   │
└────────────┘     │    × 2 streams)      │     └─────┬─────┘
                   │                      │           │
┌────────────┐     │                      │     ┌─────▼─────┐
│ Zoom/Meet  │────▶│                      │     │mlx_whisper│
│ Speaker →  │     └──────────────────────┘     │ (optional)│
│ BlackHole  │                                  └─────┬─────┘
└────────────┘                                        │
                                                ┌─────▼─────┐
                                                │  Ollama   │
                                                │ (optional)│
                                                └───────────┘

1. Your microphone feeds into LoopRec as the mic source
2. Zoom/Meet/Teams sends speaker output into a Multi-Output Device that includes BlackHole 2ch
3. LoopRec captures both paths simultaneously at 48 kHz / 16-bit
4. On stop, temporary WAV files are mixed and exported as a single .m4a

See docs/INSTALL_AND_ROUTING.md for detailed audio routing setup (especially for AirPods + Zoom).

Local AI Workflow (Optional)

After recording, LoopRec shows a ready-to-paste transcription command:

mlx_whisper "~/Music/LoopRec/Recording_20260317_135510.m4a" \
  --model mlx-community/whisper-large-v3-turbo \
  --output-dir "~/Music/LoopRec" \
  --output-name "Recording_20260317_135510"

From there, feed the transcript into Ollama or any local LLM for meeting notes, summaries, or action items — all without leaving your machine.

Architecture

Sources/
├── AudioEngine/           # Core recording engine
│   ├── Models.swift           # Data types: AudioDevice, RecordingConfig, etc.
│   ├── RecorderEngine.swift   # Protocol defining the capture interface
│   ├── CaptureAudioEngine.swift  # AVCaptureSession-based dual-stream recorder
│   ├── WAVFileWriter.swift    # Low-level PCM → WAV writer
│   └── OfflineMixExporter.swift  # AVComposition-based WAV → M4A mixer
├── SetupWizard/           # Pre-flight checks and user guidance
│   └── SetupAdvisor.swift     # BlackHole detection, permission checks
└── RecordingApp/          # SwiftUI application shell
    ├── RecordingApp.swift     # @main entry point
    └── AppShell/
        ├── AppViewModel.swift # App state and recording lifecycle
        └── ContentView.swift  # Main UI with cards, meters, and controls

Known Limitations

• macOS only (uses AVCaptureSession and system audio APIs)
• BlackHole 2ch is required for system audio loopback
• Best suited for users comfortable with Audio MIDI Setup and Zoom audio routing
• Not signed/notarized — you may need to allow it in System Settings on first launch

See KNOWN_LIMITATIONS.md for the full list.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Sam Zhang