Skip to content

feat(cider): Umbriel loft and overlay OSD (1.10.0) #680

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ItsLemmy merged 2 commits into from
Sep 9, 2026
Merged

feat(cider): Umbriel loft and overlay OSD (1.10.0) #680

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
357e013
feat(cider): Umbriel loft and overlay OSD (1.10.0)
dragged9698 Sep 9, 2026
c305c08
fix(cider): drop unsupported panel layer field
dragged9698 Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 27 additions & 23 deletions cider/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,25 @@ Replaces the sparse stock media OSD **for Cider only**. Other players keep Nocta

## Plugin


| Field | Value |
| ---------- | ---------------------------------------------------------- |
| ID | `dragged/cider` |
| Entries | Bar widget: `now-playing`; panel: `osd`; service: `bridge` |
| Dependency | `python3`, `gtk3`, `gtk-layer-shell`, `python-gobject` |

| Field | Value |
| ------------ | ---------------------------------------------------------- |
| ID | `dragged/cider` |
| Entries | Bar widget: `now-playing`; panel: `osd`; service: `bridge` |
| Dependencies | `python3`, `gtk3`, `gtk-layer-shell`, `python-gobject` |

## Requirements

- Noctalia v5.0.0-beta.9+ (`plugin_api` 24 — argv `runAsync`). Tested on Umbriel, Niri, and Hyprland.
- Noctalia v5.0.0-beta.9+ (`plugin_api` 24 — argv `runAsync`). Tested on Umbriel 0.1.0 / Noctalia v5.0.1; Niri and Hyprland keep left-click = lyrics HUD.
- Cider with Connectivity / External API enabled
- `python3` on `PATH`, with `python-socketio`, `requests`, and `websocket-client` (`pip install -r requirements.txt` from this plugin directory)
- Overlay HUD: `gtk3`, `gtk-layer-shell`, and `python-gobject`. Untimed silence gate optionally uses `parec` (PulseAudio / PipeWire).


- Umbriel loft (middle-click): `umbriel` on `PATH` (0.1.0+). No-op on other compositors.

## Usage

1. Enable **Cider** in Settings → Plugins (or `noctalia msg plugins enable dragged/cider`).
2. Open **Settings → Plugins → Cider** and set the API token, or leave it empty to reuse `~/.config/cider-kde-notifier/config.json`.
3. Add bar widget `dragged/cider:now-playing`. Click it to toggle the sticky lyrics HUD (gtk-layer-shell overlay).
3. Add bar widget `dragged/cider:now-playing`. **Left-click** toggles the sticky lyrics HUD. **Middle-click** lofts Cider to the Umbriel scratchpad (and restores it). **Right-click** shows the OSD card. All three are remappable in the widget editor (`[widget.actions]`).
4. **Do not put Cider on** `shell.mpris.blacklist` — that also kills Control Center / Media Now Playing.
5. Hide Cider app toasts with a notification filter (not an MPRIS blacklist). Plugin toasts use app name `Now Playing` / desktop entry `noctalia-now-playing`:

Expand All @@ -49,22 +46,29 @@ Put `cider_app` first in `notification.filter_order`.
media = false
```



### Panels

```sh
noctalia msg panel-toggle dragged/cider:osd
```

`osd` is the now-playing card (also opened automatically on track change when **Track alert** is OSD). Lyrics always use the gtk-layer-shell overlay.

Bar chip: **left-click** toggles the lyrics HUD; **right-click** shows the OSD card. Both are remappable in the widget editor (`[widget.actions]`).
`osd` is the now-playing card (also opened automatically on track change when **Track alert** is OSD). It is a persistent floating panel. Lyrics always use the gtk-layer-shell overlay. On 5.0.1 the host also injects Attached/Floating/Layer/Open Near Click overrides under **Settings → Plugins** (gear on this plugin).

Cider’s MPRIS has no synced lyrics. The bridge pulls Apple Music TTML via Cider’s amapi (LRCLIB fallback) for the sticky HUD.

## Settings
### Bar chip clicks

Defaults are remappable in the widget editor.

| Click | Umbriel | Niri / Hyprland |
| --- | --- | --- |
| Left | Lyrics HUD | Lyrics HUD |
| Middle | Loft that Cider window (scratchpad send/restore) | Lyrics HUD (`chip-left` dispatcher) |
| Right | Track OSD | Track OSD |

`toggle-loft` is also a bindable IPC event. It is a no-op when Cider is not running or the window id is unknown. Lyrics and OSD IPC stay unaliased.

## Settings

| Setting | Type | Default | Description |
| ------------------------- | -------- | ------------------------ | --------------------------------------------------------------------------- |
Expand Down Expand Up @@ -93,7 +97,6 @@ Cider’s MPRIS has no synced lyrics. The bridge pulls Apple Music TTML via Cide
| `cover_size` | `int` | `18` | Bar widget artwork size, 12–32 px. |
| `glyph` | `glyph` | `music` | Bar widget fallback icon when artwork is hidden/missing. |


Gap under the bar is shell-global: **Settings → Shell → Panel → floating offset**.

## IPC
Expand All @@ -104,15 +107,16 @@ noctalia msg plugin dragged/cider:bridge all hide-osd
noctalia msg plugin dragged/cider:bridge all toggle-lyrics-hud
noctalia msg plugin dragged/cider:bridge all show-lyrics-hud
noctalia msg plugin dragged/cider:bridge all hide-lyrics-hud
noctalia msg plugin dragged/cider:bridge all chip-left
noctalia msg plugin dragged/cider:bridge all toggle-loft
```



## Notes

- **Network:** the Python bridge talks to Cider’s local Connectivity API (`base_url`). Lyrics use Cider `amapi/run-v3` (Apple Music TTML) with an LRCLIB fallback.
- **Processes:** `scripts/start-bridge.sh` launches `scripts/cider_bridge.py`. The lyrics HUD is `scripts/lyrics_overlay.py`. Disable/uninstall stops them via `onExit`.
- **Filesystem:** runtime JSON, artwork, and the Cider API token file live under `~/.cache/noctalia-cider/`. Durable settings also go to `noctalia.pluginDataDir()`. `ui.image` only loads local cover files after the bridge downloads them. Detached process logs: `/tmp/noctalia-cider-bridge.log`, `/tmp/noctalia-cider-lyrics-overlay.log`.
- **Processes:** `scripts/start-bridge.sh` launches `scripts/cider_bridge.py`. The lyrics HUD is `scripts/lyrics_overlay.py`. Umbriel loft is a one-shot `python3 cider_bridge.py --toggle-loft` (does not restart the bridge). Disable/uninstall stops helpers via `onExit`.
- **Filesystem:** runtime JSON, artwork, loft latch, and the Cider API token file live under `~/.cache/noctalia-cider/`. Durable settings also go to `noctalia.pluginDataDir()`. `ui.image` only loads local cover files after the bridge downloads them. Detached process logs: `/tmp/noctalia-cider-bridge.log`, `/tmp/noctalia-cider-lyrics-overlay.log`.
- **Compositor:** Umbriel loft send/restore uses `umbriel msg` (`window-move-to-scratchpad`, `scratchpad-toggle`, `window-restore-from-scratchpad`). If another client is stored in the same output pad, it can flash for a frame on restore — Umbriel cannot restore a hidden pad member without showing the pad first.
- **Panels:** `panel-open` / `panel-close` are used instead of `togglePanel` so a persistent toast is never inverted if it is already open.
- Local path source for development:

Expand All @@ -121,4 +125,4 @@ noctalia msg plugins source add cider-local path /path/to/noctalia-plugin
noctalia msg plugins enable dragged/cider
noctalia msg config-reload
noctalia plugins lint cider
```
```
3 changes: 2 additions & 1 deletion cider/plugin.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

id = "dragged/cider"
name = "Cider"
version = "1.9.7"
version = "1.10.0"
plugin_api = 24
author = "dragged"
license = "MIT"
Expand Down Expand Up @@ -246,6 +246,7 @@ entry = "widget.luau"
# Remappable from the bar widget editor (community pattern: airpods / todo / mimir).
[widget.actions]
left = "plugin dragged/cider:bridge all toggle-lyrics-hud"
middle = "plugin dragged/cider:bridge all chip-left"
right = "plugin dragged/cider:bridge all show-osd"

[[widget.setting]]
Expand Down
Loading