nuclear

Abstracts streaming from multiple free sources (YouTube, Jamendo, SoundCloud, Audius) through a plugin-based provider system. Each provider implements a standardized interface for search, metadata retrieval, and stream URL resolution, allowing the core player to remain agnostic to source-specific APIs. The plugin SDK enables third-party providers to be added without modifying core code.

Scans local filesystem for audio files, builds an indexed library with metadata extraction, and enriches tracks with information from external metadata providers (artist images, album art, release dates). Uses a schema-based model system to normalize metadata across different file formats and sources, storing results in a local database for fast retrieval without re-scanning.

Provides a theming system (packages/themes) that allows users to customize the player's appearance through predefined themes or custom CSS. Themes define color schemes, typography, and layout preferences, which are applied dynamically to React components via CSS-in-JS or Tailwind CSS. The system supports light/dark mode switching and theme persistence across sessions.

Organizes the project as a pnpm monorepo managed with Turborepo, enabling multiple packages (@nuclearplayer/player, @nuclearplayer/ui, @nuclearplayer/plugin-sdk, etc.) to be developed and versioned independently while sharing common dependencies. Turborepo optimizes build times through caching and parallel task execution. The structure enables clear separation of concerns (core player, UI library, plugin SDK, documentation).

Exposes Nuclear's capabilities as an MCP server, allowing AI models and agents to interact with the player programmatically. The MCP server provides tools for searching music, managing playlists, controlling playback, and querying library metadata. This enables AI assistants to understand user music preferences and provide recommendations or automate playlist creation based on natural language requests.

Manages user-created playlists and collections with full CRUD operations, supporting import/export in multiple formats (M3U, JSON, etc.). Playlists are stored locally with references to tracks (both local and streamed), and the system handles track resolution when sources change or become unavailable. Export functionality generates portable playlist files compatible with other players.

Builds a lightweight desktop application using Tauri (Rust + React) instead of Electron, reducing binary size and memory footprint while maintaining cross-platform compatibility (Windows, macOS, Linux). The Rust backend (src-tauri) handles system-level operations (file I/O, audio playback, process management), while the React frontend (packages/ui) provides the UI layer. IPC bridges TypeScript/JavaScript frontend calls to Rust backend functions.

Provides a TypeScript-based plugin SDK (packages/plugin-sdk) that allows developers to extend the player with custom providers, playback handlers, queue managers, and settings. Plugins are loaded dynamically at runtime and communicate with the core player via a standardized interface. The plugin store enables discovery and installation of community-developed plugins without modifying core code.

Implements a unified search interface that queries multiple providers (streaming sources and local library) in parallel, aggregates results, and ranks them by relevance. Metadata is fetched from multiple sources (provider APIs, local tags, external metadata services) and deduplicated to avoid showing duplicate results. Search results include track, album, and artist information with fallback logic when primary sources are unavailable.

Provides a comprehensive i18n system (packages/i18n) that enables the UI to be translated into multiple languages. Translations are stored in JSON files organized by language code, and the system dynamically loads the appropriate language based on user locale or preference. The i18n package exports translation keys and functions for use in React components, enabling compile-time type safety for translation strings.

Manages the playback queue with operations like add, remove, reorder, and clear. Implements playback state management (playing, paused, stopped) and controls (play, pause, next, previous, seek). The queue system supports both linear playback and shuffle/repeat modes. Queue state is persisted locally so playback can resume from where the user left off.

Handles audio decoding and playback for multiple formats (MP3, FLAC, OGG, WAV, etc.) using platform-specific audio backends. Implements volume control, equalizer, and audio effects through a pluggable playback system. The Tauri backend abstracts platform differences (Windows WASAPI, macOS CoreAudio, Linux ALSA/PulseAudio), providing a unified playback interface to the frontend.

Manages user preferences (theme, language, audio settings, provider configuration) with persistent storage in a local database or configuration files. Settings are organized hierarchically and can be modified through the settings UI or programmatically via the settings plugin. Changes are immediately persisted and applied without requiring app restart.