Nocky

Nocky is a native GTK4/libadwaita music player for Linux. It combines a polished local-library experience with synchronized lyrics, a real-time spectrum visualizer, MPRIS controls, optional Noctalia color integration, and an optional YouTube Music integration.

This app is vibe-coded and any improvement suggestion is welcomed, but don't expect much as it's just a free time hobby project =)

Status: Nocky 0.6.0 is a beta release. It introduces the redesigned responsive YouTube Music Home, direct InnerTube recommendation parsing, durable cache-first restoration, offline playlist playback and privacy-safe account disconnection.

Note

Nocky is inspired by the visual language, theming system and desktop experience of Noctalia Shell.

A heartfelt thank-you goes to the Noctalia developers and contributors for creating and sharing such an inspiring project.

Nocky is an independent, unofficial hobby project. It is not affiliated with, endorsed by, maintained by, or officially connected to the Noctalia project or its development team.

Highlights

• Frosted Glass theme with floating translucent surfaces and matte controls
• Three visual identities: Noctalia, Material Expressive and Frosted Glass
• Artwork-aware dynamic color transitions shared by the expressive themes
• Independent blur source and glass-opacity controls for Niri and Hyprland
• Native Rust, GTK4 and libadwaita interface
• Recursive local music-library scanning
• Unified local and YouTube Music albums, artists, playlists and liked songs
• Stable track/disc-aware playback queues
• Embedded and sidecar album artwork
• Direct GStreamer playback engine
• Noctalia-style 60 Hz mirrored audio spectrum visualizer
• Five-line synchronized lyrics preview
• Full synchronized .lrc lyrics page
• Automatic LRCLIB lookup
• MPRIS support for media keys, playerctl and desktop shells
• Optional Noctalia palette integration with live CSS reload
• Frosted Glass visual theme with compositor-backed blur and album-aware accents
• Optional YouTube Music catalogue search and automatic account-library synchronization

Visual themes

Nocky 0.6.0 includes three visual identities:

• Noctalia follows the desktop palette and keeps the original shell-oriented appearance.
• Material Expressive uses solid tonal surfaces, expressive motion and colors derived from the current artwork.
• Frosted Glass uses floating translucent islands, matte controls, restrained borders and artwork colors as ambient lighting.

The blur provider is selected independently from the visual theme: custom compositor blur, Noctalia-managed blur or no blur. Nocky never writes compositor configuration. Niri or Hyprland supplies the real blur while Nocky controls GTK surface opacity.

See the complete Frosted Glass documentation.

YouTube Music integration

• ytmusicapi provides catalogue and account-library data;
• yt-dlp resolves a temporary audio URL;
• Deno supplies the JavaScript runtime required by current YouTube extraction;
• Nocky's native GStreamer engine plays the stream and keeps MPRIS, visualizer and media controls working.

Public search works without connecting an account. After connecting, Nocky automatically synchronizes saved songs, liked songs and personal playlists into the main library interface on startup. Online albums and artists are grouped from the synchronized catalogue, and a Sync with Nocky button is still available for manual refreshes. The last synchronized library is loaded from disk immediately, while a fresh synchronization runs in the background. Nocky also prefetches the next four stream URLs and keeps separate 512 px and 1200 px artwork caches for collection cards and the now-playing view. Read docs/YOUTUBE_MUSIC.md before connecting an account.

No cookies, sessions, .env files or personal data from the reference project are included in this repository.

Supported local audio formats

Playback depends on the GStreamer plugins installed on the system. With the common plugin sets, Nocky can play MP3, FLAC, OGG, Opus, M4A/MP4, WAV, AAC and many other formats.

Complete installation

The universal source installer supports Debian/Ubuntu, Fedora, openSUSE and Arch-based distributions.

chmod +x install.sh
./install.sh --install-deps

This builds Nocky, installs its desktop integration and icons, creates an isolated Python runtime for YouTube Music, installs pinned ytmusicapi/yt-dlp dependencies and bundles Deno when it is not already installed.

For local-library-only use:

./install.sh --install-deps --without-youtube

By default, Nocky is installed for the current user under ~/.local. Use --system for /usr/local:

./install.sh --install-deps --system

More options:

./install.sh --help

Run from source

Create the project-local YouTube runtime once, then launch the app:

./scripts/setup-youtube-runtime.sh
cargo run

For local-only development, cargo run works without the helper runtime.

Diagnostics:

./scripts/check-playback.sh
./scripts/check-youtube.sh
./scripts/check-mpris.sh

Installed files

A user installation places files in:

~/.local/bin/nocky
~/.local/share/applications/io.github.maylton.Nocky.desktop
~/.local/share/icons/hicolor/*/apps/io.github.maylton.Nocky.png
~/.local/share/metainfo/io.github.maylton.Nocky.metainfo.xml
~/.local/share/nocky/helpers/nocky_youtube.py
~/.local/share/nocky/runtime/

The desktop entry, icon and application ID all use io.github.maylton.Nocky, so the icon is resolved correctly by Wayland desktops, launchers and task switchers after installation.

Configuration and private data

Nocky stores ordinary settings at:

~/.config/nocky/config.json

YouTube Music browser-session headers are stored in Secret Service/libsecret when available. The fallback is:

~/.config/nocky/youtube-session.json

The fallback file is created with mode 0600. Stream URLs and cover images are cached below ~/.cache/nocky/youtube/. Disconnecting the account removes the saved session.

Uninstall

./uninstall.sh

For a system installation:

./uninstall.sh --system

The uninstaller intentionally preserves user settings, session data and cache. Disconnect the account in Nocky before uninstalling, or remove ~/.config/nocky/youtube-session.json manually when Secret Service is not available.

First-run setup

New installations open a five-step setup wizard before the main interface. It covers the initial music source, the experimental YouTube Music integration, window blur, Noctalia palette synchronization, the Material Design 3-inspired wavy progress bar and footer behavior.

Noctalia-specific appearance options are enabled only when Noctalia Shell is detected. Existing users are migrated as already onboarded and are not interrupted after upgrading.

For development testing:

NOCKY_FORCE_ONBOARDING=1 cargo run

Lyrics

Nocky loads sidecar .lrc files and can automatically search LRCLIB when synchronized lyrics are missing. Downloaded lyrics are saved beside local audio files when the folder is writable. Local and YouTube Music tracks can use the five-line inline preview and the full lyrics page. The focused inline line wraps only when it exceeds the available card width.

MPRIS

The player registers as org.mpris.MediaPlayer2.Nocky. Local and YouTube tracks publish title, artist, album, duration, cover and source URL where available.

Noctalia plugin ecosystem

Nocky integrates with two independent Noctalia plugins maintained by the same author:

• Album Aura derives a Noctalia palette from the current album and consumes Nocky's native runtime bridge.
• OpenRGB Noctalia applies the active Noctalia primary color to supported OpenRGB devices.

Nocky playback and artwork
          ↓
     Album Aura
          ↓
 Noctalia active palette
          ↓
OpenRGB Noctalia (optional)

The projects remain independent: Nocky publishes playback data, Album Aura controls the shell palette, and OpenRGB Noctalia controls physical RGB devices. See the complete ecosystem documentation.

Noctalia theme integration

Nocky remains an independent project, but it can follow Noctalia's Material color roles. The app watches ~/.config/nocky/theme.css. Use assets/nocky.css.template as a Noctalia template and set its output to that path.

Frosted Glass theme

Frosted Glass is available as a third visual theme. It reuses the Material 3 Expressive interaction model and dynamic album palette while adding translucent surfaces, highlights, borders and depth. Real blur is supplied by the compositor; Nocky only controls GTK surface transparency. See docs/FROSTED_GLASS.md.

Project structure

src/
├── main.rs             process entry point and module declarations
├── app/                application startup, state, sidebar and controller
│   └── controller/     playback, queue, YouTube, offline and UI coordination
├── ui/                 footer, player, settings and reusable GTK widgets
├── playback/           GStreamer engine, queue, MPRIS and session state
├── youtube/            YouTube page, library/cache and playback bridge
├── lyrics/             lyrics presenter and full/inline views
├── integrations/       external runtime bridges such as Album Aura
├── browser.rs          unified local/YouTube library browser and routes
├── config.rs           persistent settings and migrations
├── library.rs          recursive local-library scanner
├── material_palette.rs dynamic Material palette generation
├── offline_store.rs    offline collection metadata and persistence
├── visual_theme.rs     visual-theme and artwork-palette coordination
└── visualizer.rs       theme-aware spectrum visualizer

helpers/
└── nocky_youtube.py    ytmusicapi/yt-dlp sidecar

requirements-youtube.txt  pinned optional Python runtime

Development

./scripts/quality-gate.sh
./scripts/verify-release.sh
./install.sh --version

See CONTRIBUTING.md for contribution guidelines.

Current beta limitations

• A tiny lower-border rasterization artifact may appear on the main Frosted Glass player card with some GTK/compositor combinations.
• YouTube Music uses an unofficial browser-session integration and can require updates when the service changes.
• YouTube stream URLs are temporary, although Nocky automatically refreshes rejected or expired streams.
• YouTube Music mutations are reconciled asynchronously and may be confirmed again during the next library synchronization when remote verification is unavailable.
• A minor Home-player layout shift may occur while inline lyrics change from loading to synchronized content.
• Gapless playback is disabled; the pipeline is reset between tracks for reliability.
• Flatpak packaging is planned but not included in this release.

License

Nocky is licensed under the GNU General Public License v3.0 or later. See LICENSE.