Omahub
← All plugins
M

YouTube Shelf

by Martin Ro

Browse saved YouTube playlists and channels, then play audio with mpv.

GitHub

Security review

Review recommended · 2 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
4d81e17
Scanned
2 weeks ago
  • medium eval tests/resource-limits.sh:166

    Shell sources dynamically generated content.

    source <(awk '\''/^require_commands$/{exit} {print}'\'' "$PLUGIN_SCRIPT")
  • medium eval tests/resource-limits.sh:187

    Shell sources dynamically generated content.

    source <(awk '\''/^require_commands$/{exit} {print}'\'' "$PLUGIN_SCRIPT")

Automated analysis only — not a security guarantee.

AI advisory review

Review recommended

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

Medium
AI risk level
Medium
Recommendation
review
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
4d81e17
Reviewed
2 weeks ago

The runtime code is defensive and well-bounded; the deterministic scan's medium findings are in tests/resource-limits.sh and are test-harness only, not normal plugin execution. No persistence, credential access, or destructive install commands were found. The main remaining risk is the opaque bundled bin/yt-dlp executable that is launched during normal use, so its checksum should be verified against the upstream release before publishing.

  • tests/resource-limits.sh sources dynamically generated content from the main script, but this only happens in the test harness, not in plugin runtime.
  • bin/yt-dlp is a bundled binary that the plugin executes; it should be verified against the SHA-256 in THIRD_PARTY_NOTICES/README and the upstream release.
  • If XDG_RUNTIME_DIR is unset, the mpv IPC socket falls back to a predictable /tmp path; minor local-safety consideration.
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/martin-ro/omarchy-youtube-shelf --enable
Widgets #bar #quickshell #media

YouTube Shelf

YouTube Shelf is an Omarchy bar plugin for audio playback from saved YouTube playlists and channels. It opens a native Omarchy panel, like Wi-Fi and Bluetooth, and continues playback through a background mpv process.

Features

  • Save up to 100 public or unlisted YouTube playlists and channels.
  • Browse 100 recent videos by default, with a strict supported range of 1 to 200.
  • Play one video, the full visible list, or the list in shuffled order.
  • Browse and manage sources without opening a terminal.
  • Show a circled play icon when stopped or paused, and a circled pause icon in the current theme's accent color while playing.
  • Right-click the bar icon to pause or resume. Stop playback from the panel.
  • Use standard desktop media keys through MPRIS.
  • Keep saved sources outside the plugin so updates and removal do not erase them.

Install

omarchy plugin add https://github.com/martin-ro/omarchy-youtube-shelf.git --enable

The widget appears in the right section of the Omarchy bar.

Use

  1. Left-click the play icon in the bar.
  2. Select Add source.
  3. Paste a public or unlisted YouTube playlist or channel URL, then Save source.
  4. Select the saved source.
  5. Select one video, Play all, or Shuffle.

The panel closes when playback starts. Click outside it or press Escape to close it. Use the trash button beside a saved source to remove it after confirmation. Channel links automatically use the channel's Videos page.

Controls

Action Result
Left-click the bar icon Open or close the panel
Right-click the bar icon Pause or resume; open the shelf if stopped
Stop button in the panel Stop
Middle-click the bar icon No action
Desktop media keys Pause, resume, next, or previous

Requirements

  • Omarchy with the plugin system
  • mpv
  • jq
  • Python 3

The optional terminal picker (scripts/youtube-shelf without arguments) also requires fzf and gum.

A current generic yt-dlp executable is included in bin/. This avoids playback failures when the distribution package is older than YouTube's current stream format.

Resource limits

The plugin applies fixed limits before parsing or displaying local and remote data:

  • YOUTUBE_SHELF_LIMIT must be an integer from 1 to 200. The default is 100.
  • Saved sources are limited to 100 entries and a 256 KiB JSON file.
  • Saved source names are limited to 120 characters.
  • Saved source URLs are limited to 1,024 characters.
  • Remote yt-dlp stdout is limited to 4 MiB and stderr to 64 KiB.
  • Source checks stop after 45 seconds. Video-list requests stop after 75 seconds.
  • Remote titles, channel names, durations, URLs, and displayed errors have explicit field or display limits.
  • Generated TSV and M3U output is capped at 512 KiB before it is written.
  • mpv output is discarded. The plugin does not create a persistent player log.

Privacy and limitations

YouTube Shelf does not sign in to YouTube and does not read browser cookies. Private playlists, Watch Later, and Liked Videos are therefore unavailable. Change a custom playlist to Unlisted or Public before adding it.

The plugin stores only the names and URLs that you add. Saved sources remain in:

~/.config/omarchy/youtube-shelf/sources.json

The bounded current playback list is stored in:

~/.cache/youtube-shelf/current.m3u

The plugin does not keep a persistent mpv log.

Tests

Run the resource-boundary and panel API tests with:

./tests/resource-limits.sh
python tests/panel.py

The panel tests use a fake player and fake YouTube responses. They do not play sound or change your saved sources.

Update

omarchy plugin update io.github.martin-ro.youtube-shelf

Remove

omarchy plugin remove io.github.martin-ro.youtube-shelf

Removing the plugin does not remove your saved source list.

License

The plugin source is available under the MIT License. The bundled yt-dlp executable is available under the Unlicense. See THIRD_PARTY_NOTICES.md.