kahawai

kah-hah-why · Hawaiian for stream; in te reo Māori, a strong fish of strong water

A self-hosted server for streaming your own movies, series, anime and music. It plays the file as it is whenever it can, and when it can't, it changes only the stream that's in the way.

pre-release Latest: v0.0.20-rc.1 MIT licensed Rust + GStreamer

Because my library was almost, but not quite, what media servers expect.

My collection is the messy kind: fansub anime with carefully typeset ASS subtitles and their own fonts, Blu-ray rips with image-based subtitles, HDR sources, and a lot of music. It lives on a low-power NAS, while the hardware that can actually transcode sits in a different machine.

The existing servers mostly cope. But "mostly" meant subtitles flattened to plain text, an entire film transcoded because one audio track didn't fit, a transcoder that had to sit on the same box as the disks, and anime matched by guessing at file names when a hash could say exactly what the file is.

So I started again, from a few rules I wasn't willing to bend: never touch the media files; decide from what was measured, never from what was assumed; do the least work that gives a correct result; and let storage and compute live wherever they already are.

Your media, played as it is, from wherever it lives.

Where they're ahead, honestly: years of maturity, a large community, clients on almost every platform, plugins, and live TV and DVR, which Kahawai doesn't do at all. Kahawai is pre-release software, and it isn't trying to be a drop-in replacement for any of them.

Heads up. Kahawai is in active development and only ships release candidates so far. Expect breaking changes between versions, and keep a backup of your hub (kahawai hub backup) before upgrading.

1. Make a home for its state

   Three persistent directories: configuration, data and cache.

   shell

   mkdir -p runtime/config/kahawai runtime/data runtime/cache

2. Describe your media

   Save this as runtime/config/kahawai/kahawai.toml. Each collection is a media type (movies, series, anime or music) and the folders it lives in, as seen from inside the container.

   kahawai.toml

   [all_in_one]
   transcoder = true
   
   [hub]
   bind = "0.0.0.0:8420"
   satellite_bind = "0.0.0.0:8421"
   
   [mediahost]
   name = "local"
   
   [[mediahost.collections]]
   name = "movies"
   media_type = "movies"
   roots = ["/media/movies"]
   
   [[mediahost.collections]]
   name = "series"
   media_type = "series"
   roots = ["/media/series"]

3. Start the container

   Replace /srv/media with wherever your media is. It's mounted read-only. Port 8421 is only needed if you'll attach satellites later.

   docker run -d \
     --name kahawai \
     --restart unless-stopped \
     --device=/dev/dri:/dev/dri \
     -p 127.0.0.1:8420:8420 \
     -p 8421:8421 \
     -v "$PWD/runtime/config:/config" \
     -v "$PWD/runtime/data:/data" \
     -v "$PWD/runtime/cache:/cache" \
     -v /srv/media:/media:ro \
     iksteen/kahawai:0.0.20-rc.1

   Intel or AMD--device=/dev/dri:/dev/dri

   NVIDIA--gpus all, with the NVIDIA Container Toolkit

   No GPUleave the device out; it encodes in software

   Curious what your hardware can do? doctor lists every decode, encode, remux and tone-mapping path it finds.

   shell

   docker run --rm --device=/dev/dri:/dev/dri iksteen/kahawai:0.0.20-rc.1 doctor

4. Create the first administrator

   This goes through a private control socket inside the container, so the public address never offers a way to claim your server.

   shell

   docker exec -it kahawai kahawai hub init-admin

5. Open it

   Go to http://localhost:8420, sign in, and build your libraries from the collections it found. Before you let anything outside the machine reach it, put a TLS reverse proxy in front.

yay -S kahawai      # or: paru -S kahawai
sudoedit /etc/kahawai/kahawai.toml
sudo systemctl enable --now kahawai
sudo -u kahawai kahawai --config /etc/kahawai/kahawai.toml hub init-admin