kima-hub

A self-hosted, on-demand audio streaming platform that brings the Spotify experience to your personal music library.

Kima is built for music lovers who want the convenience of streaming services without sacrificing ownership of their library. Point it at your music collection, and Kima handles the rest: artist discovery, personalized playlists, podcast subscriptions, and seamless integration with tools you already use like Lidarr and Audiobookshelf.

A Note on Native Apps

Once the core experience is solid and properly tested, a native mobile app (likely React Native) is on the roadmap. The PWA works great for most cases for now.

Thanks for your patience while I work through this.

Table of Contents

• Features
  • The Vibe System
  • Playlist Import
• Mobile Support
• Quick Start
• Configuration
• CLAP Audio Analysis
• GPU Acceleration
• Integrations
  • Native Apps (Subsonic)
• Using Kima
  • Using the Vibe System
• Administration
• Architecture
• Roadmap
• License
• Acknowledgments

Features

Your Music, Your Way

• Stream your library - FLAC, MP3, AAC, OGG, and other common formats work out of the box
• Automatic cataloging - Kima scans your library and enriches it with metadata from MusicBrainz and Last.fm, including ISRC codes and genre tags
• Audio transcoding - Stream at original quality or transcode on-the-fly (320kbps, 192kbps, or 128kbps)
• Lyrics - Displays embedded lyrics or fetches them automatically from LRCLIB. Timed lyrics get line-by-line sync during playback; untimed lyrics display as static text. Coverage is good for major artists but varies for niche or independent music*
• Ultra-wide support - Library grid scales up to 8 columns on large displays

Discovery and Playlists

• Made For You mixes - Programmatically generated playlists based on your library:
  • Era mixes (Your 90s, Your 2000s, etc.)
  • Genre mixes
  • Top tracks
  • Rediscover forgotten favorites
  • Similar artist recommendations
• Library Radio Stations - One-click radio modes for instant listening:
  • Shuffle All (your entire library)
  • Workout (high energy tracks)
  • Discovery (lesser-played gems)
  • Favorites (most played)
  • Dynamic genre and decade stations generated from your library
• Discover Weekly - Weekly playlists of new music tailored to your listening habits (requires Lidarr)
• Artist recommendations - Find similar artists based on what you already love
• Artist name resolution - Smart alias lookup via Last.fm (e.g., "of mice" → "Of Mice & Men")
• Discography sorting - Sort artist albums by year or date added
• Deezer previews - Preview tracks you don't own before adding them to your library
• Vibe matching - Find tracks that match your current mood (see The Vibe System)

Podcasts

• Subscribe via RSS - Search iTunes for podcasts and subscribe directly
• Track progress - Pick up where you left off across devices
• Episode management - Browse episodes, mark as played, and manage your subscriptions
• Mobile skip buttons - Jump ±30 seconds on mobile for easy navigation

Audiobooks

• Audiobookshelf integration - Connect your existing Audiobookshelf instance
• Unified experience - Browse and listen to audiobooks alongside your music
• Progress sync - Your listening position syncs with Audiobookshelf
• Mobile skip buttons - Jump ±30 seconds on mobile for easy chapter navigation

The Vibe System

The centerpiece of music discovery in Kima. Your entire library is analyzed by a CLAP neural network and projected into a 2D/3D space where similar-sounding tracks cluster together. The result is a living map of your music collection you can explore, search, and navigate.

Music Map -- the default 2D view. Every track in your library is a point on the map, colored by mood cluster. Zoom and pan to explore. Click any track to inspect it; double-click to play it immediately.

Galaxy View -- the same data rendered as a 3D star field. Orbit, zoom, and fly through your library. Switch between Map and Galaxy with the toggle in the top-left corner.

Drift -- pick any two tracks as start and end points and Kima plots a smooth path through the audio space between them. The resulting queue travels gradually from one sonic neighborhood to the other.

Blend -- add multiple tracks and let Kima find the centroid in audio space. The result is a queue of tracks that blend all of the inputs together into something new.

Additional features:

• Text search - Type any descriptor ("loud and fast", "rainy day piano") to highlight matching tracks on the map
• Right-click context menu - Vibe from any track (similar-track queue), find similar (highlight on map), or start a Drift
• Labels - Toggle track/artist labels on the map
• Keep The Vibe Going - From the player, activate vibe mode to continuously queue tracks that match what's playing

Mood Mixer -- pick a mood preset (Happy, Energetic, Chill, Focus, Party, Acoustic, Melancholy, Sad, Aggressive) to instantly generate a playlist calibrated to that sound. Moods are derived from audio analysis of your actual library, not genre tags.

Playlist Import

Import playlists from Spotify, Deezer, and YouTube, or browse and discover new music directly.

• Spotify Import - Paste any Spotify playlist URL to import tracks
• Deezer Import - Same functionality for Deezer playlists
• YouTube Import - Import from YouTube and YouTube Music playlists
• ISRC Matching - Deterministic track matching via International Standard Recording Codes before falling back to fuzzy text matching
• Smart Preview - See which tracks are already in your library, which albums can be downloaded, and which have no matches
• Selective Download - Choose exactly which albums to add to your library
• Browse Deezer - Explore Deezer's featured playlists and radio stations directly in-app

Native Apps

• OpenSubsonic API - Use any Subsonic-compatible client (Symfonium, DSub, Ultrasonic, etc.) to stream your Kima library
• Standard Subsonic auth - MD5 token auth supported; enter your API token as the password -- works with Amperfy, Symfonium, DSub, and any standard Subsonic client
• Per-client tokens - Generate named API tokens in Settings > Native Apps; revoke them individually when a device is lost or replaced
• Enrichment-aware - Genres and artist biographies exposed to clients come from Last.fm enrichment, not just file tags
• Lyrics, bookmarks, and play queue - getLyrics, bookmarks, and savePlayQueue/getPlayQueue for cross-device resume

Multi-User Support

• Separate accounts - Each user gets their own playlists, listening history, and preferences
• Admin controls - Manage users and system settings from the web interface
• Two-factor authentication - Secure accounts with TOTP-based 2FA

Custom Playlists

• Create and curate - Build your own playlists from your library
• Share with others - Make playlists public for other users on your instance
• Save mixes - Convert any auto-generated mix into a permanent playlist

Mobile and TV

• Progressive Web App (PWA) - Install Kima on your phone or tablet for a native-like experience
• Android TV - Fully optimized 10-foot interface with D-pad/remote navigation
• Responsive Web - Works on any device with a modern browser

Mobile Support

Progressive Web App (PWA)

Kima works as a PWA on mobile devices, giving you a native app-like experience without needing to download from an app store.

To install on Android:

1. Open your Kima server in Chrome
2. Tap the menu (⋮)
3. Select "Add to Home Screen" or "Install app"

To install on iOS:

1. Open your Kima server in Safari
2. Tap the Share button
3. Select "Add to Home Screen"

PWA Features:

• Full streaming functionality
• Background audio playback
• Lock screen and notification media controls (iOS Control Center and Android notifications)
• Offline caching for faster loads
• Installable icon on home screen

Android TV

Kima includes a dedicated interface optimized for television displays:

• Large artwork and readable text from across the room
• Full D-pad and remote navigation support
• Persistent Now Playing bar for quick access to playback controls
• Simplified navigation focused on browsing and playback

The TV interface is automatically enabled when accessing Kima from an Android TV device's browser.

Quick Start

One Command Install

docker run -d \
  --name kima \
  -p 3030:3030 \
  -v /path/to/your/music:/music \
  -v kima_data:/data \
  chevron7locked/kima:latest

That's it! Open http://localhost:3030 and create your account.

With GPU acceleration (requires NVIDIA Container Toolkit):

docker run -d \
  --name kima \
  --gpus all \
  -p 3030:3030 \
  -v /path/to/your/music:/music \
  -v kima_data:/data \
  chevron7locked/kima:latest

What's Included

The Kima container includes everything you need:

• Web Interface (port 3030)
• API Server (internal)
• PostgreSQL Database (internal)
• Redis Cache (internal)

Configuration Options

docker run -d \
  --name kima \
  -p 3030:3030 \
  -v /path/to/your/music:/music \
  -v kima_data:/data \
  -e SESSION_SECRET=your-secret-key \
  -e TZ=America/New_York \
  --add-host=host.docker.internal:host-gateway \
  chevron7locked/kima:latest

Using Docker Compose

Create a docker-compose.yml file:

services:
    kima:
        image: chevron7locked/kima:latest
        container_name: kima
        ports:
            - "3030:3030"
        volumes:
            - /path/to/your/music:/music
            - kima_data:/data
        environment:
            - TZ=America/New_York
        # Required for Lidarr webhook integration on Linux
        extra_hosts:
            - "host.docker.internal:host-gateway"
        restart: unless-stopped

volumes:
    kima_data:

Then run:

docker compose up -d

Updating with Docker Compose:

docker compose pull
docker compose up -d

Bind-mounting /data on Linux

Named volumes are recommended. If you bind-mount /data, make sure required subdirectories exist and are writable by the container service users.

mkdir -p /path/to/kima-data/postgres /path/to/kima-data/redis

If startup logs report a permission error, chown the host path to the UID/GID shown in the logs (for example, the postgres user).

Kima will begin scanning your music library automatically. Depending on the size of your collection, this may take a few minutes to several hours.

Release Channels

Kima offers two release channels to match your stability preferences:

🟢 Stable (Recommended)

Production-ready releases. Updated when new stable versions are released.

docker pull chevron7locked/kima:latest
# or specific version
docker pull chevron7locked/kima:v1.7.3

🔴 Nightly (Development)

Latest development build. Built on every push to main.

⚠️ Not recommended for production - may be unstable or broken.

docker pull chevron7locked/kima:nightly

For contributors: See [CONTRIBUTING.md](CONTRIBUTING