MoosicBox

A modern, high-fidelity music server and streaming platform for cows

🎵 Listen to your HiFi music anywhere

MoosicBox is a powerful, self-hosted music server that lets you stream your personal music library and access premium music services from anywhere. Built with performance and audio quality in mind, MoosicBox provides a seamless listening experience across all your devices.

📱 Download MoosicBox | 🏠 Visit Website

⚠️ Project Status

Development Notice: This is currently a personal side project in active development. Most features are experimental and may not work as expected. While the goal is to eventually create a stable, user-friendly music app that others can enjoy, the project is not yet ready for general use. Your mileage may vary significantly at this stage.

---

✨ Key Features

🎧 Hi-Fi Audio Experience

• Lossless audio streaming with support for FLAC, ALAC, and other high-quality formats
• Real-time audio encoding (AAC, MP3, Opus) optimized for your connection
• High-resolution audio support for audiophile-grade listening

🌐 Multi-Platform Access

• Web interface - Stream from any browser
• Desktop applications - Native apps for Windows, macOS, and Linux
• Mobile apps - Android (in-progress)
• Cross-device sync - Continue listening where you left off

🎼 Music Service Integration

• Local library - Your personal music collection
• Tidal - Access millions of hi-fi tracks and MQA content
• Qobuz - Studio-quality streaming with large catalog
• Global search across all connected services and local library

🏠 Self-Hosted & Private

• Complete ownership of your music server
• No internet required for local music playback
• Privacy-focused - your data stays on your devices

🔧 Advanced Features

• Multi-zone audio - Play different music in different rooms
• Multiple simultaneous outputs - Stream to multiple devices at once
• Automatic image optimization - Perfect album art for any screen size
• Database flexibility - Support for PostgreSQL, MySQL, and SQLite
• Audio visualization - See waveforms and track progress
• Remote library access - Connect to other MoosicBox servers

---

🚀 Getting Started

Quick Start Options

1. 📱 Download Apps: Get native apps at moosicbox.com/download
2. 🛠️ Self-Host: Set up your own server using the instructions below

Self-Hosting Your MoosicBox Server

Prerequisites

• Rust toolchain (latest stable)

Installation & Setup

1. Clone the repository:

   git clone https://github.com/MoosicBox/MoosicBox.git
   cd MoosicBox

2. Start the server:

   # Default port is 8000
   cargo run -p moosicbox_server
   
   # Or specify a custom port
   PORT=8001 cargo run -p moosicbox_server

3. Access your server:

   • Open your browser to http://localhost:8000 (or your custom port)
   • Start adding your music library and connecting services

Advanced Configuration

Development mode with debugging:

RUST_BACKTRACE=1 RUST_LOG="moosicbox=debug" cargo run -p moosicbox_server

---

🏗️ Architecture

MoosicBox is built with a modular, high-performance architecture:

Core Technologies

• 🦀 Rust - Memory-safe, high-performance backend
• 🌐 Web Technologies - Modern web interface with TypeScript
• 🎨 HyperChad UI Framework - Custom reactive UI system
• 📱 Tauri - Cross-platform desktop applications
• 🔄 Real-time sync - WebSocket-based live updates

Supported Platforms

• 🖥️ Desktop: Windows, macOS, Linux (via Tauri)
• 📱 Mobile: Android
• 🌐 Web: All modern browsers
• 🐧 Server: Linux, Docker, cloud deployments

---

📊 Database Support

MoosicBox supports multiple database backends for maximum flexibility:

• SQLite - Perfect for personal use and getting started
• PostgreSQL - Recommended for production and multi-user setups
• MySQL - Full feature support with basic MySQL compatibility

🔧 Development

MoosicBox is built as a comprehensive Rust workspace with 150+ packages:

Key Development Commands

# Run the main server (default port 8000)
cargo run -p moosicbox_server

# Run with custom port
PORT=8001 cargo run -p moosicbox_server

# Run with debug logging
RUST_LOG="moosicbox=debug" cargo run -p moosicbox_server

# Run tests
cargo test

# Check code quality
cargo clippy --all-targets --all-features

# Format code
cargo fmt

Project Structure

• packages/ - Modular Rust packages (audio, networking, UI, etc.)
• app-website/ - Marketing website source
• kubernetes/ - Kubernetes deployment manifests
• terraform/ - Infrastructure as code

---

📄 License

MoosicBox is licensed under the Mozilla Public License 2.0.

🔗 Links

• 🌐 Website: moosicbox.com
• 📱 Downloads: moosicbox.com/download
• 🐛 Issues: GitHub Issues

---

📦 All Workspace Packages (Click to expand)

Core Application

• moosicbox - Main MoosicBox server application
• moosicbox_server - Core server implementation and HTTP handlers
• moosicbox_server_simulator - Server simulation utilities for testing

Audio & Media

• moosicbox_audio_decoder - Audio decoding with support for multiple formats
• moosicbox_audio_encoder - Audio encoding utilities with feature-gated support
• moosicbox_audio_output - Multi-platform audio output management
• moosicbox_audio_zone - Audio zone database management with CRUD operations
• moosicbox_audio_zone_models - Data models for audio zone management
• moosicbox_player - High-performance audio player with playback controls
• moosicbox_resampler - Audio resampling utilities for format conversion
• moosicbox_downloader - Media downloading and caching system
• moosicbox_opus - Opus codec integration
• moosicbox_opus_native - Native Opus codec bindings
• moosicbox_opus_native_libopus - LibOpus native library
• aconverter - Audio converter helper binary

Music Services Integration

• moosicbox_tidal - Tidal music service integration with comprehensive API
• moosicbox_qobuz - Qobuz hi-fi music service integration
• moosicbox_yt - YouTube Music API integration

Library & Search

• moosicbox_library - Music library management and database operations
• moosicbox_library_models - Core data models for music library
• moosicbox_library_music_api - Music API integration for library
• moosicbox_remote_library - HTTP client for remote music servers
• moosicbox_search - High-performance full-text search engine using Tantivy
• moosicbox_scan - Library scanning and metadata extraction
• moosicbox_scan_models - Data models for library scanning

Music API & Models

• moosicbox_music_api - Unified music API with service integrations
• moosicbox_music_api_api - Core API implementations and endpoints
• moosicbox_music_api_helpers - Helper utilities for music APIs
• moosicbox_music_api_models - Data models for music API
• moosicbox_music_models - Core music data models and types

Application Framework

• moosicbox_app_models - Application data models and structures
• moosicbox_app_state - Application state management system
• moosicbox_app_native - Native application components
• moosicbox_app_native_bundled - Bundled native app service
• moosicbox_app_native_image - Image asset management for native apps
• moosicbox_app_native_ui - Native UI components and widgets

Desktop Application (Tauri)

• moosicbox_app_tauri_bundled - Bundled Tauri application
• moosicbox_app_client - Tauri client utilities and bindings
• tauri_create_config - Tauri configuration generator
• moosicbox - MoosicBox Tauri desktop application
• app-tauri-plugin-player - Tauri plugin for audio player
• moosicbox_app_ws - Tauri WebSocket integration

HyperChad UI Framework

• hyperchad - Core HyperChad UI framework
• hyperchad_actions - Action system for HyperChad
• hyperchad_app - HyperChad application framework
• hyperchad_color - Color utilities and theming
• hyperchad_js_bundler - JavaScript bundling for HyperChad
• hyperchad_router - Client-side routing system
• hyperchad_state - State management for HyperChad
• hyperchad_template - Template system and DSL
• hyperchad_template_actions_dsl - DSL for template actions
• hyperchad_template_macros - Template system macros
• hyperchad_transformer - UI transformation system
• hyperchad_transformer_models - Models for UI transformations

HyperChad Renderers

• hyperchad_renderer - Core rendering abstractions
• hyperchad_renderer_egui - Native desktop renderer using egui
• hyperchad_renderer_fltk - Cross-platform native GUI renderer using FLTK
• hyperchad_renderer_html - Server-side HTML renderer
• hyperchad_renderer_html_actix - Actix Web integration for HTML renderer
• hyperchad_renderer_html_cdn - CDN integration for HTML renderer
• hyperchad_renderer_html_http - Generic HTTP server integration
• hyperchad_renderer_html_lambda - AWS Lambda integration for serverless deployment
• hyperchad_renderer_html_web_server - Web server utilities for HTML renderer
• hyperchad_renderer_vanilla_js - Client-side JavaScript renderer
• hyperchad_renderer_vanilla_js_hash - Content-based hash generation for cache busting

Web & Networking

• moosicbox_web_server - Web server abstraction and utilities
• moosicbox_web_server_core - Core web server functionality
• moosicbox_web_server_cors - CORS middleware for web servers
• switchy_http - Generic HTTP client abstraction
• switchy_http_models - HTTP protocol models and types
• moosicbox_ws - WebSocket utilities and abstractions
• moosicbox_middleware - HTTP middleware collection

Networking & Discovery

• moosicbox_tunnel - Tunneling utilities and protocols
• moosicbox_tunnel_sender - WebSocket-based tunneling client
• moosicbox_tunnel_server - WebSocket-based tunneling server
• switchy_tcp - Generic TCP networking abstraction
• switchy_upnp - UPnP device discovery and communication
• switchy_mdns - mDNS service registration and discovery
• switchy_p2p - Peer-to-peer networking utilities
• moosicbox_load_balancer - Load balancing utilities
• openport - Find free unused network ports

Authentication & Security

• moosicbox_auth - Authentication utilities and client registration
• moosicbox_profiles - User profile management and validation
• moosicbox_session - Session management utilities
• moosicbox_session_models - Data models for session management

Database & Storage

• switchy_database - Database abstraction layer
• switchy_database_connection - Database connection management
• switchy_schema - Database schema and migration framework
• switchy_schema_cli - CLI tool for schema migrations
• moosicbox_schema - Database migration system
• switchy_fs - Cross-platform filesystem abstraction

Utilities & Infrastructure

• moosicbox_config - Configuration utilities for applications
• switchy_env - Environment configuration utilities
• moosicbox_env_utils - Environment variable parsing utilities
• moosicbox_logging - Logging utilities with feature-gated modules
• switchy_telemetry - OpenTelemetry integration for distributed tracing
• moosicbox_async_service - Service framework for async applications
• switchy_time - Time abstraction utilities
• switchy_random - Random number generation utilities
• switchy_uuid - UUID generation and handling utilities

Data Processing & Parsing

• moosicbox_json_utils - JSON parsing utilities and helpers
• moosicbox_parsing_utils - Utilities for parsing integer sequences and ranges
• moosicbox_date_utils - Date parsing and manipulation utilities
• moosicbox_paging - Pagination utilities for data sets
• moosicbox_stream_utils - Byte stream utilities with ByteWriter/ByteStream
• moosicbox_channel_utils - Channel utilities for async communication

Media & Image Processing

• moosicbox_image - Image processing and optimization utilities
• moosicbox_files - File handling and streaming utilities

UI & Interface

• moosicbox_menu - Menu system utilities
• moosicbox_menu_models - Data models for menu system
• moosicbox_admin_htmx - HTMX API endpoints for administrative operations
• moosicbox_marketing_site - Marketing website implementation
• moosicbox_marketing_site_ui - UI components for marketing site

Development & Testing

• simvar - Simulation variable system
• simvar_harness - Simulation testing framework
• simvar_utils - Simulation utilities and helpers
• moosicbox_arb - Arbitrary data generation for testing
• moosicbox_clippier - Workspace analysis and CI generation tool
• clippier_test_utilities - Testing utilities for Clippier
• hyperchad_simulator - HyperChad simulation utilities
• hyperchad_test_utils - HyperChad testing utilities
• switchy_schema_test_utils - Schema testing utilities
• web_server_simulator - Web server simulation utilities
• bloaty - Binary analysis utilities (placeholder)

Core Libraries

• switchy - Feature-gated re-exports for cross-platform compatibility
• switchy_async - Async runtime abstraction
• switchy_async_cargo - Cargo integration for async runtime
• switchy_async_macros - Macros for async runtime
• moosicbox_assert - Conditional assertion macros

Transpiler & Code Generation

• gpipe - General-purpose transpiler framework
• gpipe_ast - Abstract syntax tree for gpipe

Examples & Demos

Note: The workspace includes 25+ example packages demonstrating various features across different domains:

Async & Concurrency

• cancel - Async cancellation examples
• simulated - Simulated async examples

Database & Persistence

• turso_basic - Turso database basic usage
• turso_transactions - Turso transaction handling

Schema & Migrations

• basic_usage - Schema basic usage
• basic_migration_test - Database migration testing
• static_migrations - Static migrations
• borrowed_migrations - Borrowed migrations pattern
• mutation_migration_test - Mutation migrations
• state_migration_test - State migrations

HTTP & Web Server

• simple_get - Simple HTTP GET example
• basic_handler - Basic web server handler example
• basic_handler_standalone - Standalone basic handler
• nested_get - Nested GET routes
• openapi - OpenAPI integration
• from_request_test - Request extraction example
• json_extractor_standalone - JSON extraction
• query_extractor_standalone - Query parameter extraction
• combined_extractors_standalone - Combined extractors
• handler_macro_test - Handler macro testing

Testing & Simulation

• api_testing - API testing with simvar
• basic_web_server - Basic web server with simvar

HyperChad UI

• basic_web_server - HyperChad web server

Filesystem

• temp_dir - Temporary directory usage

For a complete list of examples, see the workspace members in Cargo.toml.