MoosicBox Native App

A cross-platform desktop music application built with the HyperChad framework, providing a native interface for the MoosicBox music server.

Overview

The MoosicBox Native App is a desktop client that provides:

• Cross-Platform Support: Windows, macOS, and Linux
• Multiple UI Backends: Egui (GPU-accelerated), FLTK (lightweight), Web (HTML/JS)
• Music Streaming: Connect to local or remote MoosicBox servers
• Multi-Source Support: Local library, Tidal, Qobuz, YouTube Music
• High-Quality Audio: Support for FLAC, AAC, MP3, Opus formats
• Modern Interface: Responsive design with native look and feel
• Download Support: Download music for offline playback

Installation

From Source

cargo install --path packages/app/native --features "default"

Pre-built Binaries

Download from the releases page or build locally.

System Dependencies

Linux

# Ubuntu/Debian
sudo apt-get install pkg-config libssl-dev libgtk-3-dev

# For audio support
sudo apt-get install libasound2-dev libpulse-dev

# For Egui backend
sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

macOS

# Using Homebrew
brew install pkg-config openssl

# For audio support
brew install portaudio

Windows

• Visual Studio Build Tools or Visual Studio Community
• Windows SDK

Usage

Basic Usage

Start the native app:

moosicbox_app_native

Or using cargo:

cargo run --bin moosicbox_app_native --features "default"

Library Integration API

If you embed this crate in another Rust application, the primary public entry points are:

• moosicbox_app_native::init() - Initializes and returns the application router with all routes registered
• moosicbox_app_native::init_app_state(state).await - Initializes app state persistence and event listeners
• moosicbox_app_native::actions::handle_action(action, value).await - Dispatches UI actions (playback, queue, search, filtering)
• Global statics: ROUTER, RENDERER, STATE_LOCK, STATE, and PROFILE

Connection Configuration

Server connections are configured through the in-app settings interface:

• Navigate to Settings → Connections
• Add a new connection with your server URL
• Select the connection to use

UI Backend Selection

The default build includes multiple UI backends. You can enable specific backends with cargo features:

Egui (GPU Accelerated - Default)

cargo run --features "egui-wgpu"

Additional Egui variants:

• egui-glow - OpenGL backend
• egui-v1 - Legacy HyperChad egui renderer implementation (original, overcomplicated)
• egui-v2 - New HyperChad egui renderer implementation (work in progress, simplified)

FLTK (Lightweight)

cargo run --features "fltk" --no-default-features

Web Interface (HTML + JavaScript)

cargo run --features "html,vanilla-js" --no-default-features

The web interface supports additional deployment options:

• actix - Deploy with Actix web server
• lambda - Deploy as AWS Lambda function

Configuration

Environment Variables

Note: Server connection settings are configured through the in-app settings interface rather than environment variables.

Features

Audio Formats Support

• FLAC - Lossless audio with full quality
• AAC/M4A - High-quality lossy compression
• MP3 - Universal compatibility
• Opus - Modern, efficient codec

Music Sources

• Local Library - Your personal music collection
• Tidal - Hi-Fi streaming service
• Qobuz - Hi-Res audio streaming
• YouTube Music - Google's music service

Playback Features

• Audio Visualization - Real-time waveform display
• Volume Control - Adjust playback volume
• Seek Control - Navigate within tracks
• Queue Management - Control playback order

Planned Features

• Gapless playback
• Crossfade transitions
• Replay Gain normalization
• Equalizer controls
• Lyrics display

Interface Features

• Library Browser - Navigate your music collection
• Albums View - Browse and filter albums by source
• Artist View - View artist details and albums
• Audio Zones - Manage playback zones
• Playback Sessions - View and control active sessions
• Settings - Configure connections, downloads, and music API sources
• Download Manager - Offline music management

Building

Development Build

# Debug build with all features
cargo build --features "default"

# Specific UI backend
cargo build --features "egui-wgpu,all-decoders,all-sources"

Release Build

# Optimized release build
cargo build --release --features "default"

# Minimal build for distribution
cargo build --release --features "egui-wgpu,all-os-decoders" --no-default-features

Cross-Platform Builds

# Build for Windows from Linux
cargo build --release --target x86_64-pc-windows-gnu

# Build for macOS from Linux (requires cross-compilation setup)
cargo build --release --target x86_64-apple-darwin

# Build AppImage for Linux
cargo install cargo-appimage
cargo appimage --release

Bundled Mode

For self-contained deployment with embedded server:

# Build with bundled server
cargo build --release --features "bundled,all-sources,all-decoders"

# This creates a single executable with embedded MoosicBox server

Bundled Mode Features

• Standalone Operation - Embedded server runs in the same process
• Auto-Configuration - Automatic server startup and initialization
• Performance - Direct in-process communication with the server

Development

Local Development

# Start with debug features
cargo run --features "dev,console-subscriber,debug"

Note: The dev feature enables asset serving and static route handling for development.

Testing Different Backends

# Test Egui backend
cargo test --features "egui-wgpu"

# Test FLTK backend
cargo test --features "fltk"

# Test web backend
cargo test --features "html,vanilla-js"

Performance Profiling

# Profile with puffin
cargo run --features "profiling-puffin,egui-wgpu"

# Profile with tracing
cargo run --features "profiling-tracing,egui-wgpu"

# Profile with Tracy
cargo run --features "profiling-tracy,egui-wgpu"

Packaging

Windows Installer

# Build MSI installer
cargo install cargo-wix
cargo wix --install

# Build NSIS installer (requires NSIS)
cargo install cargo-wix
cargo wix --installer nsis

macOS Bundle

# Create .app bundle
cargo install cargo-bundle
cargo bundle --release

# Create DMG
cargo install cargo-bundle
cargo bundle --format dmg --release

Linux Packages

# Create AppImage
cargo install cargo-appimage
cargo appimage --release

# Create Debian package
cargo install cargo-deb
cargo deb --release

# Create RPM package (requires rpm tools)
cargo install cargo-rpm
cargo rpm build --release

User Interface

Main Interface Components

The user interface is built using the HyperChad framework and includes:

1. Home View - Main dashboard with library access
2. Albums View - Browse and filter albums by source
3. Artists View - View artist details and albums
4. Player Controls - Play, pause, skip, seek, volume control
5. Audio Visualization - Real-time waveform display
6. Settings - Configure connections, downloads, music API sources, and scan settings
7. Audio Zones & Sessions - Manage playback zones and sessions

The interface and keyboard shortcuts are currently determined by the UI backend being used (Egui, FLTK, or Web). Note: Standardized keybindings across all UI backends is a planned future enhancement.

Troubleshooting

Common Issues

1. Connection failed: Check server URL and network connectivity
2. Audio playback issues: Verify audio drivers and output device
3. High CPU usage: Try different UI backend or disable visualizations
4. Crashes: Check system dependencies and graphics drivers

Debug Information

# Enable detailed logging
RUST_LOG=moosicbox_app_native=debug moosicbox_app_native

# Audio debugging
RUST_LOG=moosicbox_audio=debug moosicbox_app_native

# Network debugging
RUST_LOG=moosicbox_http=debug moosicbox_app_native

Performance Issues

# Disable GPU acceleration if issues occur
cargo run --features "egui-glow" --no-default-features

# Use lightweight FLTK backend
cargo run --features "fltk" --no-default-features

Architecture

The MoosicBox Native App is structured as follows:

• Main Application (moosicbox_app_native) - Application entry point and routing
• UI Components (moosicbox_app_native_ui) - HyperChad-based UI components
• Bundled Server (moosicbox_app_native_bundled) - Optional embedded server mode
• App State (moosicbox_app_state) - Application state management
• Player (moosicbox_player) - Audio playback functionality
• Music API (moosicbox_music_api) - Multi-source music integration

See Also

• MoosicBox App Native UI - UI component library
• MoosicBox App Native Bundled - Bundled server mode