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

# 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

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

audio-setup list-outputs

Shows all available audio output devices (speakers, headphones, HDMI, DisplayPort, etc.) with numbers for easy switching.

List available input devices

audio-setup list-inputs

Shows all available audio input devices (microphones, line-in, etc.) with numbers for easy switching.

Switch output device

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

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

audio-setup volume 75

Sets the output volume to 75%. Valid range: 0-100.

Mute/unmute output

audio-setup mute      # Mute speakers/headphones
audio-setup unmute    # Unmute speakers/headphones

Mute/unmute input

audio-setup mute-input      # Mute microphone
audio-setup unmute-input    # Unmute microphone

Get help

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:

# 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

# 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

# List inputs
audio-setup list-inputs

# Switch to external USB mic (e.g., device #2)
audio-setup input 2

Quick Status Check

# See what's currently active
audio-setup

Setting Up for a Call

# 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

# Start PulseAudio
pulseaudio --start

# Check if running
pactl info

No audio devices showing up

# 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:

# 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

# 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

# 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

# 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