Crate ncw 

Native Instruments NCW Audio File Format

Description

NCW (Native Instruments Compressed Wave) is a lossless compression algorithm developed by Native Instruments which is essentially DPCM and bit truncation.

This is a zero-dependency Rust library to decode NCW files and to write mono/stereo PCM16/24 NCW files. It is part of a wider reverse engineering effort of proprietary audio formats.

The repository also ships ncw-convert, a command-line NCW/WAV converter built on this crate.

Requirements

• Rust 1.85 or higher (edition 2024)

Usage

use ncw::{NcwReader, SampleFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = std::fs::File::open("sample.ncw")?;
    let mut ncw = NcwReader::read(input)?;

    println!("channels: {}", ncw.header.channels);
    println!("sample_rate: {}", ncw.header.sample_rate);
    println!("bits_per_sample: {}", ncw.header.bits_per_sample);

    // Samples are interleaved i32 in plain channel order; mid/side encoded
    // blocks are converted to left/right for you. PCM files give
    // sign-extended integers at the file's bit depth; float files give raw
    // f32 bit patterns.
    for sample in ncw.decode_samples()? {
        match ncw.sample_format {
            SampleFormat::Pcm => println!("{sample}"),
            SampleFormat::Float => println!("{}", f32::from_bits(sample as u32)),
        }
    }
    Ok(())
}

Writing PCM

encode_pcm(samples, PcmSpec, StereoMode) returns NCW bytes for mono/stereo PCM16/24. write_pcm writes those bytes to a Write stream. encode_pcm_with_template(samples, spec, original_bytes) preserves original encoding metadata while rebuilding the active sample payload. It validates table framing, rejects unsupported flags/zero-width or one-bit delta blocks, and errors if replacement PCM cannot fit the original block widths or exact sum/difference transform. See the repository’s WRITER_VALIDATION.md for independent Kontakt evidence and remaining coverage limits. Float writing is not implemented.

Contribution

Pull requests are welcome. If you have Kontakt libraries at hand, the most valuable contribution right now is test material: see the Help wanted section of the repository README.

License

Licensed under either MIT or Apache-2.0, at your option.

Structs

BlockHeader

The 16-byte header that precedes each per-channel block.

NcwHeader

The parsed fields of the 120-byte file header. The sample-format word at offset 32 is not exposed here; template writing preserves the full header.

NcwReader

Reader for an NCW file.

PcmSpec

Parameters for integer PCM writing. The initial writer supports mono/stereo 16/24-bit PCM.

Enums

ChannelEncoding

NcwError

SampleFormat

StereoMode

Stereo transform selection for newly encoded blocks.

Constants

SAMPLES_PER_BLOCK

Every block holds this many samples for one channel. The final block of a file is padded up to this size.

Functions

encode_pcm

Encode interleaved PCM to a new NCW. Unknown main-header bytes are initialized to zero. This is a deterministic encoder, not a reproduction of NI’s block selection policy.

encode_pcm_with_template

Re-encode PCM using an existing NCW’s encoding choices. The template supplies opaque headers, block widths/flags, unused terminal deltas and padded tail samples. Active audio payloads are reconstructed from samples, never copied. Rejects unsupported flags, malformed framing and values that do not fit the template. Supports raw and delta blocks for mono/stereo PCM16/24. Does not clip, round or normalize samples.

write_pcm

Write encoded bytes to any output stream.