Build a PipeWire Output Toggle Script That Moves Active Audio

For a small Debian audio toggle, use pactl through PipeWire’s PulseAudio-compatible server. The script below switches between two named outputs, sets the new default, and moves playback streams that are already open. Replace the sample sink names with the exact names shown on your machine.

1. Confirm the PipeWire Pulse server and find your outputs

PipeWire’s pipewire-pulse component provides a PulseAudio-compatible server, so standard tools such as pactl can control its sinks (audio outputs). Check which server your client reaches and list the available sinks:

pactl info | grep -E 'Server Name|Server Version'
pactl list short sinks

For this procedure, the server name should mention PipeWire. The sink list contains symbolic names such as alsa_output.pci-0000_00_1f.3.analog-stereo. Copy two names exactly: one for each output you want to toggle between. These names are specific to the connected hardware and audio profile; do not copy names from the example or use a numeric sink index, which can change during a session.

If pactl is missing, Debian provides it in pulseaudio-utils. Install that client package only if needed. If pactl info cannot connect or reports a different sound server, first confirm that PipeWire’s PulseAudio replacement is running in your user session; do not install or switch audio servers blindly.

2. Create the toggle script

Create a per-user scripts directory and open a new file:

mkdir -p ~/.local/bin
nano ~/.local/bin/toggle-audio-output

Paste this script, replacing both values in SINK_A and SINK_B with the names you copied:

#!/usr/bin/env bash
set -euo pipefail

SINK_A='alsa_output.pci-0000_00_1f.3.analog-stereo'
SINK_B='alsa_output.usb-Generic_Headset-00.analog-stereo'

command -v pactl >/dev/null || { echo "pactl is missing" >&2; exit 1; }
server_name=$(pactl info | sed -n 's/^Server Name: //p')
case "$server_name" in
  *PipeWire*) ;;
  *) echo "pactl is not connected to PipeWire's Pulse server" >&2; exit 1 ;;
esac

sinks=$(pactl list short sinks | awk '{print $2}')
for sink in "$SINK_A" "$SINK_B"; do
  if ! grep -Fqx -- "$sink" <<< "$sinks"; then
    printf 'Sink not found: %s\n' "$sink" >&2
    exit 1
  fi
done

current=$(pactl get-default-sink)
if [[ "$current" == "$SINK_A" ]]; then
  target=$SINK_B
else
  target=$SINK_A
fi

pactl set-default-sink "$target"
while IFS= read -r input_id; do
  [[ -n "$input_id" ]] || continue
  pactl move-sink-input "$input_id" "$target"
done < <(pactl list short sink-inputs | awk '{print $1}')
printf 'Default output: %s\n' "$target"

The script checks that both outputs are present before changing anything. It chooses the other configured output when the current default is SINK_A; if the current default is another sink, it starts with SINK_A. The set-default-sink command affects new streams, while the loop uses move-sink-input to route existing playback streams too. If you only want future apps to use the new default, remove the while loop; already-playing streams will stay where they are. Run this script as the same logged-in desktop user that owns the PipeWire session. Do not use sudo, which can connect through a different user runtime and fail to control your desktop audio. These operations are documented in Debian’s pactl manual.

3. Save, run, and verify the switch

Save in Nano with Ctrl+O, press Enter, then exit with Ctrl+X. Mark the script executable and run it:

chmod +x ~/.local/bin/toggle-audio-output
~/.local/bin/toggle-audio-output

It should print the new default sink. Check the server’s current default and any active playback streams:

pactl get-default-sink
pactl list short sink-inputs

Run the script a second time to switch back. For a practical listening check, play a short audio sample while switching and confirm that it comes from the selected device. The exact device names and display behavior vary with hardware, Bluetooth connection state, and active audio profiles.

When the script does not switch audio

• “Sink not found”: run pactl list short sinks again. A disconnected headset or changed profile may have changed the sink name; update the matching variable.
• Cannot connect: check that the PipeWire user services are running and that pactl info identifies the PipeWire Pulse server. Debian’s pipewire-pulse package provides that replacement server, while pulseaudio-utils includes the pactl client.
• New audio moves but a current app does not: rerun the script while that stream is visible in pactl list short sink-inputs. Some applications reopen streams or keep their own device selection, so choose “Default” in that application if it remains pinned to an output.

PipeWire’s Protocol Pulse documentation explains why PulseAudio command-line clients can control PipeWire when pipewire-pulse is the active server. This script uses that compatibility layer; it does not configure hardware profiles or guarantee that a disconnected device will be available.