add Noctalia YT Music plugin

[aabidk20]

Plugin

• Id: aabidk20/noctalia-ytmusic
• New plugin
• Update to an existing plugin (version bumped in plugin.toml)

What it does

Noctalia YT Music is a YouTube Music client for Noctalia v5 featuring:

• Full audio playback control via MPV backend with MPRIS integration.
• Library browsing (playlists, history, quick picks, search).
• Offline audio track, thumbnails, stats caching.
• Dedicated cookie extraction wizard using local browser session profiles.

External dependencies

• yt-dlp: Stream URL resolution, track metadata extraction, and offline track downloading.
• mpv: Background audio player daemon.
• mpv-mpris: System media controls and MPRIS interface integration. (Optional)
• jq: In-flight JSON parsing for InnerTube API responses.
• curl: Asynchronous HTTP network requests for browse, thumbnails, and likes.
• nc: Socket communication with the local MPV daemon.

Testing

• Tested Flows:

  • Exported YouTube session cookies via the cookie extraction wizard using local browser session.
  • Browsed user playlists
  • Performed track/artist searches
  • Tested playback controls (play, pause, next/prev track, volume) which are handled via MPV backend and MPRIS interface.
  • Validated offline audio track downloading and caching under $XDG_CACHE_HOME/noctalia-ytmusic/audio/.
  • Toggled plugin settings and panel views (panel-toggle aabidk20/noctalia-ytmusic:panel and mini).

• Tested on Niri

• Tested on Hyprland

• Tested on Sway

• Tested on another compositor:

• Noctalia version tested against: Noctalia v5 (v0.5.x)

• Plugin API level: 23

Screenshots / Videos

Key Technical Details & Accounting

Security & Privacy Notice

• Cookie Extraction: Uses yt-dlp --cookies-from-browser locally to extract session cookies when triggered via the cookie extraction page. Cookies are strictly saved to $XDG_CACHE_HOME/noctalia-ytmusic/cookies.txt and are never uploaded or sent to third-party endpoints besides the Youtube Music endpoints explicitly listed here. Extraction happens only when user explicitly selects a browser and never automatically.
• Cache Isolation: Audio cache, artwork, and JSON state persistence remain entirely within $XDG_CACHE_HOME/noctalia-ytmusic/.
• Debug logs: The plugin contains a debug log feature, which generates a log file locally. Users can review the collected logs before submitting, the details about content are mentioned clearly in project's README.

Below is an account of network endpoints, commands, filesystem paths used by the plugin

1. Network

Endpoint / Target	Purpose	Executed By	Location
music.youtube.com/youtubei/v1/browse	Fetch Home mix, Playlists, and continuation pages	curl + jq via shell	api/browse.luau
youtubei/v1/like/like Endpoint & like/removelike Endpoint	Like/unlike tracks on YT Music	curl via shell	api/likes.luau
youtubei/v1/search	Search tracks/albums/artists	noctalia.http	api/search.luau, api/innerTube.luau
i.ytimg.com/vi/...	Fetch track & playlist thumbnails	curl via shell	api/thumbnails.luau
youtube.com/watch?v=...	Audio stream URL resolution, offline audio download, view/like stats	yt-dlp	api/resolve.luau, api/stats.luau, scripts/cookies.sh

2. Process

Command / Process	Purpose	Trigger Location
curl	Raw HTTP POST to InnerTube API & thumbnail fetching	api/browse.luau, api/likes.luau, api/thumbnails.luau
jq	In-flight JSON parsing & payload extraction	api/browse.luau, api/search.luau
yt-dlp	Resolve audio stream URLs & download audio files for offline cache	api/resolve.luau,api/stats.luau, scripts/cookies.sh
mpv	Audio backend for playback via IPC socket	scripts/mpv.sh
nc	Socket communication with MPV daemon	scripts/mpv.sh
timeout	Enforce execution budget/timeouts on background commands	scripts/cookies.sh, scripts/mpv.sh
mkdir / du / rm	Cache directory management & disk usage accounting	api/cache.luau, modules/cacheops.luau, scripts/cookies.sh, api/thumbnails.luau, api/resolve.luau, cacheops.luau
xdg-open / Browser launch	Open browser for YouTube authentication during cookie export	scripts/cookies.sh

3. Filesystem Accounting

Path	Purpose	Written By
$XDG_CACHE_HOME/noctalia-ytmusic/cookies.txt	Exported YouTube session cookies	scripts/cookies.sh
$XDG_CACHE_HOME/noctalia-ytmusic/{library,recent_playlists,session,quick_picks,stats}.json	Cached metadata & plugin state persistence	api/cache.luau, modules/cacheops.luau
$XDG_CACHE_HOME/noctalia-ytmusic/playlists/	Cached playlist structure JSONs	api/browse.luau
$XDG_CACHE_HOME/noctalia-ytmusic/thumbnails/	Cached track and playlist artwork	api/thumbnails.luau
$XDG_CACHE_HOME/noctalia-ytmusic/audio/	Downloaded offline audio tracks	api/resolve.luau
/tmp/noctalia-ytmusic-*	Temporary payload, IPC socket (mpv.sock), raw responses & scratch files	api/*, scripts/mpv.sh

Checklist

• The directory name matches the part of id after the / in plugin.toml exactly.
• It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
• README.md follows the README template, documents every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
• I created thumbnail.webp with the thumbnail generator.
• version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
• Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
• I did not edit catalog.toml; CI generates it.
• This PR touches exactly one plugin directory.

Code review attestation

• The code is readable and not obfuscated, minified, or generated.
• It does not download and execute remote code.
• Every network call, filesystem write, and spawned process is something the description above accounts for.
• I have the right to publish this code under the license declared in plugin.toml.