How to Set Up Bluetooth Audio with PipeWire and WirePlumber

Before you start

Bluetooth audio under PipeWire is handled locally by the PipeWire service together with WirePlumber as the session manager. You need a Linux system where PipeWire and WirePlumber are installed and running, plus a paired Bluetooth audio device. The supporting package for Bluetooth support must also be present; on many distributions this is a package named libspa-bluetooth or pipewire-audio, depending on how PipeWire is packaged. Confirm that the Bluetooth adapter is available and not blocked before testing audio routing.

Start by checking whether the services are active. Run systemctl status --user pipewire pipewire-session-manager or systemctl status --user pipewire wireplumber depending on your distribution, and look for an active state. If Bluetooth service management is handled by a separate system service, check that too. Pair and connect the device through your desktop Bluetooth settings or bluetoothctl first; PipeWire cannot route audio to a device the adapter cannot reach.

Step-by-step instructions

Use these steps as a reversible setup path. If a setting already looks correct, leave it unchanged and move to the next step.

• 1. Open a Bluetooth settings window or run bluetoothctl, then connect the target headphones, headset, speaker, or other audio device.
• 2. In bluetoothctl, use devices to list known devices, pair the device address if it is new, trust it, and connect it.
• 3. Confirm WirePlumber sees Bluetooth devices. Run wpctl status and look under the Audio section for the connected device.
• 4. Select the Bluetooth output device when available. Run wpctl set-default with the device ID shown in wpctl status to make it the default output device.
• 5. For a headset microphone, check whether the device is exposed as an input device. Use wpctl status to find it under Sources, then set it as the default input if needed.
• 6. Start playback in the application you want to use, then route the application stream if the desktop volume mixer does not switch automatically.

Bluetooth device names can change between High Fidelity Playback and Headset Head Unit profiles. A headset is typically exposed as an output device for music in the high-quality profile and as a separate input/output device in the headset profile. Switching profiles may be available through the desktop sound settings or wpctl set-profile.

Check the output

Open the sound settings or a volume mixer and confirm that the expected Bluetooth device is marked as the output device. Play audio from one application and watch the application stream meter in wpctl status or pavucontrol, if installed. Meter movement indicates that the stream reached PipeWire, but not that the headset is producing sound, so also listen on the device at a safe volume.

For a microphone, check the input level in the sound settings or wpctl status while speaking. If there is no level, test with one application at a time. Bluetooth microphone input commonly uses a lower sample rate and narrower bandwidth than wired input, and headset mode may reduce playback quality while the microphone is active. That is expected behavior rather than a routing failure.

Common problems and next steps

If the device connects but does not appear as an audio output or input device, check that the Bluetooth support package is installed for your PipeWire version and that WirePlumber has restarted after installation. Restarting the session manager is usually enough; a full reboot is not required unless the Bluetooth adapter itself is stuck.

No sound after selecting the device often comes from the application still using another output. Move the application stream to the Bluetooth device in the mixer, or set the Bluetooth device as default while the application is closed and start it again. Some applications keep the output choice they opened with and will not follow a later default change.

Poor microphone quality, missing input, or unexpected profile changes are usually related to the headset profile. Keep the high-quality playback profile when only listening, and switch to the headset profile when you need the microphone. Background noise may appear more prominent in headset mode because of the limited Bluetooth microphone bandwidth, so place the microphone closer and reduce competing sound instead of raising the input level too high.

If the device worked before and now fails, remove it from Bluetooth settings, pair it again, and confirm the adapter is not connected to another computer or phone. After reconnecting, run wpctl status again and check that the device appears with the expected profile. If waveform meters move but you hear silence, check the physical output level and confirm that the application is not paused or muted.