docs.rs failed to build moosicbox_server-0.5.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

MoosicBox Server

The main music server component of MoosicBox - a music streaming server with support for multiple audio sources and formats.

Overview

The MoosicBox Server is the core component that provides:

Music Library Management: Index and serve your local music collection
Multi-Format Audio Support: AAC, FLAC, MP3, Opus encoding on-the-fly
Streaming Sources Integration: Tidal, Qobuz, and YouTube Music support
Multi-Zone Audio: Control playback across multiple devices and zones
Web API: RESTful API with OpenAPI documentation
WebSocket Support: Real-time communication for clients
Database Flexibility: SQLite and PostgreSQL support
Tunnel Integration: Remote access through tunnel server
High-Quality Audio: Hi-Fi audio playback with configurable quality

Dependencies and local evaluation

The default feature set includes native codecs and audio output. Install a native compiler toolchain and pkg-config; codec source builds may also require Autoconf, Automake, and Libtool. On Linux the default CPAL backend needs ALSA development headers. An installed Opus development library can avoid building Opus from source. Optional libvips image support adds libvips dependencies. See this package's and the audio encoder's clippier.toml for CI setup.

For a loopback-only evaluation, run BIND_ADDR=127.0.0.1 cargo run --locked -p moosicbox_server, then open http://127.0.0.1:8000/admin for administration or /health for a health check. The root URL is not the listening-client UI. Connect a separate client for playback. The default bind is otherwise 0.0.0.0; authentication is not a blanket default protection. Review network exposure before remote deployment.

The music server supports SQLite/PostgreSQL configurations. MySQL/DuckDB implementations in Switchy are reusable-library capabilities, not documented end-to-end server configurations.

Installation

From Source

cargo install --path packages/server --features "all-apis,all-formats,all-sources"

Dependency selection

Codec dependencies depend on enabled features; the default server already enables Opus and other formats. They are not optional prerequisites for that default build. See Dependencies and local evaluation.

Usage

Basic Usage

Start the server (defaults to port 8000):

moosicbox_server

Or specify a custom port:

moosicbox_server 8001

Or using cargo:

cargo run --bin moosicbox_server --features "all-apis,all-formats,all-sources" -- 8001

Development Mode

Run with debug logging:

RUST_BACKTRACE=1 RUST_LOG="moosicbox=debug" moosicbox_server 8001

Production Deployment

With tunnel server integration:

WS_HOST="wss://tunnel.moosicbox.com/ws" \
TUNNEL_ACCESS_TOKEN='your_access_token' \
moosicbox_server 8001

Note: STATIC_TOKEN must be set at compile-time when using the static-token-auth feature.

Library API

If you are embedding the server in your own Rust binary, use the exported entry points from moosicbox_server:

run_basic(...) - Starts the server with default optional behavior.
run(...) - Starts the server with full configuration, including optional pre-bound listener and feature-gated player/UPnP/telemetry settings.

use moosicbox_config::AppType;

async fn start() -> std::io::Result<()> {
    moosicbox_server::run_basic(AppType::App, "0.0.0.0", 8000, None, |_| {}).await
}

Configuration

Environment Variables

Variable	Description	Default
`BIND_ADDR`	Network address to bind to	`0.0.0.0`
`PORT`	Service port (can also be passed as first argument)	`8000`
`ACTIX_WORKERS`	Number of Actix worker threads	Auto
`MAX_THREADS`	Maximum blocking threads	`64`
`STATIC_TOKEN`	Static authentication token (compile-time; requires `static-token-auth` feature)	-
`WS_HOST`	WebSocket tunnel host (requires `tunnel` feature)	-
`TUNNEL_ACCESS_TOKEN`	Tunnel server access token (requires `tunnel` feature)	-

Database Setup

SQLite (Default)

No additional setup required. Database file created automatically.

PostgreSQL

# Enable PostgreSQL support with features
cargo run --bin moosicbox_server --features "all-apis,all-formats,all-sources,postgres-sqlx" -- 8001

# Connection string configured via switchy_database_connection
# See documentation for database connection configuration

Features

The server supports various feature flags for customization:

Audio Formats

format-aac - AAC/M4A support (requires OS encoders/decoders)
format-flac - FLAC support (requires OS encoders/decoders)
format-mp3 - MP3 support
format-opus - Opus support (requires OS encoders/decoders)
all-formats - Enable all formats (includes all-os-formats and format-mp3)

Audio Sources

qobuz - Qobuz streaming integration
tidal - Tidal streaming integration
yt - YouTube Music integration
all-sources - Enable all sources

Audio Outputs

cpal - Cross-platform audio library
jack - JACK audio support
asio - ASIO audio support (Windows)

Database

sqlite-sqlx - SQLite support via sqlx (default)
sqlite-rusqlite - SQLite support via rusqlite
postgres-sqlx - PostgreSQL support via sqlx
postgres-raw - PostgreSQL support via raw connections
postgres-openssl - PostgreSQL with OpenSSL
postgres-native-tls - PostgreSQL with native TLS

APIs

admin-htmx-api - Admin web interface with HTMX
audio-output-api - Audio output configuration API
audio-zone-api - Audio zone management API
auth-api - Authentication API
config-api - Configuration API
downloader-api - Download management API
files-api - File serving API
library-api - Local music library API
menu-api - Menu API
music-api-api - Music API integration
player-api - Audio player API
qobuz-api - Qobuz-specific API endpoints
scan-api - Music library scanning API
search-api - Global search API
session-api - Session management API
tidal-api - Tidal-specific API endpoints
upnp-api - UPnP/DLNA API
yt-api - YouTube Music-specific API endpoints
all-apis - Enable all APIs (includes app-apis, player-api, upnp-api)

Additional Features

openapi - Enable OpenAPI documentation endpoints (enabled by default)
tunnel - Enable tunnel server integration for remote access (enabled by default)
static-token-auth - Enable static token authentication
tls - Enable TLS support
telemetry - Enable telemetry and metrics (enabled by default)
profiling - Enable profiling support (enabled by default)
profiling-puffin - Enable Puffin profiler
profiling-tracy - Enable Tracy profiler
profiling-tracing - Enable tracing profiler

API Documentation

When running with the openapi feature, API documentation is available at:

Swagger UI: http://localhost:8001/openapi/swagger-ui/
ReDoc: http://localhost:8001/openapi/redoc/
RapiDoc: http://localhost:8001/openapi/rapidoc/
Scalar: http://localhost:8001/openapi/scalar/
OpenAPI JSON: http://localhost:8001/openapi/api-docs/openapi.json

Library Scanning

The server can automatically scan and index your music library:

# Scan a directory
curl -X POST "http://localhost:8001/scan/run-scan-path?path=/path/to/music"

Multi-Zone Audio

Configure audio zones for different rooms/devices:

# Audio zone API is available at /audio-zone
# Requires the audio-zone-api feature (enabled by default with all-apis)
curl "http://localhost:8001/audio-zone"

Troubleshooting

Common Issues

Port already in use: Choose a different port or stop other services
Permission denied: Ensure user has access to music directories
Database connection failed: Check database URL and credentials
Audio playback issues: Verify audio output configuration

Logs

Enable detailed logging:

RUST_LOG="moosicbox_server=debug,moosicbox_audio=debug" moosicbox_server 8001

moosicbox_server 0.5.0