Omahub
← All plugins
F

Tunarchy

by flathack

Browse and play a Plex music library from the Omarchy bar.

GitHub

Security review

Review recommended · 9 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
937bb1e
Scanned
1 week ago
  • medium package_manager …/workflows/test.yml:34

    System package manager operation.

    apt-get update
  • medium package_manager …/workflows/test.yml:35

    System package manager operation.

    apt-get install --no-install-recommends -y qt6-declarative-dev-tools
  • medium sudo …/workflows/test.yml:34

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo apt-get update
  • medium sudo …/workflows/test.yml:35

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo apt-get install --no-install-recommends -y qt6-declarative-dev-tools
  • low obfuscation tests/test_player.py:21

    Augments a command with octal/hex escape sequences.

    \x0dIHDR" + struct.pack(">II", 16, 16)
  • low obfuscation tests/test_player.py:22

    Augments a command with octal/hex escape sequences.

    \xaeB\x60\x82")
  • low obfuscation tests/test_player.py:1354

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n")
  • low obfuscation bin/tunarchy:658

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n") and len(data) >= 24:
  • low obfuscation bin/tunarchy:709

    Augments a command with octal/hex escape sequences.

    \xaeB\x60\x82"))

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

None
AI risk level
None
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
937bb1e
Reviewed
1 week ago

The plugin is a well-scoped Plex music player: the QML panel talks to a Python helper that uses argument arrays, secure private storage, and same-origin redirect checks, and no install-time or destructive commands run on the user's machine. The deterministic scan's medium rating comes from CI-only apt-get usage and PNG magic-byte checks in artwork validation, neither of which is a real user risk.

How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/flathack/omarchy-tunarchy --enable
Widgets #bar #quickshell #media

Tunarchy

An unofficial native Omarchy bar widget for browsing and playing music from a Plex Media Server. Click the bar item to open a compact library browser and player. Tunarchy is not affiliated with or endorsed by Plex, Inc.

Tunarchy full and mini player preview

Features

  • Plex browser sign-in — no token copying required
  • One-click Plex on/off switch that keeps the saved account for instant reconnects
  • Home, artists, albums, playlists, history, favorites, queue, and search
  • Artist → album → track and playlist → track navigation
  • Album/playlist play and shuffle actions
  • Manageable queue with play, reorder, remove, and clear-upcoming actions
  • Album cover in the bar and player, progress, seek, play/pause, previous, and next
  • Theme-colored record placeholder when Plex has no usable cover art
  • System output volume by default, with optional 0–130% local player volume
  • Shuffle, repeat-all, and repeat-one
  • MPRIS integration for hardware media keys and desktop media controls
  • Plex Dashboard integration with live play, pause, progress, track, and stop updates
  • Actionable offline, authentication, DNS, library, and server error states
  • Lazy on-demand artwork loading, bounded private cache, and offline last-good data
  • Native Omarchy/Quickshell styling with top, bottom, and vertical bar support
  • Optional mini player popup with search, playback controls, progress, and volume
  • Mini mode shows only a music icon in the bar, with a subtle pulse during playback
  • The full player opens on Queue when music is playing
  • Live Omarchy theme and font matching: the bar label uses bar colors, while the player panel uses popup text, accent, and error colors from the active theme
  • Keyboard and mouse navigation
  • Credential-free demo mode with fictional music
  • No Python packages: the helper uses only Python's standard library
  • Plex access stored outside the plugin in a mode-0600 config file
  • mpv IPC playback sends the Plex token as an HTTP header, keeping it out of process arguments, stream URLs, and MPRIS metadata

Requirements

  • Omarchy 4.0 or newer with the plugin-based shell
  • Python 3.10 or newer
  • mpv (omarchy pkg add mpv)
  • mpv-mpris (omarchy pkg add mpv-mpris) for media keys and MPRIS
  • A reachable Plex Media Server with a music library
  • A Plex account that can access that server

Install

omarchy plugin add https://github.com/flathack/omarchy-tunarchy.git --enable

The manifest suggests the center of the bar. Move it at any time with:

omarchy bar move io.github.flathack.tunarchy --section center

Connect Plex

When the player is not connected, click Connect with Plex. Tunarchy asks for the server URL, opens Plex's sign-in page in the browser, and waits for you to approve the app. Your Plex password is entered only on Plex's website and is never visible to the plugin.

The same flow is available from a terminal:

~/.config/omarchy/plugins/io.github.flathack.tunarchy/bin/tunarchy login

Enter the HTTPS base URL, for example https://plex.example.net:32400. Tunarchy verifies TLS certificates and refuses to forward credentials across origins or from HTTPS to HTTP redirects. Use a plain http:// address only on a network you trust or inside an encrypted tunnel such as Tailscale; the Plex token is otherwise visible to devices that can observe that connection. If the server has several music libraries, setup asks which one to use.

Right-clicking the bar widget retains an interactive manual token setup as a recovery fallback. The token is read without echo and is never accepted as a command-line argument. Plex documents that fallback in Finding an authentication token / X-Plex-Token.

Connection details are stored in:

${XDG_CONFIG_HOME:-~/.config}/tunarchy/config.json

Usage

Tunarchy follows Omarchy theme and font changes automatically, including while the player panel is open. Use omarchy theme set <name> or omarchy font set <name> as usual; no separate Tunarchy theme or restart is needed. Themes may customize popup text through popups.text in Omarchy's shell.toml.

  • Left-click the bar item to open the player.
  • Switch between Full and Mini under Help and settings → Player view. Mini keeps the full library one click away through its list button. Search results appear as you type; select one with the arrow keys and press Enter to play it immediately.
  • Right-click it to reconfigure the Plex connection.
  • Middle-click it to play or pause.
  • Scroll over it to move to the previous or next track.
  • Type in the panel to search Plex.
  • Search terms are limited to 256 characters to keep helper and server requests bounded.
  • Use the navigation rail to browse artists, albums, playlists, history, favorites, and the active queue.
  • Click a collection to open it, or use its inline play/shuffle actions.
  • Reorder or remove upcoming tracks in the Queue view. When playback is stopped, Clear upcoming clears the complete saved queue because there is no current track.
  • Use Left/Right to switch library tabs when the search field is empty. While editing a query, those keys move the text cursor normally.
  • Use Up/Down to select rows and Enter to open or play them.
  • Use Ctrl+Enter to play a selected album or playlist and Shift+Enter to shuffle it; Shift+Enter queues a selected track next.
  • In Queue, use Ctrl+Up/Down to move a track and Delete to remove it.
  • Use Tab/Shift+Tab to reach sliders, transport controls, tabs, collection actions, and inline Queue actions. Enter or Space activates a focused button.
  • Escape clears an active search, returns from a collection, or closes the panel. Ctrl+Space toggles play/pause from anywhere in the panel.
  • Open help and settings with the tuna button in the upper-right corner or F1. Select System to control Omarchy's current audio output (the default), or Plex to change only Tunarchy's local mpv player volume. Press Escape to return to the player.
  • Use the power button in the header to disconnect from Plex without deleting the saved server or token. Switching it back on restores the saved connection; health checks continue retrying automatically if the server is temporarily offline.
  • Hardware media keys work through MPRIS while mpv is running.

The CLI is also useful for troubleshooting:

PLAYER="$HOME/.config/omarchy/plugins/io.github.flathack.tunarchy/bin/tunarchy"
"$PLAYER" doctor
"$PLAYER" status
"$PLAYER" health
"$PLAYER" connection off
"$PLAYER" connection on
"$PLAYER" library artists --limit 5
"$PLAYER" queue

Configuration

Plugin settings are exposed through Omarchy's schema:

omarchy bar set io.github.flathack.tunarchy recentAlbumCount 30
omarchy bar set io.github.flathack.tunarchy libraryItemCount 150
omarchy bar set io.github.flathack.tunarchy volumeMode System

Demo mode

Demo mode shows fictional data, never contacts Plex, and never starts mpv:

omarchy bar set io.github.flathack.tunarchy demoMode true --json
# Restore the real library afterwards:
omarchy bar set io.github.flathack.tunarchy demoMode false --json

Updates and removal

omarchy plugin update io.github.flathack.tunarchy
"${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/plugins/io.github.flathack.tunarchy/bin/tunarchy" shutdown
omarchy plugin remove io.github.flathack.tunarchy

The shutdown command reports the active session as stopped and terminates the private mpv process. Removing the plugin intentionally leaves connection settings and the size-limited artwork cache in place. To remove them too, move these folders to the desktop trash:

gio trash "${XDG_CONFIG_HOME:-$HOME/.config}/tunarchy"
gio trash "${XDG_CACHE_HOME:-$HOME/.cache}/tunarchy"

Development

Run the tests and the same manifest validation used during installation:

python3 -m unittest discover -s tests -v
node --test tests/test_model.js
omarchy plugin validate .

For local development, symlink the checkout and enable it:

ln -s "$PWD" "$HOME/.config/omarchy/plugins/io.github.flathack.tunarchy"
omarchy plugin enable io.github.flathack.tunarchy --section center

Plugin files normally reload after saving. If a change is not picked up, run:

omarchy-shell shell rescanPlugins

Brand assets

The generated Tuna artwork is stored in four transparent PNG variants:

  • assets/tuna-brand.png — cropped, 512-pixel detailed brand artwork
  • assets/tuna-ui-18.png — 18-pixel smallest UI sprite variant
  • assets/tuna-ui-24.png — 24-pixel bar and compact help button sprite
  • assets/tuna-ui-64.png — 64-pixel keyboard-help header artwork

Privacy and limitations

Library requests, cover downloads, audio streams, and playback timeline updates go directly to the Plex server configured by the user. The browser sign-in talks to plex.tv; no other third-party service is involved. See SECURITY.md for credential handling details.

  • Playback is local to this computer; this version does not remote-control a Plexamp client on another device.
  • Audio uses the original Plex media part directly. Tunarchy does not currently request a transcoded stream.
  • Playback queues are capped at 500 tracks. When a larger collection is started from a selected track, the queue continues from that track and wraps around.
  • The plugin implements the Plex server endpoints used by current Plex music libraries. Plex does not publish these endpoints as a stable public SDK.

License

MIT