Metadata-Version: 2.4
Name: karavox
Version: 0.1.0
Summary: Toolkit for the karavox open karaoke format: build, inspect and export masters
Author: Łukasz Nowak
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://karavox.org
Project-URL: Repository, https://github.com/lukenowak/karavox
Project-URL: Changelog, https://github.com/lukenowak/karavox/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/lukenowak/karavox/issues
Keywords: karaoke,kfn,cdg,kar,matroska,ass,subtitles
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=3.4
Requires-Dist: tqdm>=4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Dynamic: license-file

<!-- SPDX-License-Identifier: GPL-3.0-or-later -->

# karavox

[![CI](https://github.com/lukenowak/karavox/actions/workflows/ci.yml/badge.svg)](https://github.com/lukenowak/karavox/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/lukenowak/karavox?include_prereleases)](https://github.com/lukenowak/karavox/releases)
[![PyPI](https://img.shields.io/pypi/v/karavox)](https://pypi.org/project/karavox/)
[![License: GPL-3.0-or-later](https://img.shields.io/github/license/lukenowak/karavox)](https://github.com/lukenowak/karavox/blob/main/LICENSE)
![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)
![Coverage ≥85%](https://img.shields.io/badge/coverage-%E2%89%A585%25%20enforced-brightgreen)

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`](https://github.com/lukenowak/karavox/blob/main/spec/karavox-format.md)
- **Site** — https://karavox.org
- **Format notes** — [`docs/`](https://github.com/lukenowak/karavox/tree/main/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](https://github.com/lukenowak/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](https://github.com/lukenowak/karavox/releases/latest) 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

```bash
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](https://github.com/lukenowak/karavox/blob/main/spec/LICENSE),
  so anyone — including closed-source players — is free to implement the format.
- **Everything else** (toolkit code, docs, site) —
  [GPL-3.0-or-later](https://github.com/lukenowak/karavox/blob/main/LICENSE).
  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](https://github.com/lukenowak/karavox/blob/main/spec/karavox-format.md)
and [`docs/ultrastar-notes.md`](https://github.com/lukenowak/karavox/blob/main/docs/ultrastar-notes.md)):
the [UltraStar file format](https://github.com/UltraStar-Deluxe/format) (versioning scheme,
field tiers, metadata vocabulary — karavox interoperates rather than competes),
[Matroska](https://datatracker.ietf.org/doc/html/rfc9559)/[EBML](https://datatracker.ietf.org/doc/html/rfc8794),
and the [libass](https://github.com/libass/libass)/anime-fansubbing tradition of soft
styled karaoke subtitles, which proved the whole approach.

The converter descends from [kfn2mp4](https://github.com/lukenowak/kfn2mp4); its
reverse-engineering of the KFN formats built on prior open work:

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

[Croonify](https://croonify.com/) 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).
