Cómo configurar un script de conmutación de salida de audio de PipeWire en Debian

La forma más sencilla y fiable de cambiar las salidas de PipeWire desde un script en Debian es usar wpctlla herramienta de línea de comandos WirePlumber: identifica los dos nodos de destino que te interesan, inspecciona el nodo de destino predeterminado actual y llama wpctl set-default IDa la herramienta para cambiar al otro. Esto es preferible a codificar un ID de nodo numérico, ya que los ID de objeto de PipeWire pueden cambiar cuando los dispositivos se desconectan, se vuelven a conectar o se reinicia la sesión.

Esta guía utiliza un interruptor de dos dispositivos (por ejemplo, altavoces de portátil y auriculares Bluetooth) y mantiene deliberadamente la lógica compatible con las versiones actuales de Debian 13 (Trixie) y Debian 12 (Bookworm). A partir de octubre de 2026, las páginas de paquetes de Debian listan WirePlumber 0.5.8 en Debian 13 y 0.4.13 en Debian 12. Las versiones más recientes de WirePlumber ofrecen funciones de listado adicionales, pero wpctl status -n, wpctl inspect, y wpctl set-defaultson el denominador común necesario aquí.

Cuando este método sea adecuado

Utilice este método cuando PipeWire ya esté gestionando el audio del escritorio y desee un acceso directo de teclado, un lanzador, un alias de shell o una tecla de acceso rápido para alternar entre dos salidas. Funciona bien para una salida analógica integrada más un DAC USB, un monitor HDMI, unos auriculares Bluetooth u otro receptor que aparezca en la sección Sinkswpctl status de .

No es la herramienta adecuada para todos los problemas de enrutamiento. wpctl set-defaultModifica el destino predeterminado para las transmisiones que requieren conexión automática. No garantiza que todas las aplicaciones en ejecución migren inmediatamente una transmisión existente. Algunas aplicaciones adoptan automáticamente la nueva configuración predeterminada; otras pueden necesitar que su transmisión se migre por separado o que se reinicie la aplicación.

Antes de escribir el guion

Confirme que la sesión de PipeWire y WirePlumber a nivel de usuario esté en buen estado. La documentación oficial de WirePlumber recomienda comprobar el demonio con systemctl --user status wireplumber. Debian también recomienda el pipewire-audiometapackage en Debian 12 y versiones posteriores al configurar una pila de audio PipeWire completa.

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

Si wpctlfalta, instale WirePlumber y los componentes de audio normales de PipeWire en lugar de intentar sustituirlos por una utilidad de mezclador no relacionada:

sudo apt update
sudo apt install pipewire-audio wireplumber

No ejecute wpctlcon sudo. PipeWire y WirePlumber normalmente operan en la sesión de su usuario de escritorio, por lo que el comando debe conectarse al gráfico de medios de ese usuario.

Paso 1: Encontrar los nombres de los sumideros de salida

Correr:

wpctl status -n

La -nopción solicita wpctlmostrar los nombres de los objetos en lugar de descripciones fáciles de entender. En Audio → Sinks , anote los nombres de las dos salidas que desea alternar. Una máquina podría mostrar un sink integrado similar a alsa_output.pci-0000_00_1f.3.analog-stereoy un sink Bluetooth que comience con bluez_output..

Elija un fragmento lo suficientemente distintivo como para coincidir únicamente con la salida deseada. Para una tarjeta integrada, el alsa_output...nombre completo del nodo suele ser una opción acertada. Para un dispositivo Bluetooth, un bluez_output.fragmento más corto solo es conveniente si normalmente tiene un único receptor de audio Bluetooth conectado. Si conecta con frecuencia varias salidas Bluetooth, utilice un fragmento más largo y exclusivo del dispositivo en cuestión.

Paso 2: Verifique un sumidero con wpctl inspect.

Antes de programar el interruptor, inspeccione uno de los ID que se muestran a continuación wpctl status -n:

wpctl inspect 45

Reemplazar 45con el ID actual de su sistema. Busque propiedades como node.namey media.class. Para una salida de reproducción, media.classdebería identificar un sumidero de audio. El ID numérico es útil para la inspección y para el set-defaultcomando inmediato, pero el script a continuación resuelve un ID nuevo cada vez que se ejecuta.

También puedes preguntarle a WirePlumber qué fregadero es el predeterminado actualmente sin conocer su ID numérico:

wpctl inspect @DEFAULT_AUDIO_SINK@

@DEFAULT_AUDIO_SINK@WirePlumber documenta el identificador especial , que se resuelve en tiempo de ejecución al nodo de reproducción predeterminado actual.

Paso 3: Crear un script de conmutación de dos salidas

Si es necesario, cree un directorio ejecutable personal y, a continuación, abra el script:

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

Pegue el siguiente código y reemplace SINK_Ay SINK_Bcon fragmentos de su propia wpctl status -nsalida:

#!/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"

Por qué el script resuelve los ID cada vez

Los ID de objeto de PipeWire son objetos de sesión, por lo que tratar un ID como 45un identificador de dispositivo permanente resulta poco fiable. En su lugar, el script almacena fragmentos reconocibles del nombre del nodo, analiza la sección Sinks actual y extrae el ID numérico solo en el momento del cambio.

Por qué utiliza wpctl inspect para la configuración predeterminada actual

El script solicita @DEFAULT_AUDIO_SINK@su node.name. Eso evita depender de la ubicación visual de un asterisco en wpctl statusal determinar qué fregadero está seleccionado actualmente. Luego compara ese nombre con SINK_Ay SINK_B.

Paso 4: Haz que el script sea ejecutable y pruébalo.

Guarda el archivo y luego ejecuta:

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

Si el sumidero de destino está disponible, el script debería imprimir el ID que seleccionó. Ejecútelo de nuevo y debería elegir el otro sumidero configurado. Confirme el resultado con wpctl status -no inspeccionando @DEFAULT_AUDIO_SINK@.

WirePlumber documenta wpctl set-default IDla configuración de un sumidero o fuente como destino predeterminado. En la versión moderna de WirePlumber, esta selección del usuario se recuerda y puede tener mayor prioridad que la selección automática basada en prioridades. Si posteriormente desea que WirePlumber vuelva a la selección automática predeterminada, utilice:

wpctl clear-default

Agrega el script a un atajo de teclado.

Una vez que la prueba en la terminal sea fiable, asigne /home/YOUR_USER/.local/bin/toggle-audio-outputun atajo de teclado al escritorio. Utilice la ruta absoluta en lugar de la ruta completa ~, ya que algunos lanzadores de atajos no expanden la sintaxis abreviada del intérprete de comandos. La interfaz de usuario del atajo depende del entorno de escritorio, por lo que la prueba importante consiste en comprobar primero que el script funciona correctamente desde una terminal de usuario normal.

Si un acceso directo se ejecuta pero wpctlinforma que no puede conectarse, es posible que el lanzador no esté heredando el entorno de sesión de usuario esperado. Verifique el mismo comando desde una terminal dentro de la sesión gráfica y luego revise las reglas de ejecución de accesos directos del entorno de escritorio. No solucione ese problema anteponiendo el script con sudo.

Solución de problemas comunes

“No hay fregaderos disponibles que coincidan”

Es probable que el dispositivo esté desconectado, que su nombre de nodo haya cambiado o que el patrón sea demasiado específico. Vuelva a ejecutar el script wpctl status -ny actualice el valor correspondiente SINK_A. SINK_BPara Bluetooth, confirme que los auriculares estén conectados y que hayan expuesto un receptor de audio antes de ejecutar el script.

El script cambia el audio predeterminado, pero el audio existente sigue reproduciéndose en otro lugar.

Esto puede ser normal. La documentación de origen describe set-defaultla selección del destino para nuevos flujos que requieren conexión automática. Si el flujo existente de una aplicación en particular permanece en el destino anterior, detenga y reinicie la reproducción o vuelva a abrir la aplicación. Si necesita migrar flujos existentes, considérelo como una tarea de enrutamiento independiente en lugar de darlo por set-defaultsentado.

Se ha seleccionado el dispositivo Bluetooth incorrecto.

Sea SINK_Bmás específico. Un patrón genérico como este bluez_output.solo es adecuado cuando hay un único receptor Bluetooth compatible. Use el nombre completo del nodo o un fragmento intermedio único cuando se puedan conectar varias salidas inalámbricas a la vez.

WirePlumber no está funcionando

Controlar:

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

La documentación oficial recomienda que, systemctl --user --now enable wireplumbercuando el demonio esté instalado pero no habilitado, en un escritorio Debian ya configurado, se investigue por qué se detuvo el servicio de usuario antes de reiniciar repetidamente toda la pila de audio.

Debian 12 frente a Debian 13: ¿qué cambios hay?

No copie sin más los ejemplos de configuración de WirePlumber 0.5 en una instalación anterior de la versión 0.4. WirePlumber 0.5 modificó su sistema de configuración; este tutorial evita esa limitación de versiones mediante el uso de comandos en lugar de archivos de configuración persistentes.

Lista de verificación rápida

• systemctl --user status wireplumbermuestra el gestor de sesiones en ejecución.
• wpctl status -nEn la sección "Sinfines" se enumeran ambas salidas previstas.
• wpctl inspect @DEFAULT_AUDIO_SINK@Devuelve un nodo de reproducción actual válido.
• Los dos patrones de script identifican de forma unívoca los sumideros previstos.
• Al ejecutar el script dos veces, se alterna la salida predeterminada entre las dos opciones.
• Si una aplicación existente no se traslada, debe entender que la selección predeterminada y la migración de flujo activo son comportamientos distintos.

Referencias primarias

Para obtener información sobre la semántica de los comandos y el comportamiento actual de WirePlumber, consulte el manual oficial de WirePlumber wpctl y la guía de inicio rápido oficial de WirePlumber . Para obtener información sobre paquetes y configuración específicos de Debian, consulte la documentación de PipeWire de Debian , la página del paquete WirePlumber de Debian 12 y la página del paquete WirePlumber de Debian 13 .