MP3 Output

The MP3Output class in VisioForge SDK provides functionality for configuring MP3 audio output settings in video capture and editing operations. This guide explains how to use the MP3Output class effectively.

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

The MP3Output class implements multiple interfaces:

• IVideoEditXBaseOutput
• IVideoCaptureXBaseOutput
• IOutputAudioProcessor

This makes it suitable for both video editing and capture scenarios where MP3 audio output is needed.

Initialization

To create a new MP3Output instance, you need to provide the output filename:

var mp3Output = new MP3Output("output.mp3");

Audio Settings

The Audio property provides access to MP3 encoder settings:

mp3Output.Audio = new MP3EncoderSettings();
// Configure MP3 encoding parameters through the Audio property

Custom Audio Processing

You can set a custom audio processor using the CustomAudioProcessor property:

mp3Output.CustomAudioProcessor = new MediaBlock();
// Configure custom audio processing if needed

Filename Operations

There are multiple ways to work with the output filename:

// Get the current filename
string currentFile = mp3Output.GetFilename();

// Set a new filename
mp3Output.SetFilename("newoutput.mp3");

// Or use the property directly
mp3Output.Filename = "another.mp3";

Audio Encoders

The MP3Output class supports MP3 encoding exclusively. You can verify the available encoders:

var audioEncoders = mp3Output.GetAudioEncoders();
// Returns an array with a single Tuple containing:
// - "MP3" as the encoder name
// - typeof(MP3EncoderSettings) as the settings type

Best Practices

1. Always initialize the class with a valid output filename.
2. Configure the MP3 encoder settings through the Audio property before starting the encoding process.
3. Use the appropriate interface methods depending on whether you're working with video capture or video editing scenarios.

Example Implementation

Usage in Video Capture SDK:

var core = new VideoCaptureCoreX();
core.Outputs_Add(mp3Output, true);

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

var core = new VideoEditCoreX();
core.Output_Format = mp3Output;

Create a Media Blocks MP3 output instance:

var mp3settings = new MP3EncoderSettings();
var mp3OutputBlock = new MP3OutputBlock("output.mp3", mp3settings);

Windows-only engines (VideoCaptureCore/VideoEditCore)

The MP3Output class is a component of the VisioForge SDK that provides comprehensive configuration options for MP3 audio encoding. This sealed class implements both IVideoCaptureBaseOutput and IVideoEditBaseOutput interfaces, making it suitable for both video capture and video editing scenarios.

Key Features

The class offers fine-grained control over MP3 encoding parameters, including:

• Bitrate configuration (both CBR and VBR)
• Channel mode selection
• Quality settings
• Various MP3 frame flags and tags
• Sample rate configuration
• Special encoding modes

Basic Configuration

CBR_Bitrate

Controls the Constant Bit Rate (CBR) setting for MP3 encoding.

• For MPEG-1 (32, 44.1, 48 kHz): Valid values are 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320 kbps
• For MPEG-2 (16, 22.05, 24 kHz): Valid values are 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160 kbps
• Default values: 128 kbps (MPEG-1) or 64 kbps (MPEG-2)

SampleRate

Specifies the audio sampling frequency in Hz. Common values are:

• 44100 Hz (CD quality, default)
• 48000 Hz (professional audio)
• 32000 Hz (broadcast)
• 22050 Hz (lower quality)
• 16000 Hz (voice)

ChannelsMode

Determines how audio channels are encoded. Options include:

1. StandardStereo: Independent channel encoding with dynamic bit allocation
2. JointStereo: Exploits correlation between channels using mid/side encoding
3. DualStereo: Independent encoding with fixed 50/50 bit allocation (ideal for dual language)
4. Mono: Single channel output (downmixes stereo input)

Variable Bit Rate (VBR) Settings

VBR_Mode

Enables Variable Bit Rate encoding when set to true (default). VBR allows the encoder to adjust bitrate based on audio complexity.

VBR_MinBitrate

Sets the minimum allowed bitrate for VBR encoding (default: 96 kbps).

VBR_MaxBitrate

Sets the maximum allowed bitrate for VBR encoding (default: 192 kbps).

VBR_Quality

Controls VBR encoding quality (0-9):

• Lower values (0-4): Higher quality, slower encoding
• Middle values (5-6): Balanced quality and speed
• Higher values (7-9): Lower quality, faster encoding

Quality and Performance

EncodingQuality

Determines the algorithmic quality of encoding (0-9):

• 0-1: Best quality, slowest encoding
• 2: Recommended for high quality
• 5: Default, good balance of speed and quality
• 7: Fast encoding with acceptable quality
• 9: Fastest encoding, lowest quality

Special Features

ForceMono

When enabled, automatically downmixes multi-channel audio to mono.

VoiceEncodingMode

Experimental mode optimized for voice content.

KeepAllFrequencies

Disables automatic frequency filtering, preserving all frequencies at the cost of efficiency.

DisableShortBlocks

Forces use of long blocks only, which may improve quality at very low bitrates but can cause pre-echo artifacts.

MP3 Frame Flags

Copyright

Sets the copyright bit in MP3 frames.

Original

Marks the stream as original content.

CRCProtected

Enables CRC error detection at the cost of 16 bits per frame.

EnableXingVBRTag

Adds VBR information headers for better player compatibility.

StrictISOCompliance

Enforces strict ISO MP3 standard compliance.

Usage Examples

Basic Stereo MP3 Encoding

var mp3Output = new MP3Output
{
    CBR_Bitrate = 192,
    ChannelsMode = MP3ChannelsMode.StandardStereo,
    SampleRate = 44100,
    VBR_Mode = false
};

Voice-Optimized Encoding

var voiceMP3 = new MP3Output
{
    VoiceEncodingMode = true,
    ChannelsMode = MP3ChannelsMode.Mono,
    SampleRate = 22050,
    VBR_Mode = true,
    VBR_Quality = 4
};

High-Quality Music Encoding

var highQualityMP3 = new MP3Output
{
    VBR_Mode = true,
    VBR_MinBitrate = 128,
    VBR_MaxBitrate = 320,
    VBR_Quality = 2,
    EncodingQuality = 2,
    ChannelsMode = MP3ChannelsMode.JointStereo,
    SampleRate = 48000,
    EnableXingVBRTag = true
};

Apply settings to core instances

var core = new VideoCaptureCore();
core.Output_Filename = "output.mp3";
core.Output_Format = mp3Output;

var core = new VideoEditCore();
core.Output_Filename = "output.mp3";
core.Output_Format = mp3Output;

Serialization

The class supports JSON serialization and deserialization:

// Save settings to JSON
string jsonSettings = mp3Output.Save();

// Load settings from JSON
MP3Output loadedSettings = MP3Output.Load(jsonSettings);

Best Practices

1. For music encoding:

   • Use VBR mode with appropriate quality settings
   • Consider JointStereo for most stereo content
   • Maintain 44.1kHz or 48kHz sample rates

2. For voice encoding:

   • Enable VoiceEncodingMode
   • Consider using mono channel mode
   • Lower sample rates (22.05kHz or 16kHz) are acceptable

3. For compatibility:

   • Enable XingVBRTag when using VBR
   • Use StandardStereo for maximum compatibility
   • Consider CRCProtected for error-sensitive applications

Performance Considerations

The encoding process is influenced by several settings:

1. EncodingQuality has the most significant impact on encoding speed
2. VBR encoding is generally slower than CBR
3. Higher sample rates and bitrates increase processing time
4. JointStereo requires more processing than StandardStereo

Notes on Default Values

The class constructor sets these default values:

• CBR_Bitrate = 192 kbps
• VBR_MinBitrate = 96 kbps
• VBR_MaxBitrate = 192 kbps
• VBR_Quality = 6
• EncodingQuality = 6
• SampleRate = 44100 Hz
• ChannelsMode = MP3ChannelsMode.StandardStereo
• VBR_Mode = true