miko-rs

A lightweight, high-performance Subsonic-compatible music server written in Rust.

Features

• 🚀 High Performance & Tiny Footprint: Built with Rust for maximum efficiency.
• 🎨 Modern Web UI: Fascinating web-based dashboard and control panel for easy management.
• ☁️ Online Music Integration: Support for online music (downloader/scraper) via extensions (TODO).
• 📻 Subsonic & OpenSubsonic: Fully compatible and tested with clients like Feishin, Airsonic, Submariner, Musiver (音流), and Amcfy Music (箭头音乐).
• 💻 Cross-Platform: Run it anywhere—supports multiple operating systems (Linux, macOS, Windows) and architectures (ARM64, x86_64, etc.).
• 🔒 Enhanced Security:
  • Traditional Auth: Supports Subsonic's password and token-based (salted MD5) authentication via the /rest/ prefix.
  • JWT Auth: Modern JSON Web Token authentication for web clients via the /api/ prefix.

Subsonic API Implementation Status

This project implements the Subsonic API (version 1.16.1) to support various music clients (e.g., Symfonium, Dsub, Amuse).

• System
  • ping
  • getLicense
  • getOpenSubsonicExtensions
• Browsing
  • getMusicFolders
  • getIndexes
  • getMusicDirectory
  • getGenres
  • getArtists
  • getArtist
  • getAlbum
  • getSong
  • getArtistInfo
  • getArtistInfo2
  • getAlbumInfo
  • getAlbumInfo2
  • getSimilarSongs
  • getSimilarSongs2
  • getTopSongs
  • getVideos
  • getVideoInfo
• Media Retrieval
  • stream
  • download
  • getCoverArt
  • getLyrics
  • getLyricsBySongId
  • getAvatar
  • hls.m3u8
  • getCaptions
• Playlists
  • getPlaylists
  • getPlaylist
  • createPlaylist
  • updatePlaylist
  • deletePlaylist
• Scanning
  • getScanStatus
  • startScan
• Searching
  • search
  • search2
  • search3
• User Management
  • getUser
  • getUsers
  • createUser
  • updateUser
  • deleteUser
  • changePassword (Disabled for security; use Web UI)
• Lists
  • getAlbumList
  • getAlbumList2
  • getRandomSongs
  • getSongsByGenre
  • getNowPlaying
  • getStarred
  • getStarred2
• Annotation
  • star
  • unstar
  • setRating
  • scrobble
• Bookmarks
  • getBookmarks
  • createBookmark
  • deleteBookmark
  • getPlayQueue
  • savePlayQueue
• Chat
  • getChatMessages
  • addChatMessage

OpenSubsonic Extensions

• Multi-Artist Support: For songs and albums, an artists field is included in the response. This field provides a structured list of all artists associated with the item, which is particularly useful for tracks with multiple contributors.
  • Format: artists: [{"id": "artist_id", "name": "Artist Name"}, ...]
• Extended Lyrics: Supports getLyricsBySongId for better lyrics compatibility with modern clients.
• Incremental Scanning: startScan is incremental by default. It only scans for new or modified files.
  • To trigger a full re-scan, append fullScan=true to the request.

---

Installation

Prerequisites

• Docker and Docker Compose installed on your system.
• A directory containing your music collection.

Using Docker Compose (Recommended)

The easiest way to run miko-rs is using Docker Compose. Create a docker-compose.yml file with the following content:

services:
  miko-rs:
    image: ghcr.io/stkevintan/miko.rs:latest
    container_name: miko-rs
    restart: unless-stopped
    ports:
      - "8081:8081"
    environment:
      - PORT=8081
      - DATABASE_URL=sqlite:///app/data/miko.db
      - SUBSONIC_DATA_DIR=/app/data
      - JWT_SECRET=your_secret_key_here
      - PASSWORD_SECRET=your_password_salt_here
    volumes:
      - ./data:/app/data
      - /path/to/your/music:/music:ro

Configuration

• PORT: The port the server will listen on inside the container (default: 8081).
• DATABASE_URL: Path to the SQLite database file (e.g., sqlite:///app/data/miko.db).
• SUBSONIC_DATA_DIR: Folder where the server stores application data (e.g., /app/data).
• JWT_SECRET: A secret string for signing JWT tokens.
• PASSWORD_SECRET: A secret string used as a salt for password hashing.
• Volumes:
  • /app/data: Stores the SQLite database and search indexes.
  • /music: Map your local music directory to this path (read-only recommended).

Running with Docker

You can also run it directly using the Docker CLI:

docker run -d \
  --name miko-rs \
  -p 8081:8081 \
  -e JWT_SECRET=mysecret \
  -e PASSWORD_SECRET=mysalt \
  -e SUBSONIC_DATA_DIR=/app/data \
  -v $(pwd)/data:/app/data \
  -v /path/to/your/music:/music:ro \
  ghcr.io/stkevintan/miko.rs:latest

Once the service is running, access the Web UI at http://<your-server-ip>:8081 to configure your music folders and user accounts.

Default Credentials:

• Username: admin
• Password: adminpassword

Warning

For security reasons, it is strongly recommended to change the default password immediately after your first login.

The subsonic service will also be available at the same endpoint.

---

Development

Prerequisites

• Rust (latest stable)
• Node.js (>=20)
• pnpm (>=10)
• Sea-ORM CLI (optional, for migrations)

Setup

1. Clone the repository:

   git clone https://github.com/stkevintan/miko-rs
   cd miko-rs

2. Configure Environment: Create a .env file in the root directory:

   DATABASE_URL=sqlite://miko.db?mode=rwc
   PORT=3334
   PASSWORD_SECRET=your-32-character-secret-here
   JWT_SECRET=your-32-character-secret-here
   SUBSONIC_DATA_DIR=./data

3. Install Frontend Dependencies:

   pnpm install

Running Locally

To develop with hot-reloading for the frontend and automatic proxying to the backend:

1. Start the Backend:

   cargo run

   The backend will start on http://localhost:3334.

2. Start the Frontend (Dev Mode):

   pnpm dev

   The frontend will be available at http://localhost:8081. It is configured to proxy /api and /rest requests to your local backend.

Production Build

To build the project for production (embedding the frontend into the Rust binary):

1. Build the Frontend:

   pnpm build

   This generates the static files in the dist/ directory.

2. Build the Backend:

   cargo build --release

   The static files from dist/ are embedded into the resulting binary using rust-embed.

Multi-Platform Build

A helper script is provided for cross-platform builds:

./scripts/build.sh