quick-docs/modules/ROOT/pages/how-to-troubleshoot-sound-problems.adoc

= How to troubleshoot sound problems
Hank Lee ; The Music and Audio SIG
:revnumber: F40
:revdate: 2025-05-28
:category: Administration
:tags: Troubleshooting, Sound, Multimedia

[abstract]
This page covers some basic troubleshooting techniques to help narrow down the root cause of an issue. It also explains information that should be included when filing bugs related to sound. General sound problems - where the problem is observed across multiple applications - should usually be filed against the kernel, or PipeWire (see below for instructions on determining whether the problem is PipeWire-related). If the problem is observed only in a specific application, or only in applications which use a single multimedia library (such as SDL or OpenAL), the bug should be filed against that component.

== Introduction

Sound problems in Fedora can arise from a variety of causes, ranging from misconfigured audio services to missing or outdated drivers. In most cases, these issues are related to the transition to PipeWire, Fedora's default audio server since Fedora 34. While PipeWire aims to unify and improve audio handling across applications, its integration with legacy tools like PulseAudio and ALSA can sometimes lead to conflicts or device recognition problems.

Typical issues users may encounter:

* No sound output or input
* Only “Dummy Output” is available
* Microphones not being detected
* Audio devices missing after updates
* Broken Bluetooth audio connections

This guide provides a step-by-step approach to diagnosing and resolving these sound issues. It covers both general troubleshooting and specific fixes for input-related problems, such as missing microphones or inactive input devices.

== Diagnosing the Problem

- Determining if the issue is with the kernel, PipeWire, or specific applications.
- Collecting logs and system information.

=== Check which Kernel driver is in use by PCI devices

To display kernel drivers handling each device, use the lspci (List PCI) command with the option -k. Searching for known issues specific to driver’s name and your hardware model before reporting issues to Ask Fedora.

[source,bash]
----
$ sudo lspci -k
----

New hardware drivers are updated continuously. If you see a device listed as unknown, query your PCI device ID database.

[source,bash]
----
$ sudo lspci -Q
----

And update your local PCI ID database by running the command update-pciids.

[source,bash]
----
$ sudo update-pciids
----

=== ALSA Firmware

The ALSA Firmware package contains firmware for various third-party sound cards.

See which firmware is in use by running the following command.

[source,bash]
----
$ sudo dnf list alsa-firmware
----

The regular ALSA Firmware will appear <alsa-firmware.noarch>.

If the regular firmware is not on the output, install the alsa-firmware.

[source,bash]
----
$ sudo dnf install alsa-firmware
----

If any other firmware is installed, put them on blocklist on configuration directory for modprobe.

----
/etc/modprobe.d/*.conf
----

Add the line on configuration file.

----
blacklist <the module to blocklist>
----

The dracut tool creates an initial image used by the kernel for preloading the block device modules. The option -f overwrite existing initramfs file.

[source,bash]
----
$ sudo dracut -f
----

Reboot your computer for the change to take effect.

[source,bash]
----
$ sudo reboot
----

=== Hardware information

It is always useful to include detailed information on your sound hardware when filing a sound-related bug. To produce this information, run this command:

[source,bash]
----
$ alsa-info.sh --no-upload
----

It will generate a file containing detailed information about your sound hardware with the name /tmp/alsa-info.txt. Attach this file to your bug report.

=== Is it PipeWire?

PipeWire is a media sharing server, low-level multimedia framework that aims to;

* improve handling of audio and video under Linux

* work for all users at all levels

* offer support for PulseAudio, JACK (JACK Audio Connection Kit), ALSA and GStreamer-based applications

=== Visual checks on ports

Qpwgraph is a graph manager dedicated to PipeWire.

Visual checks on ports using Qpwgraph will help discover all the routing between applications and devices and change the routing as you need. For example, if multiple applications and devices are connected and disconnected like below,

* Firefox: video conference application using WebRTC protocol

* VLC: media playback

* OBS Studio: live stream and recording

* USB soundcards or mixers: devices

it will be useful to learn how ports are connected to applications and devices graphically.

Ports are directional, they can be either:

* Source ports (output). Located at the right-most edge of a node, they generate an audio/video/midi stream.

* Sink ports (input). Located at the left-most edge of a node, they consume an audio/video/midi stream.

Ports also have different types:

* Audio (default color: green)

* Video (default color: blue)

* PipeWire/JACK MIDI (default color: red)

* ALSA MIDI (default color: purple)

Ports of the same type and opposite directions can be connected.

Check the upstream documentation for user guide link:https://gitlab.freedesktop.org/rncbc/qpwgraph/-/blob/main/docs/qpwgraph-user_manual.md[Qpwgraph User Guide].

== Resolving Audio Input Issues

Follow these steps to resolve most audio input issues.

Solution steps:

=== Step 1: Reinstall PipeWire and Related Packages

Make sure the necessary PipeWire components are installed and working correctly.

[source, bash]
----
$ sudo dnf reinstall pipewire pipewire-pulseaudio pipewire-alsa wireplumber
----

Then reboot your system.

=== Step 2: Check Audio Service Status

Ensure that the PipeWire and WirePlumber services are active.

[source, bash]
----
$ systemctl --user status pipewire
$ systemctl --user status wireplumber
----

If they are not running, enable them:

[source, bash]
----
$ systemctl --user enable --now pipewire
$ systemctl --user enable --now wireplumber
----

=== Step 3: Verify User Permissions

Check that your user belongs to the correct groups:

[source, bash]
----
groups
----

If `audio` is missing, add it:

[source, bash]
----
$ sudo usermod -aG audio $USER
----

=== Step 4: Reset configuration files

If the audio configuration is corrupted, you can reset it by moving the old config folders:

[source, bash]
---- 
$ mv ~/.config/pulse ~/.config/pulse_backup
$ mv ~/.config/pipewire ~/.config/pipewire_backup
----

Then reboot your system.

=== Step 5: Check hardware

If you're using an external microphone, try reconnecting it or testing with a different device to rule out hardware issues.

== Diagnosing and Fixing Bluetooth Audio Problems

Bluetooth audio issues can often be categorized into one of three categories: device detection, pairing, or audio profile switching. This section provides a structured guide for identifying the stage where the issue occurs and how to resolve it.

=== Category 1: Device Not Detected

*Symptoms*

* Bluetooth audio device does not appear in `bluetoothctl` or GNOME Settings.
* No MAC address shown even while device is in pairing mode.
* `btmon` shows no the Host Controller Interface (HCI) events.

This usually means the Linux Bluetooth stack never received an advertisement packet from the device. Common causes include:

* The Bluetooth adapter (HCI device) is not fully initialized or supported.
* The device uses a newer Bluetooth version or chipset that requires kernel or firmware support not yet available.
* The device requires special vendor-specific commands for pairing.
* Signal interference or range issues (less likely if other devices are detected).

*Check*

Run the following command to list Bluetooth devices and their statuses.

[source, bash]
----
  $ hciconfig
  hci0:	Type: Primary  Bus: USB
  	BD Address: 12:34:56:78:9A:BC  ACL MTU: 1021:8  SCO MTU: 64:1
  	UP RUNNING 
  	RX bytes:1234 acl:0 sco:0 events:68 errors:0
  	TX bytes:5678 acl:0 sco:0 commands:65 errors:0
----

The `UP RUNNING` status indicates that the Bluetooth adapter is active and functioning properly. If the device is down or missing, it may require driver or firmware updates.

* Use `btmon` to monitor Bluetooth traffic and look for *LE Advertising Report* or *Inquiry Result* events. For example, a typical *LE Advertising Report* might look like this.

[source, bash]
----
  $ sudo btmon
  HCI Event: LE Meta Event (0x3e) plen 42
  LE Advertising Report
    AdvType: Connectable undirected - ADV_IND (0x00)
    Address: 12:34:56:78:9A:BC (Random)
    Data length: 31
    Flags: 0x06
----

Start the Bluetooth control tool.

[source, bash]
----
  $ bluetoothctl
  Waiting to connect to bluetoothd...[bluetooth]# Agent registered

  [bluetooth]# scan on
  [bluetooth]# SetDiscoveryFilter success
  [bluetooth]# Discovery started

  [NEW] Device 34:F6:4B:77:10:27 Sony WH-1000XM4
  [NEW] Device 5C:3A:9B:12:34:56 JBL Flip 5
  [NEW] Device 00:1A:7D:DA:71:13 Keyboard K380
  [CHG] Device 34:F6:4B:77:10:27 RSSI: -40
  [CHG] Device 5C:3A:9B:12:34:56 RSSI: -55
  [CHG] Device 34:F6:4B:77:10:27 Name: Sony WH-1000XM4
----

[NEW] Device <MAC Address> <Device Name>: Indicates a new device has been discovered.

[CHG] Device <MAC Address> RSSI: <value>: Notification of a change in signal strength (Received Signal Strength Indicator).

Discovery started: Indicates that scanning has begun.

If your Bluetooth device (expected MAC like 34:F6:4B:77:10:27) does not appear in the list while other nearby devices are detected, this clearly indicates that your device is not broadcasting advertisement packets properly. This points to a low-level compatibility or hardware issue with your device itself, rather than a problem with the Bluetooth adapter.

*Caution*

* Some Bluetooth devices—especially newer models using Bluetooth 5.2+—may not be fully compatible with Linux unless the kernel and BlueZ stack support their advertisement mode and codec negotiation.

NOTE: If the device never appears in scans (no MAC shown), this is often **not solvable by user-level configuration or re-pairing**, and may indicate hardware or firmware-level incompatibility.

*Recommendation*

* Test the device on other operating systems (Windows, macOS, Android) to confirm functionality.
* Search bug trackers (e.g. kernel.org, Fedora Bugzilla, bluez mailing list) for known issues related to the specific device or chipset.
* If no workaround exists, consider using another headset known to work well with Linux (some vendors like Jabra, Sennheiser, Logitech have better Linux track records).

*Comment*

* In community forums, it's helpful to distinguish device detection issues from pairing or profile switching problems. Many Bluetooth devices work well under Linux. However, some may exhibit issues—such as failing to pair or not switching audio profiles—because of missing drivers, unsupported codecs, or limitations in kernel or firmware support. Understanding the differences between these issue types helps users know what to expect and makes it easier for contributors to improve guidance and support.

=== Category 2: Pairing Fails or Is Incomplete

*Symptoms*

* Device is visible but cannot be paired or consistently fails to connect
* Authorization timeouts or connection errors

*Check*

* Use `bluetoothctl` for manual steps.

[source, bash]
----
$ bluetoothctl
power on
agent on
default-agent
scan on
pair <MAC>
trust <MAC>
connect <MAC>
----

*Fix*

* Remove device and retry pairing.

[source, bash]
----
$ bluetoothctl remove <MAC>
----

* Restart Bluetooth service.

[source, bash]
----
$ sudo systemctl restart bluetooth
----

For some devices, make sure to hold the pairing button until rapid blinking starts.

=== Category 3: Missing or Failing Audio Profiles

*Symptoms*

* Device connects but no sound is played.
* Only HSP/HFP is available, A2DP is missing.
* Microphone works but stereo audio output does not.

*Check*

* Confirm PipeWire is used.

[source, bash]
----
$ pactl info | grep Server
----

* To confirm whether the A2DP profile is missing and only HSP/HFP is available, use the following command.

[source, bash]
----
$ pactl list cards
----

Then, look for the Profiles section under your Bluetooth device. You can filter the output using grep to make it easier.

[source, bash]
----
$ pactl list cards | grep -i 'profile\|name:'
----

If the output shows only headset_head_unit or similar HSP/HFP entries and no a2dp_sink, it means A2DP is not available. This typically indicates:

* The Bluetooth codec (Example: AAC, aptX) may not be supported or enabled in your PipeWire configuration.

* Your device firmware or the system's Bluetooth stack lacks proper support for stereo audio profiles.

* A WirePlumber policy or module might be blocking the A2DP profile.

Example Output (Missing A2DP):

[source, bash]
----
        Profiles:
                headset_head_unit: Headset Head Unit (HSP/HFP) (available: yes)
                off: Off (available: yes)
----

Expected Output (A2DP Present):

[source, bash]
----
        Profiles:
                a2dp_sink: High Fidelity Playback (A2DP Sink) (available: yes)
                headset_head_unit: Headset Head Unit (HSP/HFP) (available: yes)
                off: Off (available: yes)
----

If A2DP is missing, you may need to review the bluetooth.lua.d configuration in your WirePlumber setup or check codec support.

Look for the configuration file.

[source, bash]
----
$ ls ~/.config/wireplumber/bluetooth/51-bluez-config.lua
----

Back up your config file before editing, so you can easily restore the original if something goes wrong.

[source, bash]
----
$ cp ~/.config/wireplumber/bluetooth/51-bluez-config.lua ~/.config/wireplumber/bluetooth/51-bluez-config.lua.bak
----

Open the configuration file in a text editor.

[source, bash]
----
$ nano ~/.config/wireplumber/bluetooth/51-bluez-config.lua
----

Create your own config file (minimal AAC-enabled example).

[source, lua]
----
bluez_monitor.properties = {
  ["bluez5.enable-sbc-xq"] = true,
  ["bluez5.enable-msbc"] = true,
  ["bluez5.enable-hw-volume"] = true,
  ["bluez5.codecs"] = {"sbc", "aac"}
}
----

Save the file. Restart WirePlumber (if running as user service).

[source, bash]
----
$ systemctl --user restart wireplumber
----

*Fix*

* Manually switch to A2DP profile.

[source, bash]
----
$ pactl set-card-profile <card> a2dp-sink
----

* Ensure required packages are installed.

[source, bash]
----
pipewire-pulse
wireplumber
bluez
----

Use `blueman` for profile selection if needed.

=== Notes

* Some Bluetooth 5.3+ headsets require newer kernel support.
* High-quality codecs (Example: AAC, aptX) may not be supported by default.
* Diagnostic tools:

[source, bash]
----
$ btmon
$ bluetoothctl
$ journalctl -xeu bluetooth.service
----

== Pipewire Debugging options

Debugging usually starts after the bug has been identified, and works best when users are very familiar with the circumstances surrounding the bug.

PipeWire has its own debugging options. Please see the upstream documentation link:https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Troubleshooting#pipewire-debugging-options[PipeWire debugging].

== Need More Help?

If the above steps don't resolve your issue, visit the Fedora community:

* https://discussion.fedoraproject.org/ – Ask Fedora

Contributions and feedback help improve Fedora documentation for everyone.