Skip to content

Commit b899da0

Browse files
ctsdownloadsctsdownloads
authored
Update and rename readme to readme.md
Linux Audio Diagnostic Script Update and rename readme to readme.md
1 parent 31dea5f commit b899da0

File tree

2 files changed

+241
-1
lines changed

2 files changed

+241
-1
lines changed

‎misc/audio-diagnostic/readme‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎misc/audio-diagnostic/readme.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# 🔊 Linux Audio Diagnostic Script
2+
3+
A comprehensive, read-only diagnostic tool for troubleshooting Linux audio issues across PipeWire, PulseAudio, and ALSA configurations.
4+
5+
## ✨ Features
6+
7+
- **Universal compatibility**: Works with PipeWire (WirePlumber/Media Session), PulseAudio, and ALSA
8+
- **Distro-agnostic**: Supports Ubuntu, Fedora, Debian, Arch, and other major distributions
9+
- **Non-invasive**: Read-only operations, makes no system changes
10+
- **Comprehensive checks**: Services, devices, routing, profiles, and recent logs
11+
- **Smart detection**: Identifies common issues like dummy outputs, suspended nodes, and disabled profiles
12+
- **Test capability**: Optional audio playback test to verify output
13+
14+
## 📋 Requirements
15+
16+
### Core Requirements
17+
- Linux system with systemd
18+
- One of: PipeWire, PulseAudio, or ALSA
19+
20+
### Optional Tools (auto-detected)
21+
- `wpctl` - PipeWire control (for PipeWire systems)
22+
- `pactl` - PulseAudio control
23+
- `aplay` - ALSA utilities
24+
- `journalctl` - System log access
25+
26+
## 🚀 Quick Start
27+
28+
### One-line Install & Run
29+
30+
```bash
31+
curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/misc/audio-diagnostic/audio-diagnostic.sh -o audio-diagnostic.sh && chmod +x audio-diagnostic.sh && bash audio-diagnostic.sh
32+
```
33+
34+
### Step-by-Step
35+
36+
```bash
37+
# Download the script
38+
curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/misc/audio-diagnostic/audio-diagnostic.sh -o audio-diagnostic.sh
39+
40+
# Make it executable
41+
chmod +x audio-diagnostic.sh
42+
43+
# Run basic diagnostic
44+
./audio-diagnostic.sh
45+
46+
# Run with audio test
47+
./audio-diagnostic.sh -t
48+
49+
# Check recent issues (last 2 hours)
50+
./audio-diagnostic.sh --since "2 hours ago"
51+
```
52+
53+
## 📖 Usage
54+
55+
```bash
56+
./audio-diagnostic.sh [OPTIONS]
57+
```
58+
59+
### Options
60+
61+
| Option | Description | Example |
62+
|--------|-------------|---------|
63+
| `-t`, `--test` | Play a test sound after diagnostics | `./audio-diagnostic.sh -t` |
64+
| `--since <time>` | Set journal time window (default: 45 minutes ago) | `./audio-diagnostic.sh --since "2 hours ago"` |
65+
| `-v`, `--verbose` | Show detailed log entries | `./audio-diagnostic.sh -v` |
66+
| `-h`, `--help` | Display help message | `./audio-diagnostic.sh -h` |
67+
68+
### Time Window Examples
69+
70+
```bash
71+
# Check logs from last 10 minutes
72+
./audio-diagnostic.sh --since "10 minutes ago"
73+
74+
# Check all of today's logs
75+
./audio-diagnostic.sh --since "today"
76+
77+
# Check since specific time
78+
./audio-diagnostic.sh --since "2024-01-15 14:00:00"
79+
80+
# Use environment variable
81+
SINCE="1 hour ago" ./audio-diagnostic.sh
82+
```
83+
84+
## 📊 What It Checks
85+
86+
### 1. Core Audio Services
87+
- PipeWire/WirePlumber status
88+
- PulseAudio daemon status
89+
- Service health and activity
90+
91+
### 2. Default Devices & Routing
92+
- Current default output (sink)
93+
- Current default input (source)
94+
- Device routing (HDMI, Bluetooth, USB, built-in)
95+
- Dummy device detection
96+
97+
### 3. Available Audio Devices
98+
- All audio sinks (outputs)
99+
- All audio sources (inputs)
100+
- Sound card profiles
101+
- Device states and volumes
102+
103+
### 4. System-Specific Checks
104+
- Suspended audio nodes (PipeWire)
105+
- User audio group membership (Ubuntu/Debian)
106+
- ALSA card detection
107+
- TiMidity interference (Ubuntu)
108+
109+
### 5. Recent System Logs
110+
- Service lifecycle events (starts/stops/restarts)
111+
- Error messages and warnings
112+
- Bluetooth audio issues
113+
- Dummy output fallbacks
114+
115+
### 6. Optional Audio Test
116+
- Plays system sound through default output
117+
- Verifies audio pipeline functionality
118+
119+
## 🔍 Understanding the Output
120+
121+
### Status Indicators
122+
123+
- ✅ **Green checkmarks**: Everything working correctly
124+
- ⚠️ **Yellow warnings**: Potential issues that may need attention
125+
- ❌ **Red X marks**: Critical problems requiring fixes
126+
- ℹ️ **Info icons**: Important routing information
127+
- 🔊 **Dim text**: Additional details and suggestions
128+
129+
### Common Issues Detected
130+
131+
| Issue | What It Means | Typical Fix |
132+
|-------|---------------|-------------|
133+
| **Dummy output** | No real audio device available | Restart audio service, check drivers |
134+
| **Profile OFF** | Sound card disabled | Set profile in Settings → Sound |
135+
| **Service inactive** | Audio daemon not running | `systemctl --user restart pipewire` |
136+
| **Suspended nodes** | Devices in power-save state | Restart WirePlumber |
137+
| **Bluetooth errors** | BT audio connection issues | Re-pair device, restart bluetooth |
138+
| **No default sink** | No output device selected | Select device in Settings → Sound |
139+
140+
## 💡 Example Outputs
141+
142+
### Healthy System
143+
```
144+
✅ PipeWire core: active (systemd)
145+
✅ WirePlumber session: active (systemd)
146+
✅ Default Output: alsa_output.pci-0000_00_1f.3.analog-stereo (ID: 47)
147+
✅ Default Input: alsa_input.pci-0000_00_1f.3.analog-stereo (ID: 48)
148+
✅ No service events or errors in recent logs
149+
✅ No critical issues detected - audio system appears healthy
150+
```
151+
152+
### Problem System
153+
```
154+
❌ WirePlumber session: inactive
155+
❌ Default output is dummy device. Expect silence.
156+
⚠️ One or more audio devices have profile OFF
157+
❌ Found 12 concerning entries in wireplumber logs
158+
```
159+
160+
## 🛠️ Troubleshooting
161+
162+
### No Audio Output?
163+
164+
1. Run the diagnostic:
165+
```bash
166+
./audio-diagnostic.sh
167+
```
168+
169+
2. Follow the suggested fixes in the "Conclusions" section
170+
171+
3. Test audio after fixes:
172+
```bash
173+
./audio-diagnostic.sh -t
174+
```
175+
176+
### Script Not Working?
177+
178+
Check dependencies:
179+
```bash
180+
# For PipeWire systems
181+
which wpctl pw-cli
182+
183+
# For PulseAudio systems
184+
which pactl
185+
186+
# For ALSA
187+
which aplay
188+
```
189+
190+
### Need More Detail?
191+
192+
Run in verbose mode:
193+
```bash
194+
./audio-diagnostic.sh -v --since "1 hour ago"
195+
```
196+
197+
## 🤝 Contributing
198+
199+
Contributions are welcome! Please feel free to submit a Pull Request.
200+
201+
### Testing on Different Systems
202+
203+
Before submitting changes, please test on:
204+
- [ ] Ubuntu/Debian with PulseAudio
205+
- [ ] Fedora with PipeWire
206+
- [ ] Arch with PipeWire
207+
- [ ] System with Bluetooth audio
208+
- [ ] System with USB audio
209+
- [ ] System with HDMI audio
210+
211+
## 📜 License
212+
213+
GPL-3.0-1 License - [See LICENSE file for details](https://github.com/FrameworkComputer/linux-docs/tree/main?tab=GPL-3.0-1-ov-file#readme)
214+
215+
## 🐛 Known Issues
216+
217+
- Journal time window may include system-wide logs when user logs are empty
218+
- Some device names may be truncated in PipeWire listings
219+
- Bluetooth device detection relies on device naming patterns
220+
221+
222+
## ❓ FAQ
223+
224+
**Q: Is it safe to run this script?**
225+
A: Yes, the script is completely read-only and makes no system modifications.
226+
227+
**Q: Why do I see "dummy output"?**
228+
A: This means your audio system couldn't find real hardware. Usually fixed by restarting the audio service or installing missing drivers.
229+
230+
**Q: Can I run this via SSH?**
231+
A: Yes, but the audio test (-t) won't produce sound remotely. Diagnostics will still work.
232+
233+
**Q: How often should I run this?**
234+
A: Only when experiencing audio issues. It's a diagnostic tool, not a monitoring service.
235+
236+
**Q: Does this work with Bluetooth headphones?**
237+
A: Yes, it detects and reports Bluetooth audio devices and related issues.
238+
239+
---
240+
241+
*For issues or questions, please open a GitHub issue.*

0 commit comments

Comments
 (0)