feat: add Omarchy SUB/WAVE radio plugin

.github/workflows/validate.yml

@@ -0,0 +1,30 @@
+name: Validate
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install test dependencies
+        run: sudo apt-get update && sudo apt-get install -y jq socat
+      - name: Validate manifest contract
+        run: |
+          jq -e '
+            .schemaVersion == 1
+            and .id == "getsubwave.radio"
+            and (.kinds | sort) == (["bar-widget", "overlay"] | sort)
+            and .entryPoints.barWidget == "BarWidget.qml"
+            and .entryPoints.overlay == "StationPicker.qml"
+          ' manifest.json
+          test -x subwave-fetch
+          test -x subwave-player
+          test -x tests/run
+      - name: Run tests
+        run: ./tests/run

BarWidget.qml

@@ -0,0 +1,167 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import qs.Commons
+import qs.Ui
+import "StationModel.js" as StationModel
+
+BarWidget {
+  id: root
+  moduleName: "getsubwave.radio"
+
+  property bool playerRunning: false
+  property bool playerPaused: false
+  property int playerVolume: 70
+  property string stationName: "SUB/WAVE"
+  property string stationUrl: ""
+  property string trackTitle: ""
+  property string trackArtist: ""
+  property bool stationOnline: true
+  readonly property string playerPath: Qt.resolvedUrl("subwave-player").toString().replace(/^file:\/\//, "")
+  readonly property string fetchPath: Qt.resolvedUrl("subwave-fetch").toString().replace(/^file:\/\//, "")
+  readonly property string statusPath: Quickshell.env("XDG_RUNTIME_DIR") + "/omarchy-subwave/status.json"
+  readonly property string label: trackTitle
+    ? trackTitle + (trackArtist ? " · " + trackArtist : "")
+    : stationName
+
+  function applyStatus(raw) {
+    try {
+      if (typeof raw !== "string" || raw.length > 65536) return
+      var state = JSON.parse(raw || "{}")
+      playerRunning = state.running === true
+      playerPaused = state.paused === true
+      playerVolume = Math.max(0, Math.min(100, Math.round(Number(state.volume || 70))))
+      stationName = StationModel.singleLine(state.station && state.station.name || "SUB/WAVE", 160)
+      stationUrl = StationModel.normalizeOrigin(state.station && state.station.url || "")
+      if (!playerRunning) {
+        trackTitle = ""
+        trackArtist = ""
+      }
+      nowTimer.running = playerRunning && stationUrl !== ""
+      if (nowTimer.running) refreshNowPlaying()
+    } catch (error) {}
+  }
+
+  function applyNowPlaying(raw) {
+    try {
+      if (typeof raw !== "string" || raw.length > 65536) return
+      var state = JSON.parse(raw || "{}")
+      stationOnline = state.online !== false
+      if (state.station) stationName = StationModel.singleLine(state.station, 160)
+      if (!state.error) {
+        trackTitle = StationModel.singleLine(state.title, 512)
+        trackArtist = StationModel.singleLine(state.artist, 512)
+      }
+    } catch (error) { stationOnline = false }
+  }
+
+  function runAction(action, value) {
+    if (actionProcess.running) return
+    actionProcess.command = value === undefined
+      ? [playerPath, action]
+      : [playerPath, action, String(value)]
+    actionProcess.running = true
+  }
+
+  function changeVolume(delta) {
+    runAction("volume", Math.max(0, Math.min(100, playerVolume + (delta > 0 ? 5 : -5))))
+  }
+
+  function toggleOverlay() {
+    var configured = StationModel.normalizeOrigin(setting("stationUrl", ""))
+    var payload = JSON.stringify({ stationUrl: configured })
+    Quickshell.execDetached(["omarchy-shell", "shell", "toggle", "getsubwave.radio", payload])
+  }
+
+  function refreshNowPlaying() {
+    if (nowProcess.running || !stationUrl) return
+    nowProcess.command = [fetchPath, "now-playing", stationUrl]
+    nowProcess.running = true
+  }
+
+  implicitWidth: row.implicitWidth + Style.space(14)
+  implicitHeight: barSize
+
+  FileView {
+    path: root.statusPath
+    watchChanges: true
+    atomicWrites: true
+    printErrors: false
+    onLoaded: root.applyStatus(text())
+    onFileChanged: reload()
+  }
+
+  Process {
+    id: statusProcess
+    command: [root.playerPath, "status"]
+    running: true
+    stdout: StdioCollector { id: statusOutput; waitForEnd: true }
+    onExited: root.applyStatus(statusOutput.text)
+  }
+
+  Process {
+    id: actionProcess
+    command: []
+    stdout: StdioCollector { id: actionOutput; waitForEnd: true }
+    onExited: root.applyStatus(actionOutput.text)
+  }
+
+  Process {
+    id: nowProcess
+    command: []
+    stdout: StdioCollector { id: nowOutput; waitForEnd: true }
+    onExited: root.applyNowPlaying(nowOutput.text)
+  }
+
+  Timer {
+    id: nowTimer
+    interval: 5000
+    repeat: true
+    running: false
+    onTriggered: root.refreshNowPlaying()
+  }
+
+  Row {
+    id: row
+    anchors.centerIn: parent
+    spacing: Style.space(6)
+
+    Text {
+      anchors.verticalCenter: parent.verticalCenter
+      text: "󰝚"
+      color: root.playerRunning && !root.playerPaused && root.stationOnline
+        ? Color.accent : root.bar.barForeground
+      font.family: root.bar.fontFamily
+      font.pixelSize: Style.font.body
+    }
+
+    Text {
+      visible: !root.vertical
+      width: Math.min(implicitWidth, Style.space(180))
+      anchors.verticalCenter: parent.verticalCenter
+      text: root.label
+      color: root.bar.barForeground
+      font.family: root.bar.fontFamily
+      font.pixelSize: Style.font.body
+      elide: Text.ElideRight
+    }
+  }
+
+  MouseArea {
+    anchors.fill: parent
+    hoverEnabled: true
+    acceptedButtons: Qt.LeftButton | Qt.MiddleButton | Qt.RightButton
+    cursorShape: Qt.PointingHandCursor
+    onClicked: function(mouse) {
+      if (mouse.button === Qt.MiddleButton) root.runAction("toggle")
+      else if (mouse.button === Qt.RightButton) root.runAction("stop")
+      else root.toggleOverlay()
+    }
+    onWheel: function(wheel) { root.changeVolume(wheel.angleDelta.y) }
+    onEntered: if (root.bar) root.bar.showTooltip(root,
+      (root.playerRunning ? (root.playerPaused ? "Paused · " : "Playing · ") : "Open · ")
+      + root.stationName + (root.trackTitle ? "\n" + root.label : "")
+      + " · " + root.playerVolume + "%")
+    onExited: if (root.bar) root.bar.hideTooltip(root)
+  }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SUB/WAVE contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,126 @@
+# SUB/WAVE for Omarchy
+
+Listen to your own [SUB/WAVE](https://www.getsubwave.com) station and explore
+the public community directory without leaving the Omarchy shell. The plugin
+adds a theme-aware bar widget, a searchable station picker, and an MPV player
+that works with Omarchy's existing media controls.
+
+![SUB/WAVE station picker in Omarchy](preview.png)
+
+## Install
+
+```bash
+omarchy plugin add https://github.com/getsubwave/omarchy-subwave.git --enable
+```
+
+The community directory works immediately. To put your own self-hosted station
+first in the list, configure its bare public origin:
+
+```bash
+omarchy bar set getsubwave.radio stationUrl https://radio.example.com
+```
+
+Do not include `/listen`, `/stream.mp3`, credentials, query parameters, or a
+fragment. The plugin derives the API and stream paths from the origin.
+
+## Controls
+
+### Bar
+
+| Input | Action |
+| --- | --- |
+| Left click | Open or close the station picker |
+| Middle click | Play or pause |
+| Right click | Stop playback |
+| Mouse wheel | Change volume in 5% steps |
+
+### Station picker
+
+| Input | Action |
+| --- | --- |
+| Type | Search names, places, genres, operators, and descriptions |
+| Up / Down | Move through stations |
+| Enter | Play the selected station |
+| Escape | Clear search, then close |
+
+Selecting the station that is already playing closes the picker. Playback uses
+the station's always-available `/stream.mp3` mount. `mpv-mpris` exposes it to
+the built-in `omarchy.media` widget, media keys, and compatible headset controls.
+
+## Data and privacy
+
+The plugin fetches the normalized community directory from
+`https://www.getsubwave.com/stations.json`. It asks each visible station's
+public `/api/now-playing` endpoint for its current track and online state, and
+connects MPV directly to the selected station's `/stream.mp3` mount.
+
+Remote responses are size- and record-limited before entering QML. Only
+credential-free HTTP(S) origins are accepted, remote strings are never
+evaluated as commands, and cache/status writes are atomic.
+
+Version 1 supports public stations only. It does not accept or store listener
+passwords. Favorites, requests, and station administration remain in the
+station's web player.
+
+Non-secret persistent data is stored in:
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/omarchy-subwave/
+```
+
+Player sockets, status, PID identity, and logs live in:
+
+```text
+$XDG_RUNTIME_DIR/omarchy-subwave/
+```
+
+## Remove
+
+Stop the dedicated player before removing the plugin:
+
+```bash
+~/.config/omarchy/plugins/getsubwave.radio/subwave-player stop
+omarchy plugin remove getsubwave.radio
+```
+
+The last station, volume, and directory cache remain under
+`~/.local/share/omarchy-subwave/`. Remove that directory manually only if you
+also want to delete those preferences.
+
+## Troubleshooting
+
+Check the helper contracts directly:
+
+```bash
+~/.config/omarchy/plugins/getsubwave.radio/subwave-fetch catalog | jq 'length'
+~/.config/omarchy/plugins/getsubwave.radio/subwave-fetch now-playing https://radio.example.com | jq .
+~/.config/omarchy/plugins/getsubwave.radio/subwave-player status | jq .
+```
+
+MPV diagnostics are written to
+`$XDG_RUNTIME_DIR/omarchy-subwave/mpv.log`. If the bar does not pick up a saved
+plugin change, run:
+
+```bash
+omarchy-shell shell rescanPlugins
+```
+
+Malformed or oversized saved data is not overwritten automatically. Back up
+the affected file under `~/.local/share/omarchy-subwave/` before repairing or
+removing it.
+
+## Development
+
+```bash
+./tests/run
+omarchy plugin validate .
+qmllint -I /usr/share/omarchy/shell BarWidget.qml StationPicker.qml
+```
+
+The test suite uses temporary XDG directories and fake network/player
+boundaries; it does not tune a real station. The final QML checks require an
+Omarchy installation because they import the installed shell components.
+
+## License
+
+MIT