lenovo-gentoo/scripts/audio-setup/README.md

# 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