Lumotia/docs/release/virtual-audio-setup.md

---
name: virtual-audio-setup
type: release
tags: [release, testing, smoke-test, audio, linux, macos, windows]
description: "How to set up a virtual audio source so the smoke harness can run audio-dependent cells unattended — without you speaking into a microphone."
---

# Virtual audio setup for smoke testing

## Why

Lumotia's smoke driver (`scripts/smoke-linux-driver.sh`) can automate the Capture cell — pressing the record hotkey, waiting, stopping — but the recording pipeline needs an audio signal to produce a transcript. Without one it records silence, Whisper returns nothing, and the Cleanup and History cells have nothing to assert against.

A virtual audio source feeds a synthetic signal into the recording pipeline so the smoke harness can run the audio-dependent cells without you talking. You set it up once before a test run and tear it down after.

## Setup on Linux (PulseAudio or PipeWire-pulse)

PipeWire ships a PulseAudio compatibility layer on all major distros since 2022, so the `pactl` commands below work on both.

**Option A — sine-wave tone (always available, no extra files)**

```sh
pactl load-module module-sine-source source_name=lumotia-test frequency=440
```

This creates a virtual microphone that emits a 440 Hz tone continuously. Whisper will transcribe it as something like "A" or ambient noise — enough to produce a non-empty transcript row and exercise the pipeline.

**Option B — WAV file (closer to real speech)**

First generate a test file. If `espeak` is installed you get a synthetic voice; otherwise `ffmpeg` generates a tone:

```sh
# With espeak (sounds like speech — better for Whisper)
espeak -v en -s 150 "Lumotia smoke test one two three" \
  --stdout | ffmpeg -i pipe:0 -ar 16000 -ac 1 -f s16le /tmp/lumotia-test.raw 2>/dev/null
ffmpeg -f s16le -ar 16000 -ac 1 -i /tmp/lumotia-test.raw /tmp/lumotia-test.wav 2>/dev/null

# Without espeak (synthetic tone — still exercises the pipeline)
ffmpeg -f lavfi -i "sine=frequency=440:duration=5" -ar 16000 -ac 1 /tmp/lumotia-test.wav 2>/dev/null
```

Then load the pipe-source:

```sh
pactl load-module module-pipe-source \
  source_name=lumotia-test \
  file=/tmp/lumotia-test.wav \
  format=s16le rate=16000 channels=1
```

**Wire it into Lumotia**

Open Lumotia → Settings → Start Here → Microphone and pick **lumotia-test** from the dropdown. Save. Then run the smoke driver:

```sh
./scripts/smoke-linux-driver.sh [/path/to/AppImage]
```

**Tear down after the run**

```sh
pactl unload-module $(pactl list short modules | grep lumotia-test | awk '{print $1}')
```

The smoke driver does not automatically unload the module, so your regular microphone is unaffected by the test run.

## macOS

Use **BlackHole** (open-source, free from Existential Audio). Install via Homebrew:

```sh
brew install --cask blackhole-2ch
```

After installing, open **Audio MIDI Setup** (Applications → Utilities), create a **Multi-Output Device** that includes both BlackHole 2ch and your speakers if you want to hear output. Set BlackHole 2ch as the input in Lumotia → Settings → Start Here → Microphone.

To feed audio into BlackHole during the test, route any audio player's output to the BlackHole device, or use `ffmpeg` with the AVFoundation backend (note: macOS xdotool equivalents are outside the current smoke-driver scope — these steps are manual on macOS).

## Windows

Use **VB-CABLE** (free from VB-Audio). Download from [vb-audio.com/Cable](https://vb-audio.com/Cable/), run the installer with admin rights, reboot. Set **CABLE Output** as the recording device in Lumotia → Settings → Start Here → Microphone. Route audio to **CABLE Input** from any player to feed the pipeline.

Windows smoke-test automation (UI driving) is not currently in scope for v0.1 — these instructions document the audio-loopback pattern for when it is.