chore: initialize gentoo-setup documentation repository
Add comprehensive documentation for Lenovo ThinkPad Gentoo Linux setup including: - Complete system configuration guides (power, Bluetooth, WiFi, audio) - Hardware setup documentation (touchpad, touchscreen, DisplayLink) - Management scripts with ZSH completions - Kernel configuration (6.12.41-gentoo-x86_64) - Lid automation and monitor management - Battery conservation system - User guides and troubleshooting Repository includes .gitignore to exclude logs, temporary files, and secrets. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
291
scripts/audio-setup/README.md
Normal file
291
scripts/audio-setup/README.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# Audio Setup Tool
|
||||
|
||||
Easy audio input/output management for Gentoo using PulseAudio.
|
||||
|
||||
## Features
|
||||
|
||||
- 🔊 List all available output devices (speakers, headphones, HDMI, etc.)
|
||||
- 🎤 List all available input devices (microphones, line-in, etc.)
|
||||
- 🔄 Switch between audio outputs with a single command
|
||||
- 🔄 Switch between audio inputs with a single command
|
||||
- 🔉 Set volume levels (0-100%)
|
||||
- 🔇 Mute/unmute outputs and inputs
|
||||
- ✨ Color-coded output for better readability
|
||||
- ⚡ ZSH autocompletion support
|
||||
- 🎯 Automatically moves active streams to new devices
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# From the scripts folder
|
||||
cd scripts/audio-setup
|
||||
|
||||
# Install the main script
|
||||
sudo cp audio-setup /usr/local/bin/audio-setup
|
||||
sudo chmod +x /usr/local/bin/audio-setup
|
||||
|
||||
# Install ZSH autocompletion
|
||||
sudo mkdir -p /usr/local/share/zsh/site-functions
|
||||
sudo cp _audio-setup /usr/local/share/zsh/site-functions/_audio-setup
|
||||
|
||||
# Reload ZSH completions (or restart your shell)
|
||||
autoload -U compinit && compinit
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- `pactl` (from PulseAudio package)
|
||||
- PulseAudio server running
|
||||
- ZSH (for autocompletion)
|
||||
|
||||
## Usage
|
||||
|
||||
### Show current audio status
|
||||
```bash
|
||||
audio-setup
|
||||
# or
|
||||
audio-setup status
|
||||
```
|
||||
|
||||
Displays:
|
||||
- Current output device and volume
|
||||
- Current input device and volume
|
||||
- Mute status for both
|
||||
|
||||
### List available output devices
|
||||
```bash
|
||||
audio-setup list-outputs
|
||||
```
|
||||
|
||||
Shows all available audio output devices (speakers, headphones, HDMI, DisplayPort, etc.) with numbers for easy switching.
|
||||
|
||||
### List available input devices
|
||||
```bash
|
||||
audio-setup list-inputs
|
||||
```
|
||||
|
||||
Shows all available audio input devices (microphones, line-in, etc.) with numbers for easy switching.
|
||||
|
||||
### Switch output device
|
||||
```bash
|
||||
audio-setup output 2
|
||||
```
|
||||
|
||||
Switches to output device #2. The script will:
|
||||
- Set the device as the default output
|
||||
- Automatically move all currently playing audio to the new device
|
||||
- Show the updated audio status
|
||||
|
||||
**Example use cases**:
|
||||
- Switch from laptop speakers to HDMI when connecting external monitor
|
||||
- Switch from speakers to headphones
|
||||
- Switch between different audio interfaces
|
||||
|
||||
### Switch input device
|
||||
```bash
|
||||
audio-setup input 1
|
||||
```
|
||||
|
||||
Switches to input device #1. The script will:
|
||||
- Set the device as the default input
|
||||
- Automatically move all currently recording streams to the new device
|
||||
- Show the updated audio status
|
||||
|
||||
**Example use cases**:
|
||||
- Switch between built-in mic and external USB mic
|
||||
- Switch to headset microphone
|
||||
- Switch between different audio interfaces
|
||||
|
||||
### Set volume
|
||||
```bash
|
||||
audio-setup volume 75
|
||||
```
|
||||
|
||||
Sets the output volume to 75%. Valid range: 0-100.
|
||||
|
||||
### Mute/unmute output
|
||||
```bash
|
||||
audio-setup mute # Mute speakers/headphones
|
||||
audio-setup unmute # Unmute speakers/headphones
|
||||
```
|
||||
|
||||
### Mute/unmute input
|
||||
```bash
|
||||
audio-setup mute-input # Mute microphone
|
||||
audio-setup unmute-input # Unmute microphone
|
||||
```
|
||||
|
||||
### Get help
|
||||
```bash
|
||||
audio-setup help
|
||||
```
|
||||
|
||||
## ZSH Autocompletion
|
||||
|
||||
The completion script provides:
|
||||
- Tab completion for all commands
|
||||
- Tab completion for output device numbers with descriptions
|
||||
- Tab completion for input device numbers with descriptions
|
||||
- Tab completion for common volume levels
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
# Press TAB to see all commands
|
||||
audio-setup <TAB>
|
||||
|
||||
# Press TAB to see available output devices
|
||||
audio-setup output <TAB>
|
||||
|
||||
# Press TAB to see available input devices
|
||||
audio-setup input <TAB>
|
||||
|
||||
# Press TAB to see suggested volume levels
|
||||
audio-setup volume <TAB>
|
||||
```
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Switching to External Monitor Audio
|
||||
```bash
|
||||
# List outputs to find HDMI/DisplayPort device
|
||||
audio-setup list-outputs
|
||||
|
||||
# Switch to it (e.g., device #3)
|
||||
audio-setup output 3
|
||||
```
|
||||
|
||||
### Switching Between Microphones
|
||||
```bash
|
||||
# List inputs
|
||||
audio-setup list-inputs
|
||||
|
||||
# Switch to external USB mic (e.g., device #2)
|
||||
audio-setup input 2
|
||||
```
|
||||
|
||||
### Quick Status Check
|
||||
```bash
|
||||
# See what's currently active
|
||||
audio-setup
|
||||
```
|
||||
|
||||
### Setting Up for a Call
|
||||
```bash
|
||||
# Switch to headset microphone
|
||||
audio-setup input 2
|
||||
|
||||
# Switch to headset speakers
|
||||
audio-setup output 2
|
||||
|
||||
# Set comfortable volume
|
||||
audio-setup volume 60
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### PulseAudio not running
|
||||
```bash
|
||||
# Start PulseAudio
|
||||
pulseaudio --start
|
||||
|
||||
# Check if running
|
||||
pactl info
|
||||
```
|
||||
|
||||
### No audio devices showing up
|
||||
```bash
|
||||
# Check PulseAudio status
|
||||
pactl info
|
||||
|
||||
# List all sinks (outputs)
|
||||
pactl list short sinks
|
||||
|
||||
# List all sources (inputs)
|
||||
pactl list short sources
|
||||
|
||||
# Restart PulseAudio if needed
|
||||
pulseaudio --kill
|
||||
pulseaudio --start
|
||||
```
|
||||
|
||||
### Audio still coming from old device after switching
|
||||
The script automatically moves active streams, but if this fails:
|
||||
```bash
|
||||
# Check current streams
|
||||
pactl list short sink-inputs
|
||||
|
||||
# Manually move a stream (get STREAM_ID from above)
|
||||
pactl move-sink-input STREAM_ID SINK_NAME
|
||||
|
||||
# Or just restart the audio application
|
||||
```
|
||||
|
||||
### Device numbers changed
|
||||
Device numbers can change if devices are connected/disconnected. Always use `audio-setup list-outputs` or `audio-setup list-inputs` to see current numbering.
|
||||
|
||||
## Technical Details
|
||||
|
||||
### How It Works
|
||||
- Uses `pactl` (PulseAudio Control) for all audio operations
|
||||
- Queries PulseAudio for available sinks (outputs) and sources (inputs)
|
||||
- Sets default sink/source when switching
|
||||
- Automatically moves active audio streams to the new device
|
||||
- Filters out monitor sources (internal recording devices) from input list
|
||||
|
||||
### Stream Moving
|
||||
When you switch devices, the script automatically moves:
|
||||
- **Output streams**: Music, videos, games, notifications
|
||||
- **Input streams**: Active recordings, voice calls, streaming
|
||||
|
||||
This ensures seamless transitions without restarting applications.
|
||||
|
||||
### Device Persistence
|
||||
PulseAudio remembers per-application device preferences. If an app was using a specific device, it may try to use it again next time. Use `audio-setup` to override and set the system default.
|
||||
|
||||
## Integration with Waybar
|
||||
|
||||
The audio status can be displayed in waybar using the PulseAudio module. See the main project documentation for waybar configuration.
|
||||
|
||||
## Related Tools
|
||||
|
||||
- WiFi Setup: See `scripts/wifi-setup/` for WiFi management
|
||||
- Bluetooth Setup: See `scripts/bluetooth-setup/` for Bluetooth management
|
||||
|
||||
## Examples in Practice
|
||||
|
||||
### Work From Home Setup
|
||||
```bash
|
||||
# Morning: Use laptop speakers
|
||||
audio-setup output 1
|
||||
|
||||
# Join meeting: Switch to headset
|
||||
audio-setup input 2 # Headset mic
|
||||
audio-setup output 2 # Headset speakers
|
||||
|
||||
# End of day: Back to laptop
|
||||
audio-setup output 1
|
||||
```
|
||||
|
||||
### Gaming Setup
|
||||
```bash
|
||||
# Switch to gaming headset
|
||||
audio-setup input 2 # Headset mic for voice chat
|
||||
audio-setup output 2 # Headset for game audio
|
||||
audio-setup volume 80 # Comfortable level
|
||||
```
|
||||
|
||||
### Multi-Monitor Setup
|
||||
```bash
|
||||
# When connecting dock with DisplayPort audio
|
||||
audio-setup list-outputs
|
||||
audio-setup output 3 # Switch to monitor speakers
|
||||
|
||||
# When undocking
|
||||
audio-setup output 1 # Back to laptop speakers
|
||||
```
|
||||
|
||||
## Files in This Directory
|
||||
|
||||
- `audio-setup` - Main audio management script
|
||||
- `_audio-setup` - ZSH completion script
|
||||
- `README.md` - This documentation
|
||||
Reference in New Issue
Block a user