macOS microphone bridge

Docker Desktop on macOS runs Linux containers. Those containers cannot open CoreAudio or /dev/snd the way a Linux edge host can. Cyberwave mirrors the camera MJPEG bridge pattern: host ffmpeg captures AVFoundation audio and serves raw PCM over HTTP; the microphone driver container reads that URL via AudioBridgeCapture instead of PortAudio.

Architecture

Mac host (CoreAudio / AVFoundation)
  └─ ffmpeg LaunchAgent  com.cyberwave.audio-stream*
       └─ HTTP PCM  :8101+  (host.docker.internal from container)
            └─ generic-microphone driver (Docker)
                 └─ WebRTC + Zenoh  →  twin / media-service

Layer	Artifact
Host capture	`ffmpeg` + AVFoundation, managed by `launchctl`
Per-twin map	`~/.cyberwave/audio_streams.json` → `twin_to_stream_url`
Container env	`CYBERWAVE_METADATA_AUDIO_DEVICE=http://host.docker.internal:8101`
Edge-core	Probes ports `8101`–`8110` on Darwin; injects URL when starting the driver

On Linux Docker hosts, skip the bridge: Edge Core bind-mounts /dev/snd and the driver uses PortAudio/ALSA directly. See Native microphone driver — Linux.

Prerequisites

Docker Desktop installed and running (daemon up before cyberwave edge install).
ffmpeg on the Mac host (the CLI installer expects it on PATH).
A microphone twin linked to this edge (catalog generic-microphone asset).
Microphone privacy granted to the terminal or process running ffmpeg when macOS prompts.

First-time setup

Install the CLI and Edge Core (pairing flow):

curl -fsSL https://cyberwave.com/install.sh | bash
sudo cyberwave pair

During cyberwave edge install on macOS, the installer:
- Lists AVFoundation input devices and prompts for a microphone (by index; stored in audio_streams.json).
- Installs a LaunchAgent (com.cyberwave.audio-stream) on port 8101 (additional mic twins use 8102, …).
- Writes ~/.cyberwave/audio_streams.json with twin_to_stream_url entries.
- Restarts Edge Core so driver containers receive CYBERWAVE_METADATA_AUDIO_DEVICE.
Link your microphone twin to the edge in the Cyberwave UI, then restart if you added the twin after install:

sudo cyberwave edge restart

Switch microphone or fix a broken bridge

Re-run selection without a full reinstall:

sudo cyberwave edge install --reconfigure-microphone

Skip the interactive picker when you already know the AVFoundation index:

sudo cyberwave edge install --reconfigure-microphone --microphone-index 0

cyberwave edge restart also self-heals silent ffmpeg slots (launchctl kickstart -k on com.cyberwave.audio-stream*) and warns when audio_streams.json references a port with no running service — same pattern as the camera bridge.

Verify

# Host bridge listening
lsof -i :8101

# Persisted twin → URL map
cat ~/.cyberwave/audio_streams.json

# Driver should show HTTP bridge, not "0 input devices"
cyberwave edge logs -f

Healthy container logs (MQTT/backend errors aside):

Resolved macOS host audio bridge for microphone capture: http://host.docker.internal:8101
Configuring microphone driver (..., selector='http://host.docker.internal:8101', ...)
Using host HTTP audio bridge

Failure signals:

Symptom	Likely cause
`Discovered 0 input devices`	Bridge URL not injected — re-run `--reconfigure-microphone` and `edge restart`
`PortAudio not initialized`	Driver probed ALSA inside Docker — fixed when bridge URL is set (recent driver)
Connection refused to backend/MQTT	Cloud stack not running — start your Cyberwave backend; audio bridge can still be correct

`audio_streams.json` shape

{
  "twin_to_stream_url": {
    "c349694f-0947-421e-9fe0-820e24dc7e96": "http://host.docker.internal:8101"
  },
  "device_index": 0,
  "sample_rate": 48000,
  "channels": 1
}

Edge-core reads this file (and TCP-probes the port) when launching each generic-microphone container. The driver does not enumerate PortAudio devices on macOS Docker when the bridge URL is present.

Local debugging without Docker

Run the driver on the host with direct PortAudio (no HTTP bridge):

cd cyberwave-edge-runtime/runtime-services/drivers/native/cyberwave/generic-microphone
./run-local.sh

Native microphone driver

WebRTC, recording, Zenoh, and env var reference.

Edge overview

macOS edge install, camera bridge, and CLI lifecycle.

Native speaker driver

Playback counterpart — macOS uses a host PCM sink on port 8201 (same bridge pattern).

Hardware in Cyberwave

Featured hardware

Edge computers

Add your robot

Architecture

Prerequisites

First-time setup

Switch microphone or fix a broken bridge

Verify

`audio_streams.json` shape

Local debugging without Docker

Native microphone driver

Edge overview

Native speaker driver

​Architecture

​Prerequisites

​First-time setup

​Switch microphone or fix a broken bridge

​Verify

​audio_streams.json shape

​Local debugging without Docker

​Related

Native microphone driver

Edge overview

Native speaker driver

Architecture

Prerequisites

First-time setup

Switch microphone or fix a broken bridge

Verify

`audio_streams.json` shape

Local debugging without Docker

Related