extension.js

// SPDX-FileCopyrightText: 2026 Mehmet Nuri Öztürk <info@mehmetnuri.net>
// SPDX-License-Identifier: GPL-3.0-or-later

/* Audio Output Switcher — GNOME Shell 42/43/44 (legacy imports API)
 *
 * A keyboard shortcut (default: Super+Alt+O) opens a centered "switcher" popup,
 * just like the Super+Space keyboard-layout switcher. While the shortcut's
 * modifier keys (Super+Alt) are held, pressing the shortcut again (or the arrow
 * keys) cycles through the devices; releasing the keys applies the selection.
 * There is NO panel icon.
 *
 * SAFETY: This does NOT create a custom full-screen modal overlay. It uses the
 * same SwitcherPopup mechanism as Alt+Tab / Super+Space. Esc cancels, clicking
 * outside dismisses, releasing the modifier selects, and if the modal grab
 * cannot be acquired it safely returns. It cannot lock up the screen.
 *
 * The switcher UI is modelled on GNOME Shell's own InputSourcePopup
 * (ui/status/keyboard.js — the Super+Space keyboard-layout switcher), built on
 * the public ui/switcherPopup.js API.
 *
 * The device list is built exactly like the GNOME Sound settings: the available
 * output devices (Gvc.MixerUIDevice) tracked via `output-added`/`output-removed`.
 * Unavailable ports (e.g. an HDMI/DP output with nothing plugged in) are hidden.
 */

const { Clutter, GObject, Gvc, Meta, Shell, St } = imports.gi;

const ExtensionUtils = imports.misc.extensionUtils;
const Main = imports.ui.main;
const SwitcherPopup = imports.ui.switcherPopup;

const _ = ExtensionUtils.gettext;

const SETTINGS_KEY_TOGGLE_SHORTCUT = 'toggle-shortcut';
const LOG_PREFIX = 'Audio Output Switcher';
const FALLBACK_ICON = 'audio-speakers-symbolic';

/**
 * Tracks and switches the available audio output devices.
 *
 * Creates its own Gvc.MixerControl instance so it can catch the `output-added`
 * signals from the moment it opens (the same approach the Settings window uses).
 */
class AudioOutputManager {
    constructor() {
        this._outputs = new Map(); // outputId -> Gvc.MixerUIDevice
        this._signalIds = [];

        this._control = new Gvc.MixerControl({ name: LOG_PREFIX });

        this._signalIds.push(
            this._control.connect('output-added', (_c, id) => this._onOutputAdded(id))
        );
        this._signalIds.push(
            this._control.connect('output-removed', (_c, id) => this._outputs.delete(id))
        );

        this._control.open();
    }

    _onOutputAdded(id) {
        const device = this._control.lookup_output_id(id);
        if (device)
            this._outputs.set(id, device);
    }

    isReady() {
        return this._control.get_state() === Gvc.MixerControlState.READY;
    }

    _activeSinkId() {
        const sink = this._control.get_default_sink();
        return sink ? sink.get_id() : -1;
    }

    /**
     * Returns the available output devices (same list as Settings).
     * @returns {Array<{id:number, label:string, active:boolean, iconName:string}>}
     */
    listOutputs() {
        if (!this.isReady())
            return [];

        const activeSinkId = this._activeSinkId();
        const items = [];
        const origins = new Set();

        for (const [id, device] of this._outputs) {
            const description = device.get_description() || '';
            const origin = device.get_origin() || '';
            const iconName = device.get_icon_name() || '';
            const streamId = device.get_stream_id();

            if (origin)
                origins.add(origin);
            items.push({
                id,
                description: description || _('Unknown output'),
                origin,
                iconName: iconName || FALLBACK_ICON,
                active: streamId !== -1 && streamId === activeSinkId,
            });
        }

        // If there is more than one card/origin, append the origin to keep the
        // labels distinguishable; with a single origin keep just the description.
        const showOrigin = origins.size > 1;
        for (const item of items) {
            item.label = showOrigin && item.origin
                ? `${item.description} — ${item.origin}`
                : item.description;
        }

        items.sort((a, b) => a.label.localeCompare(b.label));
        return items;
    }

    /** Makes the given output device the default output (the Settings method). */
    selectOutput(outputId) {
        if (!this.isReady())
            return;

        const device = this._outputs.get(outputId);
        if (!device)
            return;

        // change_output: default sink + port + profile. This is how GNOME Sound
        // settings changes the output device; no external tool (pactl) required.
        this._control.change_output(device);
    }

    destroy() {
        for (const id of this._signalIds)
            this._control.disconnect(id);
        this._signalIds = [];
        this._outputs.clear();
        this._control.close();
        this._control = null;
    }
}

function _mod(a, n) {
    return ((a % n) + n) % n;
}

/** Centered device visual (icon + name). Same widget class as the Alt+Tab list. */
const OutputSwitcherList = GObject.registerClass(
class OutputSwitcherList extends SwitcherPopup.SwitcherList {
    _init(items) {
        super._init(true);
        for (const item of items)
            this._addItem(item);
    }

    _addItem(item) {
        const box = new St.BoxLayout({
            vertical: true,
            style_class: 'alt-tab-app',
        });

        const icon = new St.Icon({
            icon_name: item.iconName || FALLBACK_ICON,
            icon_size: 48,
            x_align: Clutter.ActorAlign.CENTER,
        });
        box.add_child(icon);

        const label = new St.Label({
            text: item.label,
            x_align: Clutter.ActorAlign.CENTER,
        });
        box.add_child(label);

        this.addItem(box, label);
    }
});

/** Super+Space style output-device switcher (as safe as Alt+Tab). */
const OutputSwitcherPopup = GObject.registerClass(
class OutputSwitcherPopup extends SwitcherPopup.SwitcherPopup {
    _init(items, action, manager) {
        super._init(items);
        this._action = action;
        this._manager = manager;
        this._switcherList = new OutputSwitcherList(items);
    }

    // On open, pre-select the device AFTER the active one, so a quick press and
    // release switches to the other device (Alt+Tab logic). Esc cancels without
    // changing anything.
    _initialSelection(backward, _binding) {
        let activeIndex = this._items.findIndex(item => item.active);
        if (activeIndex < 0)
            activeIndex = 0;
        this._selectedIndex = activeIndex;
        if (this._items.length > 1)
            this._select(backward ? this._previous() : this._next());
        else
            this._select(activeIndex);
    }

    _keyPressHandler(keysym, action) {
        if (action === this._action)
            this._select(this._next());
        else if (keysym === Clutter.KEY_Right || keysym === Clutter.KEY_Down)
            this._select(this._next());
        else if (keysym === Clutter.KEY_Left || keysym === Clutter.KEY_Up)
            this._select(this._previous());
        else
            return Clutter.EVENT_PROPAGATE;

        return Clutter.EVENT_STOP;
    }

    _finish(timestamp) {
        super._finish(timestamp);
        const item = this._items[this._selectedIndex];
        if (item && this._manager)
            this._manager.selectOutput(item.id);
    }
});

class AudioOutputSwitcherExtension {
    constructor() {
        this._settings = null;
        this._settingsChangedId = 0;
        this._manager = null;
        this._keybindingAction = null;
        this._popup = null;
        this._popupDestroyId = 0;
    }

    enable() {
        this._settings = ExtensionUtils.getSettings();
        this._manager = new AudioOutputManager();

        this._addKeybinding();
        this._settingsChangedId = this._settings.connect(
            `changed::${SETTINGS_KEY_TOGGLE_SHORTCUT}`,
            () => this._addKeybinding()
        );
    }

    disable() {
        this._removeKeybinding();

        if (this._popup) {
            if (this._popupDestroyId) {
                this._popup.disconnect(this._popupDestroyId);
                this._popupDestroyId = 0;
            }
            this._popup.destroy();
            this._popup = null;
        }

        if (this._settings && this._settingsChangedId) {
            this._settings.disconnect(this._settingsChangedId);
            this._settingsChangedId = 0;
        }
        this._settings = null;

        if (this._manager) {
            this._manager.destroy();
            this._manager = null;
        }
    }

    _addKeybinding() {
        this._removeKeybinding();
        this._keybindingAction = Main.wm.addKeybinding(
            SETTINGS_KEY_TOGGLE_SHORTCUT,
            this._settings,
            Meta.KeyBindingFlags.NONE,
            Shell.ActionMode.NORMAL | Shell.ActionMode.OVERVIEW,
            (display, window, binding) => this._switchOutput(binding)
        );
    }

    _removeKeybinding() {
        Main.wm.removeKeybinding(SETTINGS_KEY_TOGGLE_SHORTCUT);
        this._keybindingAction = null;
    }

    _switchOutput(binding) {
        if (!this._manager)
            return;

        const outputs = this._manager.listOutputs();
        if (outputs.length === 0)
            return;

        const popup = new OutputSwitcherPopup(outputs, this._keybindingAction, this._manager);
        this._popup = popup;
        this._popupDestroyId = popup.connect('destroy', () => {
            if (this._popup === popup) {
                this._popup = null;
                this._popupDestroyId = 0;
            }
        });

        const shown = popup.show(
            binding.is_reversed(),
            binding.get_name(),
            binding.get_mask()
        );

        if (!shown) {
            // The popup could not grab input (another grab is active): at least
            // switch to the next device so the shortcut stays functional.
            popup.fadeAndDestroy();
            this._switchToNextDevice(outputs);
        }
    }

    _switchToNextDevice(outputs) {
        let activeIndex = outputs.findIndex(item => item.active);
        if (activeIndex < 0)
            activeIndex = 0;
        const next = outputs[_mod(activeIndex + 1, outputs.length)];
        if (next)
            this._manager.selectOutput(next.id);
    }
}

function init() {
    ExtensionUtils.initTranslations();
    return new AudioOutputSwitcherExtension();
}