Audio and Video Operations Manual

For a PipeWire + WirePlumber desktop, locate the failure in application streams, policy, nodes or kernel hardware. wpctl, pactl and ALSA use different objects and IDs; numbers are neither interchangeable nor stable across restarts.

Task	Start here
No sound	Architecture and state
Audio stays on old output	Default target and existing streams
Record / capture / encode	Format and input source

Policy control is not a serial audio-data hop

The solid path is a PulseAudio-protocol playback example; native clients enter PipeWire directly. WirePlumber controls links/profiles/policy, not serial audio payloads. Bluetooth has its own BlueZ-backed path; this diagram shows ALSA hardware only.

Inspect the current desktop session first

# Inspect this user’s audio services
systemctl --user status pipewire pipewire-pulse wireplumber --no-pager

Run as the affected desktop user, not root’s user manager. Adjust unit names for the distribution.

# List actual device, node, and stream names
wpctl status -n

Record current sink/source IDs and names; re-read after restarts or reconnection.

# Identify the server handling the PulseAudio protocol
pactl info

Server Name/String should match the intended compatibility server. Resolve connection/session failures first.

Inspect the relevant object type

# List playback targets
pactl list short sinks

# List capture devices and output monitor sources
pactl list short sources

Names ending in .monitor usually represent output mixes rather than microphones.

# Inspect compatibility playback streams while audio is playing
pactl list short sink-inputs

Native PipeWire streams may not appear here. For an empty list, confirm active output and protocol.

# Inspect ALSA hardware playback devices
aplay -l

# Check sound-card enumeration at kernel level
cat /proc/asound/cards

Use when investigating hardware; Bluetooth devices are not diagnosed merely by absence from ALSA cards.

Check the server identity, target sink and active stream. The wpctl star indicates the default node, not that every existing stream uses it. ALSA enumeration does not prove correct profiles, mute state or application routing.

Change defaults and pinned streams separately

Preparing the visual

Volume and mute: choose independently

# Read current volume and mute for default playback
wpctl get-volume @DEFAULT_AUDIO_SINK@

# Increase by five percentage points, capped at 100%, when needed
wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ --limit 1.0

This is an additive change, not multiplication by 1.05. Recheck with get-volume; it does not fix routing.

# Explicitly unmute playback when desired
wpctl set-mute @DEFAULT_AUDIO_SINK@ 0

0 unmutes and 1 mutes. toggle suits hotkeys; explicit state is easier to reproduce during diagnosis.

# Mute capture only when you intend to disable the microphone
wpctl set-mute @DEFAULT_AUDIO_SOURCE@ 1

Input and output differ. This is not a required playback repair step. Use 0 to restore capture and verify application permissions/source.

Change the default target or move an existing stream

# Set the verified playback node as the default for new streams
wpctl set-default 42

Replace 42 with a current sink ID. Record the old target; re-query before restoring it. Check the star and start new playback afterward.

# Obtain the current ID of the active stream to move
pactl list short sink-inputs

Match the application; this is not a wpctl sink ID.

# Move the chosen compatibility stream to an existing sink
pactl move-sink-input 73 YOUR_SINK_NAME

Use the current stream ID and a name from list short sinks. Re-list and listen; recreated streams may follow new policy.

Switch profiles only when the current one is unsuitable

# Inspect available card profiles and the active choice
pactl list cards

# Select an actually available profile from the list
pactl set-card-profile YOUR_CARD_NAME YOUR_PROFILE_NAME

Use both names from list cards and record the old profile. Switching can interrupt playback and replace IDs; recheck nodes/routing and use the old name to revert.

42 is a current wpctl sink; 73 a current pactl sink-input; the sink name comes from pactl. set-default targets new auto-connected streams; moving existing ones depends on policy, saved targets and applications. Move a specific compatible stream explicitly. Select only listed available profiles; telephony profiles change audio/capture capabilities.

Collect evidence at the failing layer before restart

Preserve evidence while the symptom occurs

# Inspect current-session service errors
journalctl --user -u pipewire -u pipewire-pulse -u wireplumber -b -n 150 --no-pager

# Observe node activity, errors, and processing time
pw-top

Keep the workload reproducing; watch growing ERR counts and affected nodes. Press q to exit. A single high value is not a diagnosis.

# Inspect properties of the current affected node
wpctl inspect 42

Reconfirm the ID and inspect node.name, device links, and media type.

# Inspect sink mute, port, state, and properties
pactl list sinks

# Inspect kernel/firmware errors when devices disappear
journalctl -k -b -n 100 --no-pager

Symptom	Next action
Only Dummy Output	Inspect enumeration, driver/firmware, permissions and policy logs
Sink and stream, no sound	Check target, stream/device mute, profile/port, ALSA mixer and cables
Stutter / crackling	Correlate pw-top errors/load before changing rates or quantum
Silent Bluetooth	Verify connection/profile in Bluetooth

Restart wireplumber when evidence warrants it, expanding to core/compatibility services only as needed. Active applications may reconnect. aplay -D hw can fail due to format or exclusivity; default speaker-test can traverse PipeWire. timeout exit 124 identifies elapsed time, not a daemon deadlock.

Choose the source, then verify container and codec

Recording: choose source, stop, then inspect

# Choose a microphone or output monitor by name
pactl list short sources

# Record WAV from the verified source
parecord --file-format=wav --device=YOUR_SOURCE_NAME recording.wav

Replace the source and choose an unused filename. This blocks until Ctrl-C; wait for the shell before inspection. Do not paste recording and postprocessing together.

# After recording, inspect duration, channels, rate, and codec
ffprobe -v error -show_format -show_streams -of json recording.wav

Confirm parsing and expected duration, then listen. Existence alone does not prove the correct source was recorded.

Transcoding: inspect input and local encoders first

# Inspect source streams, codecs, and duration
ffprobe -v error -show_format -show_streams -of json input.mp4

# Check required encoders are present in this build
ffmpeg -hide_banner -encoders

The example uses libx264 and aac. Hardware encoders also require compatible devices, drivers, and permissions.

# Transcode the first video and optional first audio to H.264/AAC
ffmpeg -n -i input.mp4 -map 0:v:0 -map "0:a:0?" \
  -c:v libx264 -crf 23 -c:a aac output.mp4

-n refuses overwrite; -map selects streams and ? permits missing audio. Lower CRF usually means higher quality/size. This does not retain every subtitle, attachment, or audio track.

# Verify output format/duration, then check playback
ffprobe -v error -show_format -show_streams -of json output.mp4

For remuxing consider -c copy after checking container compatibility and using a new output file; it is an alternative to re-encoding.

Stop recording with Ctrl-C. A monitor source captures its output mix; a normal source captures input. Raw parec output does not become WAV by renaming. The FFmpeg example requires those encoders; CRF 23 is not a universal quality guarantee. Stream copy still needs compatible containers; an encoder listing does not prove usable hardware.

Use the desktop-supported portal/recorder on Wayland. wf-recorder needs suitable screencopy support, not every compositor. Select actual audio source names, not the label HDMI. Bind wpctl and playerctl actions using the current desktop syntax. Resolve firmware failures from named missing files in kernel logs; see kernel.

WirePlumber wpctl · Linking policy · FFmpeg · wf-recorder