Troubleshooters.Com, Linux Library, and Linux Sound Studio Present:
Troubleshooting Linux Sound
Copyright © 2013, 2023 by Steve Litt
See the Troubleshooters.Com Bookstore.
CONTENTS:
Troubleshooting audio can actually be dangerous if you do things like test wearing earphones or test on a huge capacity amplifier. NEVER test audio wearing headphones! This document assumes you work in a safe way. We are not responsible for outcome, or even injury, associated with your use of this document. If that's not acceptable, you may not read this document and you may not use its tools. You are fully responsible for the outcome of your sound troubleshooting.
I love Linux, but at certain times I curse it. Like when I can't get the sound to play. So many entangled components, so little guidance. This document introduces a few scripts you can use to make Linux sound troubleshooting quicker and easier.
Things have changed since this page was originally authored in 2023. Pulseaudio has turned out to be the land of a thousand mutes, and is in the process of being replaced by software called Pipewire. For the past seven years I've used ALSA without Pipewire, and the only downside has been that I can't do Zoom conferences, I need to do Jitsi or BigBlueButton.
For the time being, I won't discuss Pipewire, because it has interlocking dependencies with dbus, your Desktop Environment or Window Manager, elogind or seatd, and XDG_RUNTIME_DIR, so at this time I don't have the time to put in the work to get it installed. Note that I have non-systemd Void Linux installation using the simplistic Openbox window manager. If you're using something like Ubuntu with Gnome, installing Pipewire will probably be much easier.
Note:
I'm not recommending you use Ubuntu, systemd or Gnome. In fact, I've gone out of my way to not use any of them. I'm just saying that if you're using them, Pipewire installation will be easier.
Part 1 was added in December 2023. It addresses a Linux sound system that uses only ALSA with no Pulseaudio, Pipewire or Jack. It's simpler and easier to troubleshoot without all the extra mutes that Pulseaudio adds.
The following diagram is an oversimplfied representation of an ALSA-only Linux sound system.
Oversimplification warning:
The preceding diagram shows mplayer, etc, outputting into configuration file ~/.asoundrc. This is not how it works, obviously, but it's a simplification making clear that ~/.asoundrc plays no part in a properly constructed speaker-test command. To portray the actual situation, I would have had to add another box, influenced by ~/.asoundrc, and show mplayer going into that box while speaker-test goes into the box marked alsaSee my Making Mental Models: Advanced Edition for details.
In the preceding diagram, notice that speaker-test goes around ~/.asoundrc, thereby discarding any effect of ~/.asoundrc on the sound. So a properly constructed speaker-test is a great way to test your sound system in the absence of ~/.asoundrc. Properly constructed executables aplay, arecord and amixer also go directly into your ALSA system. ALSA passes a digital signal to your sound card, which does digital to analog conversion and passes the analog to the external amplifier, which passes an amplified signal sufficient to driver your speakers, to your speakers.
Note:
The external amplifier is often built into the cabinet of the speakers. I call it "external" because it's external to your computer. Also, a few of the cheapest computer speakers need no amplifier and are driven, at very soft volumes, by the sound card. Headphones are usually driven directly from the sound card.
DANGER!
Never troubleshoot while wearing headphones. A diagnostic test could cause a super loud sound that can permanently harm your hearing, possibly to the point of permanent deafness.
The penny test is a test to test your amplifier and speakers or amplified speakers, from the plug that goes into your sound card right through the electronics and speaker drivers. It does not work with headphones or with unamplified speakers without an amplifier between the sound card and speakers. Here's the penny test:
Unplug your speakers from the computer (but not from the wall), and rub an American penny or other copper coin along the side of the speaker plug. You should hear static clicks, and if you listen carefully, when the penny touches the tip or the metal adjacent to the tip, you'll hear a low volume buzz. If you don't hear any of these things, increase the volume, make sure the speakers are plugged into power and turned on, and try again. If you still don't hear it, your amplifier or speaker system is probably bad, so swap in a known good set of computer speakers.
DANGER:
To prevent permanent ear damage or deafness, never troubleshoot audio problems wearing earphones.
~/.asoundrcUse the following template for ~/.asoundrc:
# CRITICAL!!! For "hw:num:othernum" in slave,
# match num to card number and othernum to
# device number, both from the aplay -l command.
pcm.!default {
# Must be type plug
type plug
slave.pcm "my_arbitrary_name"
}
pcm.my_arbitrary_name {
# Must be type dmix
type dmix
# Must be ipc_key 1024, I don't know why
ipc_key 1024
slave {
pcm "hw:<card number>,<device number>"
# Following stuff probably unnecessary, possibly
# harmful, but might help with certain songs
#period_time 0
#period_size 1024
#buffer_size 4096
#rate 44100
}
}
In the preceding, <card number> and <device number> are numbers you obtain from the aplay -l command, as explained in the upcoming flowchart. Just plug in these numbers.The flowchart is optimized for minimum time to repair. Please keep in mind that audio problems, even with only ALSA and no Pulseaudio, can be difficult and time consuming to repair. The troubleshooting flowchart follows this paragraph...
Part 2 gives you details of the workings of several utilities for troubleshooting sound.
Most Linux distributions give you a package with a name similar to "alsa-utils". If your computer makes sound, this package is a must, because it gives you many great diagnostic and adjustment tools.3
This is ALSA's music player, and it's also great for learning what's going on. Its input into ALSA isn't quite as direct as you might think, and it can play only certain sound formats, so its troubleshooting value as a sound injector is limited, perhaps not as good as mplayer. But its value as a research tool is unparallelled. For instance, here's the quick way to find all the sound cards in a system:
slitt@mydesk:~$ aplay -l **** List of PLAYBACK Hardware Devices **** card 0: Intel [HDA Intel], device 0: ALC883 Analog [ALC883 Analog] Subdevices: 0/1 Subdevice #0: subdevice #0 card 0: Intel [HDA Intel], device 1: ALC883 Digital [ALC883 Digital] Subdevices: 1/1 Subdevice #0: subdevice #0 slitt@mydesk:~$
In the preceding command, it found two devices, one analog and one digital, on my sound card. You can get a list of all PCMs with the -L (uppercase, not lower) option, but it outputs so much stuff it's not shown in this document.
The arecord program is to recording and input what aplay is to playback and output. So you can use arecord to record a .wav file, and you can also use the -l flag to list input devices, as follows:
slitt@mydesk:~$ arecord -l **** List of CAPTURE Hardware Devices **** card 0: Intel [HDA Intel], device 0: ALC883 Analog [ALC883 Analog] Subdevices: 0/1 Subdevice #0: subdevice #0 card 0: Intel [HDA Intel], device 2: ALC883 Analog [ALC883 Analog] Subdevices: 1/1 Subdevice #0: subdevice #0 card 1: HD3000 [Microsoft® LifeCam HD-3000], device 0: USB Audio [USB Audio] Subdevices: 0/1 Subdevice #0: subdevice #0 slitt@mydesk:~$
The preceding listing shows all input devices: One analog and one digital device on my computer's built-in sound card, and a USB Audio on my Microsoft webcam. Just like saplay, sarecord also features the s-L parameter to view PCMs. As a matter of fact, saplay and sarecord are really the same program, and either can be made into each other with the s-P switch for playing, or the s-C switch for recording.
amixer serves two purposes:
In my opinion it's also more stable and dependable than any of ALSA's more interactive mixers such as alsamixer and alsamixergui. Here are some uses of amixer as a command line/shellscript mixer interface to ALSA:
Using amixer as a diagnostic tool is even better. You already know the card number of the card you need information on (remember how you used aplay and arecord to get a card list?). Now, armed with the card number (assume it's 0 for this example), you can get a list of that card's controls like this:
amixer -c0 scontrols
Perhaps you want to see a list of the controls with all the settings for each control. No problem, watch this:
amixer -c0 scontents
The output of the preceding is huge, but if you're any good at all with the AWK parsing language, you can find out anything you need and turn it into exactly what you want by parsing the output of that command with your AWK script. As a matter of fact, my diagnostic tools work exactly that way.
Alsamixer is the ncurses based mixer for ALSA. It's great for changing volumes and quick observations, but I've found it buggy and hard to use for troubleshooting, and in certain situations it can prevent other troubleshooting diagnostic tests from working properly.
The speaker-test program provides a nice, easy way to provide input for your sound system. When used with no arguments, it simply supplies white noise to both speakers. I like to use it like this:
speaker-test -c2 -t wav
The preceding plays .wav files that alternately say "left speaker" and "right speaker" out of alternate speakers, thereby testing your stereo separation. If you have more than 2 channels, put the number of channels in the -c argument.
What I like about speaker-test is that it doesn't depend on Firefox, Youtube, mplayer, or anything else that, in and of itself, might have problems. Once you have everything working with speaker-test, you can then troubleshoot anything that doesn't work, like Youtube, knowing that the problem is there, not in your sound system itself.
Some distributions have ALSA compiled into the kernel, and some don't. The ones that don't come with an executable called alsa. Because my Void Linux has compiled-in ALSA, I don't have alsa and so know very little about it. The one thing I know is that most distros without ALSA compiled into the kernel use the following command to restart ALSA:
sudo alsa force-reload
The alsactl utility is tremendously featureful and powerful, but take a lot of learning. The one place I use it is to rescan my ALSA config and devices, with the following command:
sudo alsactl kill rescan
The preceding works well on distributions with ALSA compiled into the kernel.
Sometimes a sound problem is deeper than just a misconfiguration. Sometimes the hardware can't be found, either because it's broken, non-existent, or it's turned off in the BIOS. This section discusses three utilities for hardware detection:
If no cards show up, or if the only card that shows up is a microphone-only, then that's what you have to fix.
The following hardware-scanning command shows whether any working sound cards exist:
lspci -v | grep -B1 -A12 -i audio
If you don't see evidence of the sound card in that output, your sound card is probably bad, or it's not a PCI soundcard (perhaps it's USB?). Unless you're sure it's a PCI soundcard, just to rule out the possibility of a non-PCI soundcard, execute this command:
lsusb -v | grep -B1 -A12 -i audio
Use lsusb the same way you use lsusb. The difference is, lsusb shows any USB based sound cards. Another utility that does something similar is usb-devices, which shows a lot more information. More info might be a good thing or a bad thing, depending on your situation.
sudo lshw | grep -B4 -A10 -i audio
The lshw is inferior to the lspci one because it's slower and requires root privileges, but it detects sound cards anywhere on the bus.
One thing that probably would not cause the sound card to fail to show in lspci or lshw commands would be a lack of drivers. I say this based on an experiment I did, in which I created file /etc/modules.d/blacklist-littsound.conf, to blacklist all the sound modules listed in lsmod. When I rebooted, lspci still showed the sound card. The computer wouldn't make sound, and lsmod showed no sound drivers, but lspci still showed the hardware.
So, although I'm not certain, I'm pretty sure that if your sound card doesn't show up in either lspci, lsusb or lshw, that means either you have no sound card, the sound card is defective, or a motherboard sound card is disabled in the BIOS. So that's what you should start fixing.
If it shows up in lspci, lsusb or lshw, and you've unmuted and turned up all volumes in alsamixer, it's probably a driver problem. Driver problems are a pain and a half, so look at alsamixer and to make sure there are no mutes or zero levels.
Note:
As mentioned throughout this part, these conclusions assume Pulseaudio is not installed. If Pulseaudio, which I personally call "the land of a thousand mutes", is installed, then use pavuctl to unmute and raise to loud every volume.
A sound driver is a small piece of software linking the hardware sound card to the sound part of the operating system. In order for sound to come out your speakers, you need sound drivers matching your sound card to be loaded in memory. The reason I suggest troubleshooting sound drivers last is that they're difficult and time consuming to troubleshoot. When you seem to have ruled out everything else, investigate sound drivers. Here are some questions you should have in mind before starting to troubleshooting sound drivers:
Here are some of the tools you'll use to diagnose and fix driver problems:
As far as which driver to use with the card, lspci is of great help. Sometimes it straight out tells you the driver. See this:
As you see, lspci gave the name of the driver, snd_hda_intel. But even if it hadn't, just knowing that the hardware device is the Intel 82801I (ICH9 Family) helps you research the proper driver on the Internet. Once you know the right driver, and have installed it on your computer, you can load it with modprobe and test whether it loaded using lsmod.
If it's not loading, research on the Internet whether there are conflicts with other, unnecessary drivers, and if so, blacklist those conflicting drivers (learn more about blacklisting on the Internet). If you suspect it's the wrong version, see if you can obtain the right one.
Driver troubleshooting is a bear. Your best resource is Internet research, asking friends, and a lot of thought and experimentation.
I hope you never need to get this far, because the things in this section are more of a wing-and-a-prayer situation than systematic troubleshooting. But when prayers are all you have left, that's what you do.
Do enough web research, and you hear strange stories. A guy added options snd-hda-intel model=hp-m4 to a new file /etc/modprobe.d/snd-hda-intel.conf to get the laptop's internal speakers to work, after getting the symptom where only the headphones worked. Discussions of modifying /var/tmp/alsaconf.cards or /var/lib/alsa/asound.state. Conflicts between oss, ALSA and/or Pulseaudio. Sometimes you need to spend time reading and trying this stuff, and eventually something might work.
qmmp is a graphical player very much like the old xmms. The cool thing about it is that in the configuration, you can tell qmmp where you want its output to go: ALSA, Pulseaudio, oss, Jack, or several other places. Play a song on repeat, and change between them until you get something that makes sound. Then try to adapt your ALSA, Pulseaudio or (gulp) oss to do the same thing.
NOTE:
oss is the original Linux sound system. It has pretty much been replaced by ALSA, but some people have oss installed because some old software can play only through oss. Unless you absolutely need oss, don't install it. I've heard rumors of it conflicting with ALSA (works fine on my computer, but who knows).There's other software offering similar troubleshooting benefits as qmmp. The old xmms is one, assuming you can find it any more. Xmms has morphed into a command prompt software with its xmms2, and the project's official GUI player is something called promoe. Good luck with promoe if your vision isn't 20/10: It's the size of two postage stamps with tiny writing and unfathomable icons. Xmms2 itself would be a great resource for anyone remembering all its commands.
I do this all the time, with all sorts of problems. Video doesn't work? Boot Knoppix. Or System Rescue CD. Or Xubuntu. Same with sound. When you've spent a couple hours ripping your hair out over a sound problem, the ten minutes required to boot a live CD and test suddenly seems a lot shorter. If you do get a distro to make sound when the original distro didn't, get all the information you can using lspci and lsmod and various commands like amixer, aplay and the like. Look at config files. Exploiting the differences between a working and a nonworking system is a very powerful troubleshooting tactic you can use.
This is a must! You must establish a baseline.
Before your sound system breaks, or once you get your sound working, write down how it works. In a directory in your backed up data, write the output of your lspci -v command, your lsmod command, your aplay -l and arecord -l commands. Keep a copy of your /etc/modprobe.d directory; it's not very big. Maybe keep in your directory a narrative of what you did to get the sound working.
Be sure to know what all cards in alsamixer look like, and what all the tabs in pavucontrol look like.
Linux sound is much easier to both understand and troubleshoot when you know what a working system looks like. Give yourself that gift so your next troubleshoot will be easier.
Part 3 was originally created in December 2013. It addresses a Linux sound system that uses both ALSA and Pulseaudio. It's more complicated to troubleshoot because there are more moving parts and more potential mute points. Pulseaudio alone has many more mute points than ALSA.
Because I wrote Part 3 ten years ago, when I had less knowledge, you can expect Part 3 to have some inaccuracies, so use it more for ideas than for a troubleshooting road map.
This section gives the world's most oversimplified overview of Linux sound with ALSA plus Pulseaudio. In fact, I've never seen an accurate diagram of this type of system, because ALSA and Pulseaudio depend on each other. But for typical Linux ALSA/Pulseaudio sound problems, the oversimplification is good enough, and possibly just what you need:
In the preceding diagram, the farther left you move, the greater the level of abstraction. When you play a .wav file on mplayer, mplayer knows all about playing songs, handling playlists, going louder and softer or going backward or forward through the song, but it knows almost nothing about the system on which it operates. You can set it to interface with abstract sound interfaces, and in this case, you set it to interface with PulseAudio.
Pulseaudio handles sound streams very well. It can route sound streams hither and yon. Through its pavucontrol mixer, it can provide volume controls for every application playing through it. And it also provides volume controls for inputs like mikes and outputs like speakers, although it comes nowhere near to operating directly on mikes and speakers. Pulseaudio also has a nice Application Programming Interface so you can make your own computer programs interface with it.
NOTE:
Although the preceding diagram looks like Pulseaudio passes the sound to ALSA, their relationship is more complex. One indication of this is that when you increase a level in Pulseaudio, the corresponding ALSA level increases, and when you increase an ALSA level, the corresponding Pulseaudio level increases. In a way, you can think of Pulseaudio more as a controller of ALSA than a preprocessor to ALSA.
If you do think of Pulseaudio as more of an ALSA controller than a cascade step before it, then the following diagram is more accurate for the situation:
When evaluating which of the two diagrams to use (and there are probably other diagrams appropriate for various situations), keep in mind that some software outputs to ALSA, some to Pulseaudio, and some softare, like qmmp, lets you set it to output to either.
Anyway, ALSA outputs to the the sound card driver, and is the last hardware-independent part of the chain. It has less capability than Pulseaudio. For instance, it cannot provide individual volume controls for every stream going through it.
NOTE:
ALSA can be set to output to the old Linux sound system, oss, but today, it usually outputs to the driver.
ALSA has several excellent programs that aid in both adjustment and troubleshooting:
DANGER
Never do sound diagnosis wearing headphones. A sudden loud noise could cause deafness, possibly permanent.
Likewise, never diagnose sound problems with a high power sound system turned up loud, as this could also cause hearing problems, and a sudden impulse could cause electrical problems, possibly blowing the speakers or amp, or in extreme situations, perhaps cause a fire.
As mentioned in the Part 3 introduction, these tools were written ten years ago when I knew less. I personally wouldn't recommend you use them in 2023 and beyond, but I decided to leave it on this page to give you ideas.
As you know from my books, I'm a big fan of process in troubleshooting. But sometimes, the best way to start the process is with a quick predefined diagnostic likely to work. This is what the Steve Litt Diagnostic Tools help do. You can download them here.
There are two of these tools:
./unmute_all.sh
./find_all_mutes.sh
The way these tools work is you put them in a directory all by themselves, and run them within that directory. They are not meant to put on the path, and I don't recommend modifying them to put them on the path.
NOTE:
I've found out that these scripts won't find all sound cards on certain computers, so they might fail to unmute all mutes. So, if the one second ./unmute_all.sh doesn't restore the sound, run alsamixer, cycle through every sound card using the F6 key, and unmute every control with an "MM" at the bottom.
As mentioned in the Part 3 introduction, this script was written ten years ago when I knew less. I personally wouldn't recommend you use it in 2023 and beyond, but I decided to leave it on this page to give you ideas.
Troubleshooting Linux sound can consume horrendous amounts of time. Life's too short and precious for such time wasters: We need a better way, and this is it: Diagnostic tests based on likelihood and ease, combined with ./unmute_all.sh a shellscript that unmutes all ALSA mutes.
In my troubleshooting classes and books I teach the quadruple tradeoff to optimally choose the next diagnostic test:
I tell every class that you never perform unsafe diagnostic tests; if you can't make it safe, you don't do it at all. No using a 2 foot screwdriver pressed against your ear to listen to various engine parts for a hum. No tests on an Inter Continental Ballistic Missile while the nuclear warhead is attached. And no headphones while diagnosing computer sound problems!
Linux sound troubleshooting is so difficult and so time consuming that I've created a predefined diagnostic (a troubleshooting script) that hopefully will solve 90% of the problems in 10% of the time. The priority in designing this script was ease and likelihood, because with Linux sound, even divisions are difficult to understand, and as long as you're not using headphones or a powerful amp, I can't imagine an unsafe test. Here's the predefined diagnostic:
This script is built for speed on typical problems. Obviously, you start by checking whether it already works: No use messing up something that works. If it doesn't, the next step is to unmute all controls on all relevant sound cards, and please keep in mind that one physical sound card can have multiple virtual sound cards.
Just for quickness, you might try my ./unmute_all.sh shellscript to quickly turn off all ALSA mutes. But I've found out that ./unmute_all.sh doesn't find all virtual sound cards on certain computers, so if ./unmute_all.sh doesn't fix the problem, you'll need to run alsamixer, cycle through all sound cards using the F6 key, and turn off all mutes.
NOTE:
Personally, I think that mutes in Linux sound are the bain of my existence, due to the way they're implemented. Muting one control can mute several others, sometimes on other virtual sound cards, and unmuting it sometimes doesn't unmute those others, so you get a magical, seemingly unfixable sound problem. If you need to eliminate sound from your speakers, it's much better to set the master control to zero, and then when you need it again, turn it up again. You could even write a shellscript using amixer to get the master level, save it, turn it to zero, and restore it when you press enter. I leave that as an exercise for the reader.
NOTE FURTHER:
I've seen an old distro that, when you turn the volume down to zero, mutes the control. As far as I'm concerned, this misbehavior is perfect justification to get another distro.
I'd imagine ALSA mutes account for half of all sound problems, and some of the (formerly) most difficult ones, so taking this step now enables you to solve half the problems in three minutes or less. Then you just go right down the line. This predefined diagnostic won't solve all sound problems, but it will solve most of them, and do it quickly. Even those it doesn't solve will benefit from the results of the diagnostic tests.
The penny test is a test to test your speakers, from the plug that goes into your sound card right through the electronics and speaker drivers. Here's the penny test:
Unplug your speakers from the computer (but not from the wall), and rub an American penny or other copper coin along the side of the speaker plug. You should hear static clicks, and if you listen carefully, when the penny touches the tip or the metal adjacent to the tip, you'll hear a low volume buzz. If you don't hear any of these things, increase the volume, make sure the speakers are plugged into power and turned on, and try again. If you still don't hear it, your amplifier or speaker system is probably bad, so swap in a known good set of computer speakers.
NOTE:
The penny technique won't work on headphones (earphones), but to protect your hearing, you should never troubleshoot audio problems wearing earphones anyway.
When testing a sound system, I'd recommend this command:
speaker-test -c2 -t wav
The preceding command is a direct injection of sound into the ALSA system that, if all is working, should keep saying "front left" and "front right" in alternating speakers. This is much easier and more foolproof than playing a sound file with a sound playing executable, or using YouTube.
My ./unmute_all.sh is wonderful for the simplest of all reasons: The ./unmute_all.sh shellscript is wonderful for the simplest of all reasons: It might fix your problem in five seconds. If it doesn't, then, just for fun, take another five seconds to run ./find_all_mutes.sh to see if something obvious is happening (wrong card, for instance?).
You can see whether ALSA sees any sound cards with the following command:
aplay -l
NOTE:
The preceding command finds cards with outputs. If you're looking for cards with inputs (microphones, for instance), use this command:
arecord -l
Linux sound has evolved into a rather strange system. Pulseaudio doesn't just pass sound on to ALSA: Pulseaudio levels actually control ALSA levels and vice versa. If you can't find anything wrong using alsamixer, try pavucontrol, Pulseaudio's mixer application.
If no cards show up, or if the only card that shows up is a microphone-only, then that's what you have to fix.
The following hardware-scanning command shows whether any working sound cards exist:
lspci -v | grep -B1 -A12 -i audio
If you don't see evidence of the sound card in that output, your sound card is probably bad, or it's not a PCI soundcard (perhaps it's USB?). Unless you're sure it's a PCI soundcard, just to rule out the possibility of a non-PCI soundcard, execute this command:
sudo lshw | grep -B4 -A10 -i audio
The lshw is inferior to the lspci one because it's slower and requires root privileges, but it detects sound cards anywhere on the bus.
One thing that probably would not cause the sound card to fail to show in lspci or lshw commands would be a lack of drivers. I say this based on an experiment I did, in which I created file /etc/modules.d/blacklist-littsound.conf, to blacklist all the sound modules listed in lsmod. When I rebooted, lspci still showed the sound card. The computer wouldn't make sound, and lsmod showed no sound drivers, but lspci still showed the hardware.
So, although I'm not certain, I'm pretty sure that if your sound card doesn't show up in either lspci or lshw, that means either you have no sound card, the sound card is defective, or a motherboard sound card is disabled in the BIOS. So that's what you should start fixing.
If it shows up in lspci or lshw, and you've unmuted everything with the Steve Litt ./unmute_all.sh tool, it's probably either a zero level in ALSA, or a mute or zero in Pulsaudio (use pavucontrol to investigate), or it's a driver problem. Driver problems are a pain and a half, so look at alsamixer and pavucontrol to make sure there are no mutes or zero levels.