Koko is a (WIP) self-hosted media server written in Rust. At this point in time this is a learning project, and you SHOULD NOT use this for any purpose. I don't know what I am doing and the code is probably terrible. This is also NOT a functioning media server yet. Once it is, I will update this README.
Current product direction highlights:
- The browser UI is targeting a Kodi/Plex-style media-first experience.
- TheMovieDB is the first planned online metadata source for movies and TV.
- Packaged builds include
ffmpegandffprobefrom LizardByte/build-deps. Explicit executable paths remain configurable. - macOS packages require macOS 15.0 or later.
If you are interested in this project, please leave a star and watch the repository for updates.
If you would like to contribute, please reach out on our discord server. Contributor references are available in contributing.
Koko uses a YAML configuration file for core server settings.
Media libraries are stored in the application database instead of the YAML file. The browser settings UI edits server settings in YAML and library definitions in the database.
To move a library, move its files, update the existing library's paths in Settings → Libraries, and rescan it. Keep the same library to retain matched metadata, reading and playback progress, and playlists. Check that the new paths are accessible to the server before scanning. Deleting the library and creating a new one starts a separate catalog.
Open an item to find More like this, when related items are available in your accessible libraries. The row shows the same kind of item: albums lead to albums and artists to artists. Suggestions are unavailable for individual songs, TV seasons, and episodes; open their album, artist, or show page instead. After adding files, scan their library so they can appear here. To update suggestions, refresh the item's metadata from its management controls, or ask your server administrator. The row stays hidden when no similar items are available.
For movie library naming guidance, see Movie naming guidelines. For folder layouts and embedded tags, see Music naming. For library setup, metadata providers, and playback, see Music libraries. For book and audiobook folders, supported formats, reading and listening controls, and metadata sources, see Books, audiobooks, and comics.
The file must be named settings.yml and be placed in the following location, depending on your OS.
| OS | Location |
|---|---|
| Linux | $XDG_CONFIG_HOME/Koko |
| macOS | $HOME/Library/Application Support/Koko |
| Windows | %LOCALAPPDATA%\Koko |
Only the non default values need to be set in the configuration file. An example with all the default values is shown below.
---
general:
data_dir: 'data'
server:
use_https: true
address: '127.0.0.1'
port: 9191
cert_path: 'cert.pem'
key_path: 'key.pem'
use_custom_certs: false
metadata:
providers:
- id: 'tmdb'
enabled: true
api_key: ''
language: 'en-US'Local cargo build, cargo run, and cargo test prepare ffmpeg and ffprobe automatically from
the release tag matching the current third-party/build-deps submodule commit. Initialize that submodule
with git submodule update --init third-party/build-deps. Git, curl, and tar must be available on PATH.
Downloads are cached in Cargo's build output directory; CI bundles tools from that same package.
To update the dependency, check out a different published release tag in the submodule.
Packaged builds resolve omitted FFmpeg paths from ffmpeg/bin beside the Koko executable. Local builds
also search the package prepared by Cargo. Explicit ffmpeg_path and ffprobe_path settings take precedence.
Set KOKO_FFMPEG_ROOT to an extracted build-deps package's ffmpeg directory to use locally built tools.
For an offline build, use that override or set CARGO_NET_OFFLINE=true with an already cached package.
Set KOKO_SKIP_FFMPEG_DOWNLOAD=1 to use tools supplied separately through settings or PATH.
Flatpak uses packaging/linux/flatpak/modules/ffmpeg.json, matching Sunshine's downloads and extraction
into /app/ffmpeg. Its launcher adds /app/ffmpeg/bin to PATH, and its offline build skips Cargo's download.
The shared update workflow advances the build-deps submodule and refreshes the Flatpak module together.
This list is not all-inclusive, and just meant to be a very high level for the initial design.
- Branding
- Koko logo
- Koko banner
- Tray icons for different states/activity
- Publishing (enabling readme badges as required)
- GitHub Releases
- Docker/GHCR
- Flathub
- Winget
- LizardByte/Homebrew
- LizardByte/pacman-repo
- Localization and CrowdIn integration
- Unit Testing
- doc tests
- Coverage
- Settings/Config
- Notification System
- System Notifications
- Discord
- Webhooks
- Database
- Backend
- Authentication
- API
- Certs/SSL
- Media Scanner
- Media Player
- Legal/Licensing info on dependencies
- Frontend
- Home
- Media
- Settings
- Dashboard
- System Info
- CPU Usage
- Memory Usage
- Disk Usage
- Network Usage
- GPU Usage
- Play history
- Media Player
- User Management
- Legal/Licensing info on dependencies
- Plugin system
- User Documentation
- Publish docs to ReadTheDocs
- Media
- Live TV
- DVR/Tuner
- Video
- Movies
- TV Shows
- Videos
- Audio
- Albums/Music
- Podcasts
- Audiobooks
- Images
- Photos
- Books
- Ebooks
- PDFs
- Comics
- Games (Pipe Dream)
- Spin up on-demand game servers (containers or VMs)
- Live TV