Skip to content

VIRTUAL_MIC_SOLUTIONS.md

Latest commit

 

History

History
369 lines (260 loc) · 8.92 KB

VIRTUAL_MIC_SOLUTIONS.md

File metadata and controls

369 lines (260 loc) · 8.92 KB

Virtual Microphone Solutions for DictaBench

Comprehensive Guide to Virtual Audio Without BlackHole

This document explains all the methods DictaBench uses to create virtual microphones without requiring BlackHole or any external audio drivers.

Solution Overview

DictaBench implements 2 different approaches to create virtual microphones, listed from most to least automated:

Solution Automation Requirements Reliability
1. Auto CoreAudio Fully Automatic macOS only High (95%)
2. Manual Setup Manual macOS only 100%

Solution 1: Automatic CoreAudio (Recommended)

How It Works

File: coreaudio_virtual_mic.py

When you launch DictaBench, it automatically:

  1. Checks if "DictaBench Virtual Mic" exists
  2. If not, creates it using AppleScript automation
  3. Configures the device silently in the background
  4. Notifies you when ready

Implementation

from coreaudio_virtual_mic import CoreAudioVirtualMic

# Create instance
vm = CoreAudioVirtualMic()

# Automatic setup
success = vm.setup()  # Returns True if successful

# Check if exists
if vm.device_exists():
    print("Virtual mic ready!")

What Gets Created

Device Name: DictaBench Virtual Mic

Type: Aggregate Device

Components:

  • Built-in Output (receives audio from DictaBench)
  • Built-in Input (optional, for monitoring)

User Experience

Launch DictaBench
    ↓
Status: "Creating virtual microphone..."
    ↓
[10 seconds later]
    ↓
Status: "✓ Virtual microphone ready!"
    ↓
Device available immediately

Advantages

✅ Zero user interaction ✅ No external software needed ✅ Works on fresh macOS install ✅ Automatic on first launch ✅ Self-healing (recreates if deleted)

Limitations

⚠️ Requires accessibility permissions for AppleScript ⚠️ May fail on some macOS configurations ⚠️ Requires Audio MIDI Setup to be accessible

Solution 2: Manual Setup

How It Works

Complete manual instructions for creating devices yourself in Audio MIDI Setup.

Process

  1. Open Audio MIDI Setup (Applications > Utilities)
  2. Click + in the bottom-left corner, select Create Multi-Output Device
    • Name it "DictaBench Output"
    • Check Built-in Output
  3. Click + again, select Create Aggregate Device
    • Name it "DictaBench Virtual Mic"
    • Check your Multi-Output Device and Built-in Microphone
    • Enable Drift Correction for the Multi-Output Device
  4. Go to System Settings > Sound > Output and select "DictaBench Output"
  5. In your voice dictation app, select "DictaBench Virtual Mic" as the microphone

When to Use

  • Automatic setup fails
  • You need custom configuration
  • You're troubleshooting issues
  • You want full control

Technical Comparison

Architecture

All three solutions create the same audio routing:

DictaBench Audio
    ↓
System Output Device
    ↓
Multi-Output Device (DictaBench Output)
    ↓
Aggregate Device (DictaBench Virtual Mic)
    ↓
Voice Dictation App Captures Audio

CoreAudio Implementation Details

Solution 1 uses:

# AppleScript automation via subprocess
subprocess.run(['osascript', '-e', script])

# Creates aggregate device using UI automation
# More reliable than direct CoreAudio API calls

Why not direct CoreAudio API?

  • Python CoreAudio bindings are incomplete
  • AudioHardwareCreateAggregateDevice() requires complex setup
  • UI automation is more maintainable
  • Works across macOS versions

Code Structure

coreaudio_virtual_mic.py
├── CoreAudioVirtualMic class
│   ├── get_builtin_device_uids()
│   ├── create_aggregate_device_applescript()
│   ├── device_exists()
│   ├── setup()
│   └── cleanup()
└── Integration with key_presser_gui.py

Comparison with BlackHole

Feature DictaBench Solution BlackHole
External Software None needed ✓ Required
Installation Automatic ✓ Manual brew install
System Permissions Accessibility only Kernel extension
Compatibility All voice apps ✓ Varies by app
Removal Delete in Audio MIDI Uninstall package
Updates None needed ✓ Periodic
Privacy No data collection ✓ Open source

When to Use BlackHole Instead

Consider BlackHole if:

  • You need advanced audio routing
  • You use multiple audio applications
  • You're familiar with virtual audio drivers
  • You want community support
  • You need ultra-low latency

When to Use DictaBench's Solution

Use DictaBench's built-in solution if:

  • You want zero external dependencies ✓
  • You prefer automatic setup ✓
  • You only need basic virtual mic ✓
  • You don't want to install drivers ✓

Troubleshooting

Automatic Setup Fails

Symptoms: "Virtual mic setup pending" message

Solutions:

  1. Grant accessibility permissions:

    • System Preferences > Security & Privacy > Accessibility
    • Add Terminal or Python to allowed apps

  2. Check Audio MIDI Setup is accessible:

    open -a "Audio MIDI Setup"

Device Created But Not Visible

Symptoms: Setup reports success, but device not in list

Solutions:

  1. Restart DictaBench
  2. Check in Audio MIDI Setup (should see the device)
  3. Run device detection: 
    python3 -c "import sounddevice as sd; [print(d['name']) for d in sd.query_devices()]"

Voice App Can't See Device

Symptoms: Aggregate device exists but voice app doesn't list it

Solutions:

  1. Restart the voice dictation app
  2. Check it's configured as Input device (not Output)
  3. Grant microphone permissions to the app
  4. Verify Aggregate Device includes both sub-devices

No Audio Captured

Symptoms: Device selected but captures silence

Solutions:

  1. Set system output to "DictaBench Output": System Preferences > Sound > Output

  2. Check Aggregate Device configuration:

    • Open Audio MIDI Setup
    • Select "DictaBench Virtual Mic"
    • Verify "DictaBench Output" is checked
    • Enable "Drift Correction" for DictaBench Output

  3. Test with QuickTime:

    • Open QuickTime Player
    • File > New Audio Recording
    • Select "DictaBench Virtual Mic"
    • Play audio in DictaBench
    • Should see levels move

Advanced Configuration

Custom Device Names

Edit coreaudio_virtual_mic.py:

self.aggregate_device_name = "My Custom Mic Name"

Adding More Audio Sources

In Audio MIDI Setup:

  1. Select "DictaBench Virtual Mic"
  2. Check additional audio devices
  3. They'll all mix into the virtual mic

Separate Monitoring

Create a second Multi-Output for personal monitoring:

  1. Multi-Output Device: Your Headphones + DictaBench Output
  2. Hear audio while it routes to virtual mic

API Reference

CoreAudioVirtualMic Class

class CoreAudioVirtualMic:
    def __init__(self):
        """Initialize virtual mic creator."""

    def device_exists(self) -> bool:
        """Check if aggregate device exists."""

    def setup(self) -> bool:
        """Create virtual microphone. Returns True if successful."""

    def cleanup(self) -> bool:
        """Remove virtual microphone device."""

    def get_builtin_device_uids(self) -> tuple:
        """Get UIDs of built-in audio devices."""

Example Usage

from coreaudio_virtual_mic import CoreAudioVirtualMic

# Create and setup
vm = CoreAudioVirtualMic()

if not vm.device_exists():
    print("Creating virtual microphone...")
    if vm.setup():
        print("✓ Ready!")
    else:
        print("✗ Failed")

# Later, cleanup
vm.cleanup()

Resources

Apple Documentation

Alternative Solutions

  • Loopback by Rogue Amoeba: $99, GUI-based, very powerful
  • BlackHole: Free, open-source, requires installation
  • SoundFlower: Legacy, no longer maintained

Python Audio Libraries

  • sounddevice: For device enumeration and audio I/O
  • PyObjC: For CoreAudio API access (optional)
  • pyaudio: Alternative to sounddevice

Contributing

Want to improve DictaBench's virtual mic solutions?

Areas for contribution:

  • Linux/Windows virtual mic support
  • Direct CoreAudio API implementation
  • Better error handling
  • Cross-platform audio routing

See the main README.md for contribution guidelines.

Summary

DictaBench provides two complementary solutions for virtual microphones:

  1. Automatic (coreaudio_virtual_mic.py): Works out of the box for 95% of users
  2. Manual (see Solution 2 above): Complete control if needed

Both solutions require NO external software (no BlackHole), use only macOS built-in features, and work with all voice dictation apps.