Chevron7Locked/kima-hub

Kima is a music server you run yourself. Point it at a folder of music and it gives you a web app to play it from, on a computer or a phone, along with podcasts and audiobooks. It also works out how each song sounds and feels, so it can find songs that match and lay your whole library out as a map.

Web app: any modern browser, and it installs to your home screen as an app. iOS app: coming soon to the App Store.

The vibe engine

Kima describes every song three ways and matches songs on all three.

	What it is	Weight
Sound	A list of numbers that an audio model (CLAP, from LAION) produces by listening to the song. Songs that sound alike get similar lists.	1
Feel	How the song feels: calm or intense, bright or dark (its valence and arousal). It is read from the audio and set against the range of your own library, so "calm" means calm for your music.	0.25
Genre	The genres MusicBrainz lists for the song's artist. They count only between songs by different artists, so one artist's songs do not match each other just because they share genres.	0.25

The three make one similarity score. Every vibe feature uses it: similar tracks, recommendations from a track, Song Path, Blend and the ranking of similar artists. A list holds at most 2 songs from one album and 4 from one artist. Searching with words matches on sound only, because a sentence has no feel or genre. Library radio stations are separate and do not use the score. Moods (Upbeat, Melancholic, Calm, Intense and Energetic) are not part of it either; they label songs for mood mixes and for the map's mood buttons.

The map

Open Vibe in the sidebar. Your library appears as a 3D picture laid out from that same score, so songs that match sit close together. The map is laid out once, after your library has been through enrichment. New songs are placed among the others and keep their place; a wipe and re-run lays the whole map out fresh.

Click a star to see the song with four actions: Play, Match Vibe (queue the song and its closest matches), Similar (light up its closest matches on the map) and Song Path. The search box finds songs and artists by name. Song Path and Blend can also start from a description of the sound, such as "quiet piano".

Song Path and Blend

Song Path takes a start and an end, either a song, an artist or a sound, and queues a run of songs that moves from one to the other.

Blend takes songs you want more of and, if you like, songs you want less of, and builds a playlist from the songs that match the first group and not the second.

How it is worked out

After a scan, Kima runs five enrichment steps in the background: artist metadata, mood tags, audio analysis, vibe embeddings (the sound vectors) and similarity (the matches and the map). Settings > Library Enrichment shows their progress. On a 16-core machine running 16 workers, 9,004 songs took 87 minutes with an NVIDIA RTX 4060 Ti and both GPU switches on: about 1 minute per 100 songs. Without a graphics card, an earlier 1.11 build on the same machine took 98 minutes for 8,985 songs, about 1.1 minutes per 100. Fewer cores or workers take longer. Audio analysis reads the last 90 seconds of each song, or the whole song when it is shorter. The sound vector comes from five 10-second samples spread across the song. Both audio models run on ONNX Runtime on the processor, and an optional switch moves them to an NVIDIA graphics card; see docs/gpu.md.

Features

Each update opens with a short list of what changed and, sometimes, a note from Kevin; every line opens its own page with the buttons and links for it.

Your library

• Your files. Reads MP3, FLAC, M4A, AAC, OGG, Opus, WAV, WMA, APE and WV files, and identifies them with MusicBrainz: first by a MusicBrainz tag in the file, then by the album's track list and a title-checked name search, and last by an AcoustID audio fingerprint.
• Streaming quality. Play the original file, or have Kima convert it on the fly to 320, 192 or 128 kbps.
• Lyrics. Shows lyrics stored in the file, or fetches them from LRCLIB. Timed lyrics follow along with the song.
• Playlists. Make them private or public to the other accounts on your server, drag to reorder, or share one as a link that opens without an account.
• Stats. A page on what you replay most, which artists make up most of your listening and how much of your library you have never played.

Finding something to play

• Mood mixes. Pick one of five moods and Kima builds a playlist from the songs that fit.
• Made for you and radio. Generated mixes on the home page, and one-click radio stations: shuffle everything, high energy, lesser-played, most played, and stations for your common genres and decades.
• Similar artists. Taken from ListenBrainz, with Deezer as a fallback, and ranked toward your library. Each one shows how many of their albums you own.
• Weekly discovery. Weekly playlists of music you do not own, built from similar artists and downloaded through Lidarr or Soulseek.

Podcasts and audiobooks

• Podcasts. Search for a show, subscribe, and Kima streams episodes from the show's own feed and remembers your place across devices.
• Audiobooks. Connect an Audiobookshelf server and listen alongside your music. Your position is saved back to it.

Getting music

• Lidarr. Request an album you do not own, and Kima adds it when Lidarr finishes the download.
• Soulseek. Search the network and download from it, through Kima's own connection or your slskd server.
• Playlist import. Bring in playlists from Spotify, Deezer, YouTube, YouTube Music, SoundCloud, Bandcamp and Mixcloud, or an M3U file. Kima matches each track to your library and can send the missing ones to your download source.

Accounts and apps

• Several users. Each account has its own plays, playlists and settings. The first account is the administrator, and any account can turn on two-factor authentication.
• Other apps. Kima speaks the OpenSubsonic API, so Subsonic music apps can play from it. Each app gets its own token, which you can revoke.
• Scrobbling. Optionally send your plays to your own ListenBrainz account.
• TV. Kima switches to a layout for remote controls on Android TV, Fire TV and Google TV browsers.

Requirements

• Docker, on a linux/amd64 or linux/arm64 machine.
• A folder of music.
• Memory: each audio analysis worker needs about 1 to 1.5 GB, and up to 2 to 3 GB at its peak. The example Compose file limits the container to 6 GB. On a small machine, lower the worker count in Settings > Library Enrichment.
• A modern web browser.
• Optional: an NVIDIA graphics card (see docs/gpu.md), and Lidarr, Audiobookshelf or slskd if you use those features.

Quick start

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

Open http://localhost:3030 and create your account. The first account becomes the administrator. When setup finishes, Kima scans your music and starts enrichment.

The same thing as a Compose file:

services:
    kima:
        image: chevron7locked/kima:latest
        container_name: kima
        ports:
            - "3030:3030"
        volumes:
            - /path/to/your/music:/music
            - kima_data:/data
        extra_hosts:
            - "host.docker.internal:host-gateway"
        restart: unless-stopped

volumes:
    kima_data:

/data holds the database, the caches and the secrets Kima generates on its first start. Back it up: without it you lose your users, playlists and play history, and the credentials you saved in Settings can no longer be read.

To update, run docker compose pull and then docker compose up -d. docs/install.md covers the other Compose files, bind-mounting /data, pre-release images and installing Kima on a phone.

Configuration

Most things are set in the web app, under Settings. In the all-in-one image the two secrets, SESSION_SECRET and SETTINGS_ENCRYPTION_KEY, are created for you. These environment variables are the ones you are most likely to want:

Variable	What it does
SECURE_COOKIES	Set to true when Kima is served over HTTPS.
ALLOWED_ORIGINS	Comma-separated origins allowed to call the API from a browser. Unset allows any.
KIMA_CALLBACK_URL	The address Lidarr uses to reach Kima.
LOG_LEVEL	debug, info, warn, error or silent.
DISABLE_CLAP	Set to true to stop the sound-vector analyzer. The vibe features then do not work.

Every variable, the ports and the storage paths are in docs/configuration.md.

Documentation

Guide	What it covers
Install and update	Every Compose file, updating, stable and pre-release images, phones and TVs
Using Kima	A tour of the web app and its keyboard shortcuts
Configuration	Settings, environment variables, ports and storage paths
Administration	Enrichment, users, job queues, backups and logs
Integrations	Lidarr, Soulseek, Audiobookshelf, ListenBrainz and playlist import
Subsonic clients	Connecting other music apps
NVIDIA GPU	Moving the audio models onto a graphics card
Security	Secrets, sign-in, and opening Kima to the internet
Development	Running from source, tests and releases
Privacy	What Kima sends to outside services
Changelog	What changed in each version

Kima has no telemetry or analytics, and the author receives nothing from your install. PRIVACY.md lists each outside service your server contacts and what it sends.

Contributing

Bug reports and questions go to GitHub Issues; include your Kima version and the output of docker logs kima. To change the code, read CONTRIBUTING.md, then docs/development.md for running Kima from source and the checks a pull request must pass.

Licence

Kima is released under the GNU General Public License v3.0.

The feel weights in backend/src/services/matching/feelProbe.json are derived from the DEAM dataset (Aljanaki, Yang & Soleymani, PLOS ONE 2017), which its authors release under Creative Commons BY-NC. That file is licensed under those terms and credited to DEAM; the rest of Kima stays under the GPL.

Acknowledgements

Kima builds on these projects and services:

• MusicBrainz, Cover Art Archive and Wikidata for metadata, artwork and artist biographies
• ListenBrainz for similar artists, charts and open scrobbling
• AcoustID for audio-fingerprint identification
• Deezer for similar artists, artwork and playlist browsing, and Fanart.tv for artist images
• LRCLIB for lyrics
• Apple's iTunes Search API for podcast search
• Odesli (song.link) for resolving links from other music services during playlist import, and yt-dlp for reading playlist links
• LAION CLAP for the sound model, and Essentia with its MusiCNN models for audio analysis
• DEAM for the human valence and arousal ratings behind the feel part of matching
• UMAP (McInnes, Healy and Melville) for the method behind the map's layout
• Lidarr, Audiobookshelf and slskd for the services Kima connects to