Added in v0.18.0
PipeWire audio capture in Vocalinux
Vocalinux records from two kinds of source: microphones, opened through PortAudio, and system-audio sources that come straight from PipeWire. This page explains what each one is for, how to pick the right source, and what to check when dictation hears the wrong device or nothing at all.
Two capture paths: PortAudio and PipeWire
PortAudio enumerates ALSA and PulseAudio devices, not PipeWire nodes. That works well for microphones, but it cannot see a sink's monitor, the stream of everything playing through an output. Since v0.18.0 Vocalinux asks PipeWire directly: it lists sinks with pw-dump and records the chosen one with pw-record --raw. PipeWire converts the audio to the format Vocalinux asks for inside its own graph, so no format negotiation is needed.
| Path | What it lists | How it records | Use it for |
|---|---|---|---|
| Microphones (PortAudio) | Input-capable ALSA and PulseAudio devices that PortAudio enumerates, plus System Default | A PortAudio stream, downmixed to mono for the speech engine | Normal dictation into a mic or headset |
| System audio (PipeWire) | Every PipeWire Audio/Sink node, physical or virtual, shown as “System audio: …” | pw-record on that sink's monitor, raw 16-bit mono at 16 kHz | Transcribing what is playing through an output device |
Who this is for
Most people dictate into a microphone and never need to change anything. System audio is for the cases a microphone cannot cover well, such as transcribing speech from a video or a call that plays through your speakers or headphones. For recorded files, the file transcription mode is usually the better tool.
How to choose a source
- 1
Open the Audio page
Open Vocalinux Settings, go to Audio and find Input Device. Use the refresh button next to the list after plugging in a headset.
- 2
Pick a source
Choose System Default to follow your desktop sound settings, a named microphone to pin that device, or a System audio entry to record what plays through that output.
- 3
Run the Microphone Test
Click Test next to Microphone Test. It records 2 seconds and the level meter shows whether any signal arrived.
- 4
Try a real dictation
Use Test Dictation in the Settings sidebar footer, or your dictation shortcut, to confirm the engine hears speech from the chosen source.
System Default
Leaves valid default and virtual inputs under the sound server's control, so the mic you pick in desktop sound settings is the one Vocalinux hears.
A named microphone
A valid explicit choice always wins over System Default. Vocalinux saves the device name and matches it again by name when indexes shift after a replug.
System audio: …
Records one output device's monitor. Two sinks with the same description get the PipeWire node name added in brackets so you can tell them apart.
Settings and limits
Where the choice is stored
The selection lives in ~/.config/vocalinux/config.json under audio.device_index and audio.device_name. A null index means System Default.
Gotchas
- System audio needs both
pw-dumpandpw-record. Without them the entries are simply not listed. - If a saved System audio sink disappears, Vocalinux refuses to record instead of quietly switching to a microphone, because that would capture the wrong audio. Pick a source again.
- A sink monitor records the full mix for that output, including notification sounds and any other app playing at the time.
- The Flatpak release notes list PipeWire system-audio capture as a native-install path. Inside the Snap, Settings → Audio lists the sound server's microphones through
pactlinstead.
Troubleshooting
Dictation uses the wrong microphone
Select the mic by name in Settings → Audio → Input Device rather than relying on System Default. On ALSA-only setups where PortAudio substitutes some other hardware for the default input, Vocalinux prefers an input-capable pulse device so it follows your desktop's choice, and logs a warning when none exists. Run with debug logging to see which device was opened:
user@linux:~$ vocalinux --debugSilence, or a Microphone Stalled notification
Check mute state and levels in your system sound settings, then list capture hardware:
user@linux:~$ arecord -lA Microphone Stalled notification means the selected input stopped delivering audio and Vocalinux stopped that attempt. Use Microphone Test, or choose another Input Device. If a stale device index is the problem, quit Vocalinux and set audio.device_index to null in config.json. With a System audio source, remember that a silent output produces silence: start the playback first.
Bluetooth headsets
Bluetooth headset microphones use a separate capture profile that is sensitive to repeated opening. Vocalinux opens the stream once per session and pauses briefly between failed attempts on Bluetooth devices. If capture still fails, try a wired microphone to check whether the Bluetooth capture path is the cause.
FAQ
Does Vocalinux record microphones through PipeWire?
Microphones are listed and opened through PortAudio, including System Default. The native PipeWire path, pw-dump plus pw-record, is used for the System audio entries, because PortAudio cannot reach a sink monitor.
Can I capture audio from one application only?
No. A System audio entry records the monitor of a whole output device, so everything playing through that sink is mixed into the recording. Per-application stream capture is out of scope in the current code.
Why are there no System audio entries in my device list?
Vocalinux lists them only when both pw-dump and pw-record are on the PATH and the PipeWire daemon answers. If either tool is missing, the list shows microphones only and nothing else changes.
Does system-audio capture send anything online?
Not with a local engine. Audio from either path goes to the engine you selected, and local engines run on your machine. If you switch to the Remote API engine or a VocaGateway, audio is sent to the endpoint you configured.
Which version added PipeWire capture?
PipeWire system-audio capture was added in v0.18.0. Check your version with vocalinux --version.
More fixes on the troubleshooting page. How audio is handled with local and remote engines is covered in offline dictation and Remote API. Speech detection itself is explained in voice activity detection.
Pick a source and dictate
Install Vocalinux, choose your microphone or a system-audio source in Settings → Audio, and run the Microphone Test before your first dictation.