Media Operations Manual

Audio/video-related operations, including PipeWire management, volume control, device routing, recording, and troubleshooting.

Architecture Overview

Key Concepts:

PipeWire = Unified audio/video service, replacing both PulseAudio and JACK
WirePlumber = Device hot-plug/auto-routing policy (e.g., when headphones are plugged in or HDMI output is switched)
pipewire-pulse = PulseAudio compatibility layer, allowing PA apps to use PipeWire transparently
pactl operates pipewire-pulse, wpctl operates the native PipeWire layer

Status Checks

# Service status
systemctl --user status pipewire wireplumber pipewire-pulse

# PipeWire native info
pw-cli info                          # PipeWire service summary
pw-dump                              # Full dump (nodes/ports/links)
pw-top                               # Real-time performance monitoring (similar to htop)
pw-cli list-objects                  # List all objects

# WirePlumber devices
wpctl status                         # Device overview (sinks/sources/default devices)
wpctl inspect <id>                   # View details of a specific device/node

# PulseAudio compatibility layer
pactl info                           # PulseAudio service info
pactl list sinks                     # List all audio outputs
pactl list sources                   # List all audio inputs (including monitors)
pactl list cards                     # Sound card info (profile/ports)
pactl list sink-inputs               # Currently playing audio streams
pactl list modules                   # Loaded modules

# Hardware
aplay -l                             # List ALSA playback devices
arecord -l                           # List ALSA recording devices
lspci | grep -i audio                # PCI audio devices
cat /proc/asound/cards               # Sound cards from kernel perspective

Volume Control

# wpctl (Recommended, native PipeWire)
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+      # Default output +5%
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-      # Default output -5%
wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.5      # Set to 50%
wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle     # Toggle mute
wpctl set-volume <sink-id> 0.75                # Set specific sink to 75%

# pactl (PulseAudio compatibility layer)
pactl set-sink-volume @DEFAULT_SINK@ +5%
pactl set-sink-volume @DEFAULT_SINK@ 50%
pactl set-sink-mute @DEFAULT_SINK@ toggle

# amixer (ALSA low-level, direct hardware control)
amixer scontrols                      # List simple mixer controls
amixer sget Master                    # View Master volume
amixer sset Master 80%                # Set Master to 80%
amixer sset Master 5%+                # Master +5%
amixer sset Master toggle             # Toggle mute
amixer sset Headphone 70%

Audio Routing (Switch Output Device)

# List available sinks and switch
wpctl status                          # Note the target sink ID
wpctl set-default <sink-id>           # Set as default output
wpctl inspect <sink-id>               # Confirm switch took effect

# Migrate currently playing stream to a specific sink
pactl list sink-inputs                # Note the sink-input ID
pactl move-sink-input <input-id> <sink-id>

# Switch to a specific device (by name)
SINK=$(pactl list sinks short | grep -i "hdmi\|analog\|usb" | head -1 | awk '{print $1}')
pactl set-default-sink "$SINK"

# View sound card profiles (analog/digital/HDMI switching)
pactl list cards
pactl set-card-profile <card-name> output:analog-stereo
pactl set-card-profile <card-name> output:hdmi-stereo
pactl set-card-profile <card-name> output:iec958-stereo  # SPDIF

Restarting WirePlumber / PipeWire

# Restart the entire audio stack (soft restart, apps won't notice)
systemctl --user restart pipewire pipewire-pulse wireplumber

# Restart WirePlumber alone (refreshes device list)
systemctl --user restart wireplumber

# Full reset (kill then start)
systemctl --user stop pipewire pipewire-pulse wireplumber
sleep 1
systemctl --user start pipewire wireplumber pipewire-pulse

Troubleshooting

# 1. Check if there is any audio output
paplay /usr/share/sounds/alsa/Front_Center.wav    # Test tone
speaker-test -t sine -f 440 -l 1                   # 440Hz sine wave (bypasses PA/PW)

# 2. Check if pipewire-pulse is frozen (common: Chrome video freezes)
pactl info 2>&1                                    # Check for errors/timeouts
paplay /usr/share/sounds/alsa/Front_Center.wav     # If exit code is 124, pipewire-pulse is frozen
# Fix: systemctl --user restart pipewire-pulse

# 3. Check if any process is exclusively locking the sound card
fuser /dev/snd/*                                   # Who is using audio devices
lsof /dev/snd/*                                    # More detailed view

# 4. Check if ALSA layer is working normally
aplay -D hw:0,0 /usr/share/sounds/alsa/Front_Center.wav  # Bypass PipeWire and play directly
speaker-test -D hw:0,0 -t sine -f 440 -l 1
# If ALSA plays fine but PipeWire has no sound → PipeWire layer issue
# If ALSA also reports errors → Driver/hardware issue

# 5. USB/HDMI hot-plug not responding
wpctl status                          # Check if device appears
systemctl --user restart wireplumber  # Force refresh device list
journalctl --user -u wireplumber -f   # Check WirePlumber logs

# 6. Bluetooth audio
bluetoothctl connect XX:XX:XX:XX:XX:XX
# After connecting, WirePlumber automatically creates a BT sink, visible via wpctl status
# If not appearing: systemctl --user restart wireplumber

# 7. Multiple simultaneous outputs (if needed)
pactl load-module module-combine-sink   # Create a combined sink to output to all devices simultaneously
# Unload: pactl unload-module module-combine-sink

Common Symptoms Quick Reference

Symptom	Possible Cause	Command
Chrome video progress bar stuck, buffering	pipewire-pulse frozen	`systemctl --user restart pipewire-pulse`
No sound at all	Wrong default sink	`wpctl status` to check default sink
Headphones not auto-switching	WirePlumber didn't react	`systemctl --user restart wireplumber`
Some apps play sound, others don't	Different sinks used	`pactl list sink-inputs` to check routing
Bluetooth headset connected but no sound	BT profile dropped	`pactl list cards` to check profile

Recording

# Screen recording (PipeWire + wf-recorder, native Wayland)
wf-recorder -f output.mp4                    # Record full screen
wf-recorder -g "$(slurp)" -f output.mp4      # Record selected area
wf-recorder --audio -f output.mp4            # With audio (requires pipewire)
wf-recorder --audio=HDMI -f output.mp4       # Specify audio source

# Audio recording (PipeWire)
pw-record output.wav                          # Record from default input device
pw-record --target=<node-id> output.wav       # Specify input source

# PulseAudio compatibility
parecord output.wav                           # Record from default mic
parecord --device=<source> output.wav         # Specify input source
parec --device=<sink>.monitor output.wav      # Record system output (loopback)

# Screenshots (Wayland/Hyprland)
grim screenshot.png                           # Full screen screenshot
grim -g "$(slurp)" screenshot.png             # Selected area screenshot
grim - | wl-copy                              # Screenshot to clipboard

Volume/Media Keys

Hyprland media key binding example (hyprland.lua):

-- Volume control (wpctl)
hl.dsp.bind({"SUPER"}, "XF86AudioRaiseVolume",  function() hl.exec("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+") end)
hl.dsp.bind({"SUPER"}, "XF86AudioLowerVolume",  function() hl.exec("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-") end)
hl.dsp.bind({"SUPER"}, "XF86AudioMute",         function() hl.exec("wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle") end)
hl.dsp.bind({"SUPER"}, "XF86AudioMicMute",      function() hl.exec("wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle") end)

-- Playback control (playerctl, requires installation)
hl.dsp.bind({}, "XF86AudioPlay",  function() hl.exec("playerctl play-pause") end)
hl.dsp.bind({}, "XF86AudioNext",  function() hl.exec("playerctl next") end)
hl.dsp.bind({}, "XF86AudioPrev",  function() hl.exec("playerctl previous") end)

Other playerctl usages:

playerctl play-pause                  # Control current player
playerctl -p spotify next             # Specify player
playerctl -a play-pause               # All players
playerctl -l                          # List controllable players
playerctl metadata                    # Current song info
playerctl metadata --format '{{artist}} - {{title}}'

Video/Codec Information

ffprobe video.mp4                     # Full video info
ffprobe -v quiet -show_streams video.mp4 | grep codec  # Only codecs
ffprobe -v quiet -show_entries stream=codec_name,width,height video.mp4

# Check hardware codec support
vainfo                                # VA-API (Intel/AMD)
vulkaninfo | grep -i video            # Vulkan Video extension
ffmpeg -encoders | grep vaapi         # Available VA-API encoders

Firmware

# AMD GPU firmware (codec/display)
ls /lib/firmware/amdgpu/              # gc_*, psp_*, sdma_*, vcn_*, etc.
dmesg | grep -i "firmware\|amdgpu"    # Firmware loading logs

# SOF (Sound Open Firmware, Intel audio DSP)
dmesg | grep -i sof
ls /lib/firmware/intel/sof/