WavPack encoder

WavPack is a versatile audio codec that supports both lossless and hybrid lossy compression modes. This documentation covers the implementation available in the VisioForge.Core library.

The WavPack encoder provides flexible audio compression with support for various quality levels, correction modes, and stereo encoding options. It can handle multiple channel configurations and offers a wide range of bitrates and sample rates.

Cross-platform WavPack output (X-engines: VideoCaptureCoreX, VideoEditCoreX, Media Blocks)

Basic Configuration

Here's a simple example of configuring the WavPack encoder with default settings using the WavPackEncoderSettings class:

var encoder = new WavPackEncoderSettings
{
    Mode = WavPackEncoderMode.Normal,
    JointStereoMode = WavPackEncoderJSMode.Auto,
    CorrectionMode = WavPackEncoderCorrectionMode.Off,
    MD5 = false
};

Compression Modes

WavPack supports four compression modes, offering different trade-offs between speed and compression efficiency:

public enum WavPackEncoderMode
{
    Fast = 1,      // Prioritizes encoding speed
    Normal = 2,    // Balanced compression (default)
    High = 3,      // Higher compression ratio
    VeryHigh = 4   // Maximum compression
}

Example of setting a high compression mode:

var encoder = new WavPackEncoderSettings
{
    Mode = WavPackEncoderMode.High,
    ExtraProcessing = 1 // Enable better filters for improved compression
};

Rate Control Options

The encoder provides two primary methods for controlling the output quality:

1. Bitrate-based control:

   var encoder = new WavPackEncoderSettings
   {
       Bitrate = 192000 // 192 kbps
   };
   • Supported bitrate range: 24,000 to 9,600,000 bits/second
   • Values below 24,000 disable lossy encoding
   • Enables lossy encoding mode

2. Bits per sample control:

   var encoder = new WavPackEncoderSettings
   {
       BitsPerSample = 16.0 // 16-bit quality
   };
   • Values below 2.0 disable lossy encoding
   • Useful for maintaining consistent quality across different sample rates

Stereo Encoding Options

WavPack provides three Joint Stereo modes for handling stereo content:

var encoder = new WavPackEncoderSettings
{
    JointStereoMode = WavPackEncoderJSMode.Auto // Default
};

Available modes:

• Auto: Automatically selects the best encoding method
• LeftRight: Traditional left/right channel separation
• MidSide: Mid/side encoding for potentially better compression

Correction Mode

WavPack supports a unique hybrid mode where a correction file can be generated alongside the main compressed file:

var encoder = new WavPackEncoderSettings
{
    CorrectionMode = WavPackEncoderCorrectionMode.Optimized,
    Bitrate = 192000 // Required for correction mode
};

Available correction modes:

• Off: No correction file (default)
• On: Generate standard correction file
• Optimized: Generate optimization-focused correction file
• Note: Correction modes only work in lossy encoding mode

Technical Specifications

The encoder supports:

• Sample rates: 6,000 Hz to 192,000 Hz
• Channel configurations: 1 to 8 channels
• Optional MD5 hash storage of raw samples
• Extra processing options for better quality

To check if the encoder is available in your environment:

if (WavPackEncoderSettings.IsAvailable())
{
    // Configure and use encoder
    var encoder = new WavPackEncoderSettings
    {
        Mode = WavPackEncoderMode.Normal,
        Bitrate = 192000,
        MD5 = true
    };
}

Sample Code

Add the WavPack output to the Video Capture SDK core instance:

// Create a Video Capture SDK core instance
var core = new VideoCaptureCoreX();

// Create a WavPack output instance
var wavPackOutput = new WavPackOutput("output.wv");

// Add the WavPack output
core.Outputs_Add(wavPackOutput, true);

Set the output format for the Video Edit SDK core instance:

// Create a Video Edit SDK core instance
var core = new VideoEditCoreX();

// Create a WavPack output instance
var wavPackOutput = new WavPackOutput("output.wv");

// Set the output format
core.Output_Format = wavPackOutput;

Create a Media Blocks WavPack output instance:

// Create a WavPack encoder settings instance
var wavPackSettings = new WavPackEncoderSettings();

// Create a WavPack output instance
var wavPackOutput = new WavPackEncoderBlock(wavPackSettings);

// Add file sink block
var fileSink = new FileSinkBlock("output.wv");

// Connect the WavPack encoder to the file sink
pipeline.Connect(wavPackOutput.Output, fileSink.Input); // pipeline is MediaBlocksPipeline

Quality Considerations

For the best balance of quality and compression:

1. Use Normal or High mode for most content
2. Enable ExtraProcessing when encoding time isn't critical
3. Leave JointStereoMode as Auto unless you have specific requirements
4. Consider using correction mode for archival purposes when using lossy compression

The WavPack encoder provides a robust solution for both archival-grade lossless compression and high-quality lossy compression with the unique ability to later upgrade to lossless quality through correction files.