NCW (Native Instruments Compressed Wave) is the lossless audio container used by Kontakt libraries. It is essentially DPCM plus bit truncation, with optional mid/side stereo. This repository is part of a wider reverse engineering effort of proprietary audio formats with maintained research notes in the sibling ni-file-reference repository and private evidence/tooling in ni-file-sources. The historical ni-file repository is retired as an implementation target.
| Crate | What it is |
|---|---|
crates/ncw |
Zero-dependency decoder and PCM16/24 writer library (docs.rs) |
crates/ncw-convert |
NCW/WAV conversion and byte-identical template roundtrips |
Format notes, including what is known and what is still guessed, live in FORMAT.md. Release history is in CHANGELOG.md.
cargo install ncw-convert
ncw-convert sample.ncw sample.wavLibrary usage is documented in the crate README.
The decoder is verified sample-for-sample against the paired reference WAV fixtures in crates/ncw/tests/data (one NCW has no WAV), but those fixtures only exercise part of the format. Several code paths are currently covered by synthetic files that follow the documented formulas rather than by real Kontakt output. If you can produce any of the following from a library you own, please open an issue or pull request with the .ncw and, where possible, the original .wav it was made from:
- Redistributable mid/side fixtures with known PCM. Three private commercial PCM16/24 files now agree with Kontakt decoding and round-trip byte-identically using the template writer. They cannot be committed as test assets. See writer validation.
- A reference WAV for
24-bit-stereo.ncw. The file decodes, but with no original to compare against its test only checks the sample count. - A file with uncompressed blocks. Block header
bits == 0, meaning samples are stored raw at the file's bit depth. Noise or very dense material is the most likely source. - An 8-bit file, if Kontakt can produce one at all.
- A file with more than two channels, to learn how (or whether) mid/side and block layout apply beyond stereo.
- A file with the alternate signature
01 A8 9E D6 30 01 00 00. Both signatures are accepted, but only31has been seen. - Truncated blocks at widths other than 16 and 32. Delta blocks use every width from 2 to 26, but truncated blocks (negative
bits) have only been seen at −16 and −32. An 8-bit or 24-bit file compressed by Kontakt would probably show −8 or −24.
Fixtures do not need to be long: a few thousand samples is enough, and the decoder pads the last block anyway.
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --checkThe minimum supported Rust version is 1.85 (edition 2024) and is checked in CI.
MIT OR Apache-2.0
cargo run -p ncw-convert -- encode input.wav output.ncw
cargo run -p ncw-convert -- roundtrip original.ncw rebuilt.ncw
cargo run -p ncw-convert -- encode decoded.wav rebuilt.ncw --template original.ncwWriting currently supports mono/stereo integer PCM16/24. Auto mode uses mid/side
only when exactly representable and smaller. --mode direct disables it;
--mode mid-side requires it and rejects opposite-parity channel samples.
No clipping or rounding is performed. Output files must not already exist.
Byte identity requires preserving choices WAV does not contain. Template mode retains headers, widths/flags, terminal deltas and padded samples, and rebuilds active audio from PCM. Fresh encoding is deterministic but does not reproduce all NI encoder choices. Float/8-bit/32-bit writing and one-bit delta semantics remain unsupported. See CLI usage and validation/limits.