120 lines
5.2 KiB
Markdown
120 lines
5.2 KiB
Markdown
# Audio Switcher
|
||
|
||
Audio Switcher puts PipeWire inputs, outputs, volume controls, and Bluetooth
|
||
audio handoff in one compact Noctalia panel. Devices can be renamed or hidden,
|
||
multiple outputs can be grouped for simultaneous playback, and compositor
|
||
keybinds can cycle devices or connect a specific Bluetooth device by its
|
||
persistent number.
|
||
|
||
|
||
|
||
Add the **Audio Switcher** widget from Noctalia's bar editor. Left click opens
|
||
the panel, right click cycles through visible outputs, and middle click cycles
|
||
through visible inputs. Scrolling over it changes the output volume.
|
||
|
||
## Plugin
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| ID | `blackbartblues/audio-switcher` |
|
||
| Entries | Widget: `widget`; panel: `audio-switcher`; service: `service` |
|
||
|
||
## Requirements
|
||
|
||
Install `pactl`, `bluetoothctl`, and `sleep` on `PATH`. On Arch Linux they are
|
||
provided by the `libpulse`, `bluez-utils`, and `coreutils` packages respectively.
|
||
PipeWire's PulseAudio compatibility service and BlueZ must be running.
|
||
Output grouping also requires PulseAudio's or PipeWire Pulse's
|
||
`module-combine-sink`.
|
||
|
||
## Usage
|
||
|
||
Open the panel from a configured bar widget or run:
|
||
|
||
```sh
|
||
noctalia msg panel-toggle blackbartblues/audio-switcher:audio-switcher
|
||
```
|
||
|
||
The top sliders control the default output and input volume. Select **Outputs**
|
||
or **Inputs**, then choose **Use**. For a disconnected Bluetooth output the same
|
||
button connects it, waits for its PipeWire endpoint, makes it the default, and
|
||
moves current playback streams to it.
|
||
|
||
Use the pencil button to set a local display name, choose the device icon, and
|
||
change a Bluetooth keybind number. The number is assigned automatically after a
|
||
device connects successfully for the first time and can then be changed. Hidden
|
||
devices remain available in the panel but are skipped by cycling commands.
|
||
|
||
To play through multiple outputs at once, open **Outputs**, choose **Group
|
||
outputs**, select at least two available physical outputs, then choose **Create
|
||
group**. The combined output becomes the default and current playback streams
|
||
move to it. Use **Disband** on its row to remove it; if it is active, playback
|
||
moves to the first available member before removal.
|
||
|
||
Use the settings button in the panel header to open Noctalia's plugin settings.
|
||
|
||
## Settings
|
||
|
||
| Entry | Setting | Type | Default | Description |
|
||
| --- | --- | --- | --- | --- |
|
||
| Plugin | `show_percentage` | `bool` | `true` | Show the output volume beside the bar icon; disable it for an icon-only widget. |
|
||
| Plugin | `show_notification_on_switch` | `bool` | `true` | Show a notification when switching device. |
|
||
| Plugin | `show_actions_in_tooltip` | `bool` | `true` | Show actions in tooltip. |
|
||
| Plugin | `scroll_step` | `int` | `5` | Volume points changed by each wheel step over the bar widget (1–25). |
|
||
|
||
## IPC and keybinds
|
||
|
||
The background service exposes commands that can be used by any compositor:
|
||
|
||
```sh
|
||
# Next non-hidden output. Disconnected Bluetooth outputs are connected as needed.
|
||
noctalia msg plugin blackbartblues/audio-switcher:service all cycle-output
|
||
|
||
# Next non-hidden, currently available input.
|
||
noctalia msg plugin blackbartblues/audio-switcher:service all cycle-input
|
||
|
||
# Connect the Bluetooth device assigned to number 2 and use its output.
|
||
noctalia msg plugin blackbartblues/audio-switcher:service all connect 2
|
||
|
||
# Refresh device state.
|
||
noctalia msg plugin blackbartblues/audio-switcher:service all refresh
|
||
```
|
||
|
||
For example, Niri bindings can spawn the commands directly:
|
||
|
||
```kdl
|
||
Mod+F9 { spawn "noctalia" "msg" "plugin" "blackbartblues/audio-switcher:service" "all" "cycle-output"; }
|
||
Mod+F10 { spawn "noctalia" "msg" "plugin" "blackbartblues/audio-switcher:service" "all" "cycle-input"; }
|
||
Mod+1 { spawn "noctalia" "msg" "plugin" "blackbartblues/audio-switcher:service" "all" "connect" "1"; }
|
||
```
|
||
|
||
Equivalent Hyprland bindings:
|
||
|
||
```ini
|
||
bind = SUPER, F9, exec, noctalia msg plugin blackbartblues/audio-switcher:service all cycle-output
|
||
bind = SUPER, F10, exec, noctalia msg plugin blackbartblues/audio-switcher:service all cycle-input
|
||
bind = SUPER, 1, exec, noctalia msg plugin blackbartblues/audio-switcher:service all connect 1
|
||
```
|
||
|
||
## Notes
|
||
|
||
Preferences are written to `preferences.json` in Noctalia's data directory for
|
||
this plugin. They contain only aliases, hidden flags, remembered Bluetooth input
|
||
capabilities, MAC addresses, keybind numbers, and per-device icon choices.
|
||
|
||
Before connecting a requested Bluetooth audio device, Audio Switcher disconnects
|
||
other Bluetooth audio devices connected to this computer. It cannot disconnect
|
||
the target from another computer or phone; that device must release the target
|
||
first unless it supports multipoint connections.
|
||
|
||
Output groups are `module-combine-sink` instances owned by the running audio
|
||
server. Audio Switcher rediscovers its groups after the plugin service restarts,
|
||
but they disappear if PipeWire/PulseAudio restarts. Combining outputs may add
|
||
latency and resampling CPU cost, especially when the devices use different
|
||
clocks or sample rates.
|
||
|
||
The plugin does not access the network. Its service spawns only the declared
|
||
`pactl`, `bluetoothctl`, and `sleep` commands. The short sleep is used while
|
||
waiting for a newly connected Bluetooth endpoint to appear. The panel may also
|
||
invoke the local Noctalia executable to open the plugin settings page.
|