FreeBSD Audio Device Routing: Select PCM Outputs and Diagnose Sound

FreeBSD can expose multiple audio devices at once: onboard analog outputs, HDMI or DisplayPort audio, USB interfaces, and separate PCM channels on one codec. The system can therefore have a working sound driver while an application sends audio to the wrong output, a mixer channel is muted, or a headset is absent.

Troubleshooting is most efficient when performed in layers: enumerate hardware, inspect kernel attachment, identify PCM unit numbers, check mixer state, select the default unit, then test playback in the application. Installing a new codec or changing several device settings at once makes the failure harder to isolate.

Confirm the kernel sees an audio device

Start with the sound status node, kernel messages, and device list:

cat /dev/sndstat
dmesg | grep -i -E 'pcm|hdac|audio'
sysctl hw.snd.default_unit

The Handbook’s HDA example uses dmesg entries containing pcmN to map a codec and output type to a unit. A display adapter can enumerate before the onboard analog codec, so the internal speakers might be pcm4 rather than pcm0. Device numbers are assigned at boot and can change when hardware or driver order changes.

If /dev/sndstat is absent or no pcm device appears, check whether the driver attached and whether the hardware is supported. For HDA devices, snd_hda(4) documents the driver and codec behavior. A PCI device can be present while a particular codec pin layout, amplifier, HDMI controller, or firmware description prevents the expected output from being usable.

Use pciconf -lv to inspect hardware identifiers when needed, then compare them with the driver manual and kernel messages. Do not infer a supported output merely from a vendor name. External USB audio can expose a different class driver and should be diagnosed with USB enumeration tools as well as sound status.

Map PCM unit numbers to physical outputs

List the current sound devices and their PCM numbers. An example might show pcm0 as NVIDIA DisplayPort and pcm1 as Realtek Analog. Use the exact mapping from the host, not numbers copied from another machine.

cat /dev/sndstat
dmesg | grep pcm
mixer -f /dev/mixer0
mixer -f /dev/mixer1

The mixer command reports controls associated with a mixer device. A missing /dev/mixerN may mean that the PCM unit does not expose a mixer node or that the unit number differs. Read mixer(8) for supported device and control syntax before scripting it. The manual’s assignment form uses a control such as vol.volume=70%, not a positional “vol 70” argument.

Set a reasonable output level without maxing every control:

mixer -f /dev/mixer1 vol.volume=70%
mixer -f /dev/mixer1 pcm.volume=70%
mixer -f /dev/mixer1

Control names vary by hardware. Inspect the output first and use controls that actually exist. Muted output, low PCM level, muted speaker pin, and application-specific volume are separate possibilities. Do not run a bulk mixer command that assumes the same controls exist on all machines.

Select the system default

The hw.snd.default_unit sysctl selects the default PCM unit. If the observed analog output is pcm4, test it temporarily:

sysctl hw.snd.default_unit=4
sysctl hw.snd.default_unit
cat /dev/sndstat

Use the unit number identified on the current host. Do not copy 4 from the Handbook’s sample output as a universal value. After the default changes, restart or reselect the output in applications that opened an audio device before the change. Some software caches the device at startup.

To persist the selection, add the verified setting to /etc/sysctl.conf:

hw.snd.default_unit=4

Then verify it after reboot. If device numbering is unstable, a fixed unit index may target a different output after a hardware or driver change. Recheck dmesg and /dev/sndstat after kernel upgrades, dock changes, and USB device insertion.

Test with a known application

Use an application that is already installed and that can select an output device explicitly. Generate a short, non-sensitive test tone or play a known audio file at low volume. Confirm output physically at the expected speakers or headphones. FreeBSD’s base mixer controls levels; they do not generate an audio test stream by themselves.

If the application offers a device list, select the intended PCM device and record the selection. A desktop sound server or application layer may maintain a default independent of hw.snd.default_unit. Diagnose one layer at a time: system default, sound server routing, application device selection, then application volume.

Avoid testing with the system volume at maximum, especially on headphones. A channel can become audible suddenly after switching from HDMI to analog or unmuting a control. Start at a moderate level and adjust only the relevant mixer control.

Diagnose no sound, wrong output, and crackling

If /dev/sndstat lists the intended PCM unit but sound comes from another output, first check hw.snd.default_unit and application routing. Then inspect mixer controls and confirm that the output is physically connected to the connector represented by that PCM unit. HDMI audio may be tied to a specific graphics output or monitor.

If no PCM device appears, inspect hardware detection and driver messages before changing mixer values. Check the kernel module or built-in driver, PCI enumeration, USB messages, and whether the hardware is exposed by firmware. A USB device can be missing from USB enumeration, present but not bound to an audio driver, or bound with no usable PCM unit; each indicates a different layer.

If playback starts but crackles or drops, collect repeatable evidence: application, selected output, sample rate and channel count, CPU load, device connection, and kernel messages. Try a short baseline with one application and no resampling effects. Do not claim that every dropout is a hardware defect; scheduling pressure, application buffering, USB transport, and driver support can contribute.

If audio worked before a change, roll back one change at a time. Restore the prior sysctl, mixer values, application output selection, or module setting and rerun the same test. Keep the initial /dev/sndstat output so that device enumeration changes are visible.

Check whether the failure is device-wide

Test a second application that uses the same PCM device. If both fail, focus on the kernel device, mixer state, physical connection, or sound-server layer. If one application fails, inspect its output backend, per-application volume, sample format, and cached device selection. A successful recording input does not prove playback works, and working HDMI audio does not prove the analog codec is configured correctly.

For an HDA system, preserve the full hdac and pcm messages rather than only the first grep match. The snd_hda manual describes pin and codec information that can help distinguish the controller from the analog codec. Do not apply pin overrides or device hints from another laptop: wiring and amplifier configuration are model-specific, and an incorrect hint can disable previously working jacks.

For virtual_oss or another audio server, document which /dev/dsp endpoint applications open and how that service routes to physical outputs. Plain sound(4) applications may not switch mid-track after a default-unit change; stop and restart playback before concluding that the sysctl had no effect. If a desktop session maintains its own routing graph, use its supported controls instead of repeatedly changing the kernel default.

Keep a compact diagnostic bundle

When reporting a reproducible failure, include freebsd-version -kru, the full /dev/sndstat output, relevant dmesg lines, hw.snd.default_unit, mixer output for the selected unit, exact application and file format, and the physical connection used. Remove private filenames and user data where they are not needed. This gives a driver maintainer enough context to identify enumeration and route changes without a speculative list of unrelated tuning variables.

Make the configuration maintainable

Record the hardware model, driver, PCM unit-to-output mapping, persistent default, and application-specific selection. Keep sysctl configuration separate from rc.conf settings; hw.snd.default_unit belongs in sysctl configuration. Validate entries after major upgrades or when external devices are added.

For a USB headset, test attachment and removal while no critical audio stream is active. Confirm whether unit numbering changes and whether the application follows the new default automatically. A workstation may need explicit application re-selection after a hot-plug; this is not necessarily a kernel failure.

Do not unload an audio module while an application is using the device. Stop playback and close the device cleanly before experimenting. Avoid editing loader tunables that are not documented for the specific driver; unsupported tuning can silence the system or complicate boot diagnostics.

Acceptance criteria

Audio routing is ready when the intended hardware appears in /dev/sndstat, the unit mapping is documented, the default and application routing point to the expected device, mixer controls are unmuted at safe levels, and repeated playback tests produce audible output without kernel errors.

When a problem remains, capture the exact command output and reproduce with a minimal test. Include FreeBSD release, kernel architecture, driver, codec/device identifier, and whether the failure affects analog, digital, USB, or every output. That evidence is more useful than a vague report that “sound is broken.”

Related:

Sources: