karavox 0.1.0

Toolkit for the karavox open karaoke format: build, inspect and export masters

karavox

The open karaoke format — and the GPL toolkit that produces it.

Status: alpha. The format spec is a draft; the toolkit converts KFN (KaraFun), CDG (CD+Graphics) and .kar (MIDI karaoke) into masters and exports portable MP4s. The CLI is not a stable API yet — commands, flags and JSON output can change or break at any time until 1.0.

A karavox file is a Matroska master carrying everything a karaoke player needs in one file: audio in selectable roles (instrumental, vocals, …) and keys, lyrics as restylable soft ASS subtitles — never burned in — plus fonts, artwork, and the original source files for lossless round-trips.

• Format spec — spec/karavox-format.md
• Site — https://karavox.org
• Format notes — docs/ (UltraStar analysis, format survey, releasing)

Why

I have a karaoke library that took years to collect — locked in a format whose only player is officially no longer updated, by a company that moved on to subscription streaming. My first answer was kfn2mp4: convert everything to plain MP4s that play anywhere. It worked, but it flattens a song into pixels — lyrics can't be restyled, the key can't change, alternate audio tracks get dropped.

The proper fix needed an open format that keeps everything. To my surprise, none existed: the incumbents profit from lock-in, and the open community's format (UltraStar) was built for a scoring game, not for carrying a song. Meanwhile anime fansubbing had quietly proven Matroska + styled soft subtitles for two decades — nobody had named it a karaoke format.

So, karavox: boring, proven standards, assembled and specified — so that no karaoke library gets trapped again. Built for my own shelves first, designed open so it doesn't stop there.

Installation

Download the archive for your system from the latest release and unpack it — then run karavox (Linux: tar xf karavox-linux.tar.gz; Windows: unzip karavox-windows.zip, run karavox\karavox.exe). Everything is inside — ffmpeg, fluidsynth, a GM soundfont, a fallback font — nothing else to install.

Advanced: pip install karavox (Python 3.12+), plus ffmpeg on PATH (fluidsynth only for MIDI audio); karavox check tells you what's missing. Tool overrides: KARAVOX_FFMPEG (directory or binary path, covers ffprobe), KARAVOX_FLUIDSYNTH, KARAVOX_SOUNDFONT, KARAVOX_FONT.

Toolkit

One binary, subcommands (--json everywhere; stdout is data, stderr is logs):

karavox check                      # do the external tools work? (bundled builds: always)
karavox convert song.kfn           # any supported input -> karavox master (song.mkv)
karavox convert disc.cdg           # CDG + sibling audio -> graphics-only master
karavox convert tune.kar           # MIDI karaoke -> master (lyrics from meta-events)
karavox mp4 song.kfn               # one shot: straight to portable MP4, no master kept
karavox probe song.mkv             # inspect + validate against the spec (also .kfn/.cdg/.kar)
karavox export song.mkv            # master -> portable MP4 with burned-in lyrics

Styling (--sung-color … --slots), {title}-style output templates, --logo watermarks, -d previews and --report diagnostics: see karavox <command> --help.

Exit codes are stable (0 ok · 1 error · 2 usage · 3 unsupported input · 4 missing tool).

Development

pip install -e .[dev]
pytest          # branch coverage ≥85% enforced

Tests are fully synthetic — no real karaoke files needed, none accepted.

Legal & disclaimer

An independent, unofficial tool for format interoperability, not affiliated with or endorsed by KaraFun/Recisio; "KaraFun" is a trademark of its respective owners. karavox reads container formats so you can convert files you already have for personal use, and ships no copyrighted content. Recordings, lyrics and artwork inside converted files remain the property of their rights holders — do not use this tool to redistribute copyrighted material.

Licensing

Two licences, cleanly scoped:

• spec/ — CC-BY-4.0, so anyone — including closed-source players — is free to implement the format.
• Everything else (toolkit code, docs, site) — GPL-3.0-or-later. Release binaries additionally contain ffmpeg (GPL build), fluidsynth (LGPL-2.1), the TimGM6mb soundfont (GPL-2) and the Lato font (SIL OFL) — sources available from their projects.

Acknowledgements

Format influences (details in spec/karavox-format.md §10 and docs/ultrastar-notes.md): the UltraStar file format (versioning scheme, field tiers, metadata vocabulary — karavox interoperates rather than competes), Matroska/EBML, and the libass/anime-fansubbing tradition of soft styled karaoke subtitles, which proved the whole approach.

The converter descends from kfn2mp4; its reverse-engineering of the KFN formats built on prior open work:

• UlduzSoft blog — the reverse-engineering series (header, directory, Song.ini, encryption): the authoritative narrative.
• WinslowJosiah — unlock_kfn gist (Python): the cleanest read/decrypt reference (AES-128-ECB with the FLID key).
• gyunaev/spivak — Spivak (C++/Qt): a production karaoke player; lyricsparser_kfn.cpp is the reference for the Sync/Text merge + tokenization.
• MadLord80/KFN_Viewer — KFN_Viewer (C#): a GUI viewer/extractor with the richest field table and an extended-LRC export.
• mazsibazsi/kfn-rs — kfn-rs (Rust): the best-modeled [Eff#] effects/animation layer.

Croonify convinced the author that a standard video container is the proper home for karaoke (MP4 there, grown into the MKV master + MP4 export here).

This project was written with the help of AI tools — the code, tests, and documentation were developed with Anthropic's Claude (Claude Code).