How to Configure a PipeWire Audio Output Switching Script on Debian

The simplest reliable way to switch PipeWire outputs from a script on Debian is to use wpctl, the WirePlumber command-line tool: identify the two sink nodes you care about, inspect the current default sink, and call wpctl set-default ID for the other one. This is preferable to hard-coding a numeric node ID because PipeWire object IDs can change when devices disconnect, reconnect, or the session restarts.

This guide uses a two-device toggle—for example, laptop speakers and Bluetooth headphones—and deliberately keeps the logic compatible with both current Debian 13 (Trixie) and Debian 12 (Bookworm). As of October 2026, Debian's package pages list WirePlumber 0.5.8 in Debian 13 and 0.4.13 in Debian 12. Newer WirePlumber releases provide additional listing features, but wpctl status -n, wpctl inspect, and wpctl set-default are the common denominator needed here.

When this method is a good fit

Use this approach when PipeWire is already handling desktop audio and you want a keyboard shortcut, launcher, shell alias, or hotkey to alternate between two outputs. It works well for a built-in analog output plus USB DAC, HDMI monitor, Bluetooth headset, or another sink that appears under the Sinks section of wpctl status.

It is not the right tool for every routing problem. wpctl set-default changes the default target used for streams that need automatic connection. It does not promise that every already-running application will immediately migrate an existing stream. Some applications follow the new default automatically; others may need their stream moved separately or the application restarted.

Before you write the script

Confirm that the user-level PipeWire and WirePlumber session is healthy. The official WirePlumber documentation recommends checking the daemon with systemctl --user status wireplumber. Debian also recommends the pipewire-audio metapackage on Debian 12 and newer when setting up a complete PipeWire audio stack.

systemctl --user status wireplumber
systemctl --user status pipewire pipewire-pulse

If wpctl is missing, install WirePlumber and the normal PipeWire audio components rather than trying to substitute an unrelated mixer utility:

sudo apt update
sudo apt install pipewire-audio wireplumber

Do not run wpctl with sudo. PipeWire and WirePlumber normally operate in your desktop user's session, so the command should connect to that user's media graph.

Step 1: Find the output sink names

Run:

wpctl status -n

The -n option asks wpctl to show object names instead of human-friendly descriptions. Under Audio → Sinks, note the names of the two outputs you want to toggle. A machine might show a built-in sink resembling alsa_output.pci-0000_00_1f.3.analog-stereo and a Bluetooth sink beginning with bluez_output..

Выберите фрагмент, достаточно уникальный, чтобы соответствовать только предполагаемому выходному сигналу. Для встроенной карты alsa_output...обычно целесообразно использовать полное имя узла. Для устройства Bluetooth более короткий bluez_output.фрагмент удобен только в том случае, если обычно подключен только один Bluetooth-приемник аудиосигнала. Если вы часто подключаете несколько Bluetooth-выходов, используйте более длинный фрагмент, уникальный для соответствующего устройства.

Шаг 2: Проверьте работоспособность раковины с помощью команды wpctl inspect.

Перед созданием скрипта для переключения проверьте один из идентификаторов, отображаемых wpctl status -n:

wpctl inspect 45

Замените 45на текущий идентификатор в вашей системе. Найдите такие свойства, как node.nameи media.class. Для вывода воспроизведения media.classдолжен указывать на аудиоприемник. Числовой идентификатор полезен для проверки и для немедленной set-defaultкоманды, но приведенный ниже скрипт каждый раз при запуске получает новый идентификатор.

Вы также можете спросить у WirePlumber, какой из раковин в данный момент является раковиной по умолчанию, не зная её числового идентификатора:

wpctl inspect @DEFAULT_AUDIO_SINK@

Специальный идентификатор @DEFAULT_AUDIO_SINK@документируется программой WirePlumber и во время выполнения преобразуется в текущий узел воспроизведения по умолчанию.

Шаг 3: Создайте скрипт переключения с двумя выходами.

При необходимости создайте личную директорию для запуска исполняемого файла, затем откройте скрипт:

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

Вставьте следующий код и замените SINK_Aего SINK_Bфрагментами из вашего собственного wpctl status -nвывода:

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

# Replace these with distinctive fragments from `wpctl status -n`.
SINK_A="alsa_output.pci-0000_00_1f.3.analog-stereo"
SINK_B="bluez_output."

find_sink_id() {
    local needle="$1"
    wpctl status -n | awk -v n="$needle" '
        /Sinks:/   { in_sinks=1; next }
        /Sources:/ { in_sinks=0 }
        in_sinks && index($0, n) {
            for (i=1; i<=NF; i++) {
                if ($i ~ /^[0-9]+\.$/) {
                    gsub(/\./, "", $i)
                    print $i
                    exit
                }
            }
        }'
}

current_name="$(
    wpctl inspect @DEFAULT_AUDIO_SINK@ |
    awk -F'= ' '/node.name/ {
        gsub(/"/, "", $2)
        print $2
        exit
    }'
)"

if [[ "$current_name" == *"$SINK_A"* ]]; then
    target_pattern="$SINK_B"
elif [[ "$current_name" == *"$SINK_B"* ]]; then
    target_pattern="$SINK_A"
else
    # If the current default is neither target, switch to A first.
    target_pattern="$SINK_A"
fi

target_id="$(find_sink_id "$target_pattern")"

if [[ -z "$target_id" ]]; then
    printf 'No available sink matched: %s\n' "$target_pattern" >&2
    exit 1
fi

wpctl set-default "$target_id"
printf 'Default audio sink changed to ID %s\n' "$target_id"

Почему скрипт каждый раз обрабатывает идентификаторы?

Идентификаторы объектов PipeWire являются объектами сессии, поэтому рассматривать такой идентификатор, как 45постоянный идентификатор устройства, ненадежно. Вместо этого скрипт хранит распознаваемые фрагменты имен узлов, анализирует текущий раздел Sinks и извлекает числовой идентификатор только в момент переключения.

Почему в качестве параметра по умолчанию используется wpctl inspect?

Скрипт запрашивает @DEFAULT_AUDIO_SINK@его имя node.name. Это позволяет избежать зависимости от визуального расположения звездочки в wpctl statusпри определении того, какой из раковин в данный момент выбран. Затем он сравнивает это имя с SINK_Aи SINK_B.

Шаг 4: Сделайте скрипт исполняемым и протестируйте его.

Сохраните файл, затем запустите:

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

Если целевой приемник доступен, скрипт должен вывести выбранный им идентификатор. Запустите его снова, и он должен выбрать другой настроенный приемник. Подтвердите результат с помощью wpctl status -nили проверив файл @DEFAULT_AUDIO_SINK@.

В документации WirePlumber wpctl set-default IDуказано, что в качестве целевого объекта по умолчанию устанавливается источник или приемник. В современных версиях WirePlumber этот выбор пользователя запоминается и может иметь более высокий приоритет, чем автоматический выбор на основе приоритета. Если позже вы захотите, чтобы WirePlumber вернулся к автоматическому выбору по умолчанию, используйте:

wpctl clear-default

Добавьте скрипт в сочетание клавиш.

После того, как проверка терминала станет надежной, назначьте /home/YOUR_USER/.local/bin/toggle-audio-outputсочетание клавиш на рабочем столе. Используйте абсолютный путь, а не путь напрямую, ~поскольку некоторые программы запуска сочетаний клавиш не разворачивают сокращенные обозначения оболочки. Точный интерфейс сочетаний клавиш зависит от среды рабочего стола, поэтому важно сначала убедиться, что скрипт корректно работает в обычном пользовательском терминале.

Если ярлык запускается, но wpctlсообщает о невозможности подключения, возможно, средство запуска не наследует ожидаемую среду пользовательской сессии. Проверьте ту же команду в терминале внутри графической сессии, а затем просмотрите правила выполнения ярлыков в среде рабочего стола. Не решайте эту проблему, добавляя префикс к скрипту sudo.

Устранение распространенных неисправностей

«Подходящей раковины нет в наличии»

Вероятно, целевой объект отключен, изменилось имя его узла или ваш шаблон слишком специфичен. Запустите скрипт wpctl status -nснова и обновите соответствующее SINK_Aзначение SINK_B. Для Bluetooth убедитесь, что гарнитура подключена и имеет доступ к аудиоприемнику, прежде чем запускать скрипт.

Скрипт переключает режим воспроизведения по умолчанию, но существующий звук продолжает воспроизводиться в другом месте.

Это может быть нормальным явлением. В документации разработчика описывается set-defaultвыбор целевого устройства для новых потоков, требующих автоматического подключения. Если существующий поток конкретного приложения остается на старом приемнике, остановите и перезапустите воспроизведение или откройте приложение заново. Если вам необходимо перенести существующие потоки, рассматривайте это как отдельную задачу маршрутизации, а не предполагайте, set-defaultчто это гарантировано.

Выбрано неправильное Bluetooth-устройство.

Уточните SINK_B. Общий шаблон, например, bluez_output.подходит только при наличии одного соответствующего Bluetooth-приемника. Используйте полное имя узла или уникальный промежуточный фрагмент, если можно подключить одновременно несколько беспроводных выходов.

Программа WirePlumber не запущена.

Проверять:

systemctl --user status wireplumber
journalctl --user -u wireplumber

В документации разработчика рекомендуется учитывать systemctl --user --now enable wireplumberслучай, когда демон установлен, но не включен. На уже настроенном рабочем столе Debian следует выяснить причину остановки службы пользователя, прежде чем многократно перезапускать весь аудиостек.

Debian 12 против Debian 13: какие изменения?

Не копируйте примеры конфигурации WirePlumber 0.5 вслепую в более старую установку 0.4. В WirePlumber 0.5 изменилась система конфигурации; в этом руководстве обходится это ограничение по версии за счет использования операций командной строки вместо постоянных файлов политик.

Краткий контрольный список для проверки

• systemctl --user status wireplumberпоказывает работающий менеджер сессий.
• wpctl status -nВ разделе «Приемники» указаны оба предполагаемых выхода.
• wpctl inspect @DEFAULT_AUDIO_SINK@Возвращает действительный текущий узел воспроизведения.
• Два варианта написания текста однозначно идентифицируют предназначенные для них раковины.
• При двукратном запуске скрипта попеременно отображаются два варианта вывода по умолчанию.
• Если существующее приложение не перемещается, вы понимаете, что выбор по умолчанию и миграция с использованием активного потока — это разные процессы.

Основные источники

Для получения информации о семантике команд и текущем поведении WirePlumber см. официальное руководство по wpctl в WirePlumber и официальное руководство по началу работы с WirePlumber . Для получения информации о пакетах и ​​настройке, специфичных для Debian, используйте документацию PipeWire в Debian , страницу пакета WirePlumber в Debian 12 и страницу пакета WirePlumber в Debian 13 .