karavox: an open format for karaoke songs

I’m building an open format for karaoke songs — and a GPL toolkit that produces it. This post is the pitch: why karaoke needs an open format at all, what the format actually is, what works today, and where it’s going.

Karaoke libraries get trapped

A karaoke library is a long-term investment. Mine took years to collect — and it lives in a format whose only player is officially no longer supported: KaraFun’s own page marks the standalone player “no longer supported” and points to the current app — a subscription-streaming product whose release notes discontinue local-file playback (CDG/MP3/MP4). When the player dies, the library is hostage. The format stays undocumented — the KFN container is known only through third-party reverse engineering — and the player stays exclusive.

The escape hatch everyone reaches for is conversion to plain video — I wrote kfn2mp4 myself for exactly that. It works, but MP4 flattens a song into pixels: lyrics can’t be restyled or resized, the key can’t change, alternate audio tracks are dropped, and the original sources are gone. The song becomes a video instead of remaining a song.

The open community has a karaoke format — UltraStar — but it grew out of a karaoke singing game, built for scoring, not for carrying a song. When I looked for an open format that keeps everything, none existed. That’s the gap karavox fills.

The design: boring standards, assembled

karavox doesn’t invent a container. A master file is Matroska — the same proven, royalty-free, codec-agnostic container behind two decades of multimedia — with lyrics as soft ASS subtitle tracks, the tradition anime fansubbing has relied on for twenty years. The work is in naming and specifying what karaoke needs:

Audio in roles and keys. Tracks are tagged instrumental, full, vocals, backing-vocals, guide-melody or click — plus key-shifted variants when a producer deliberately bakes them. Default: one instrumental at original key, pitch-shifted in real time by the player.
Lyrics are data, not pixels. Restylable timed subtitles — colour, font, size, position — that follow key and tempo changes, with fonts embedded so rendering is self-contained.
Everything rides along. Cover art, backgrounds, and the original source files (a Song.ini, a raw .cdg, a MIDI melody) attach verbatim. The round-trip rule: the master alone is enough to reconstruct the source without quality loss.
Two tiers. The rich master (.mkv) is the archival form; an export is a portable MP4 rendering for devices that can’t run a karavox player. Exports are one-way products — the master stays the source of truth.

The toolkit: one binary, your whole shelf

The karavox CLI converts the formats people actually own — KFN (KaraFun), CDG (CD+Graphics), and MIDI karaoke (.kar) — into masters, or straight to portable MP4s when you just want a file that plays anywhere:

karavox convert song.kfn   # KFN → master
  karavox convert disc.cdg   # CDG + audio → master
  karavox convert tune.kar   # MIDI karaoke → master
  karavox mp4 song.kfn       # straight to MP4, no master kept
  karavox probe song.mkv     # inspect + validate against the spec
  karavox export song.mkv    # master → portable MP4

Self-contained Linux and Windows bundles ship with ffmpeg, fluidsynth and a soundfont inside — nothing else to install (pip install karavox if you prefer). Exit codes are stable, --json works everywhere, and karavox check tells you if anything is missing.

The KFN support descends from kfn2mp4 and the prior open reverse-engineering of KaraFun’s container — UlduzSoft’s series among others. karavox is an independent, unofficial interoperability tool: it converts files you already have, and ships no copyrighted content.

Licensed so it can spread

Two licences, deliberately split. The spec is CC-BY-4.0 — anyone, including closed-source players, is free to implement the format. The toolkit is GPL-3.0-or-later. The format only wins if it outlives any single vendor, and it can’t do that if implementing it requires permission.

Honest status

Alpha. The spec is draft 0.1 — stable enough to build on, open enough to change before 1.0. The CLI is not a stable API yet. Tests enforce ≥85% coverage and run in CI on every commit. What’s needed now is not more format theory: it’s implementers — players that read masters, converters that feed them — and real libraries converted in the wild.

Why it matters

Your library outlives any single vendor’s roadmap.
Lyrics stay restylable — bigger, different colour, translated — without re-encoding.
Key changes don’t need pre-baked variants; round-trips don’t lose sources.
It’s open: the spec is readable, implementable, and licensed for anyone.

If you have a karaoke shelf locked into something, convert it — but convert it into a format that can’t lock you out again. Read the spec, grab a release, or star the repository.

Sources: the karavox spec (draft 0.1) · the karavox repository · kfn2mp4 · RFC 9559 (Matroska) · Matroska legal page (royalty-free) · the UltraStar file format · UltraStar Deluxe (the singing game) · KaraFun Player — no longer supported · KaraFun Windows — subscription streaming · UlduzSoft: reverse-engineering the KFN format.