Table of Contents

Class AudioLevelEventArgs

Namespace
VisioForge.Core.Types.Events
Assembly
VisioForge.Core.dll

Provides data for audio level events, containing audio level information for individual channels and overall average values.

public class AudioLevelEventArgs : EventArgs

Inheritance

Inherited Members

Examples

// Event handler for audio level monitoring
void OnAudioLevel(object sender, AudioLevelEventArgs e)
{
    // Display overall average level
    Console.WriteLine($"Average Level: {e.Average}% ({e.AverageDb} dB)");

    // Display individual channel levels
    for (int i = 0; i < e.ChannelLevels.Length; i++)
    {
        Console.WriteLine($"Channel {i}: {e.ChannelLevels[i]}% ({e.ChannelLevelsDb[i]} dB)");
    }

    // Check timestamp if available
    if (e.Timestamp != TimeSpan.Zero)
    {
        Console.WriteLine($"Timestamp: {e.Timestamp}");
    }
}

Remarks

This event args class is used to report audio levels during audio processing, playback, or recording operations. Audio levels are provided in both percentage (0-100) and decibel (dB) formats for flexibility in different use cases. The class supports multi-channel audio with individual level information for each channel.

Constructors

AudioLevelEventArgs(byte[], float[], byte, float)

Initializes a new instance of the VisioForge.Core.Types.Events.AudioLevelEventArgs class with specified audio level values.

public AudioLevelEventArgs(byte[] channelLevels, float[] channelLevelsDb, byte average, float averageDb)

Parameters

channelLevels byte[]

An array containing the audio level for each channel as percentage values (0-100). The array length determines the number of audio channels being reported.

channelLevelsDb float[]

An array containing the audio level for each channel in decibels (typically -∞ to 0 dB). Must have the same length as channelLevels.

average byte

The average audio level across all channels as a percentage value (0-100).

averageDb float

The average audio level across all channels in decibels (typically -∞ to 0 dB).

Examples

// Create audio level event args for stereo audio
byte[] levels = new byte[] { 75, 80 };  // 75% left, 80% right
float[] levelsDb = new float[] { -6.0f, -4.5f };  // -6 dB left, -4.5 dB right
var args = new AudioLevelEventArgs(levels, levelsDb, 77, -5.2f);

Remarks

This constructor is typically used by audio processing components to report measured audio levels. The arrays for channel levels should have matching lengths to ensure consistent data.

Exceptions

ArgumentNullException

Thrown when channelLevels or channelLevelsDb is null.

AudioLevelEventArgs(int)

Initializes a new instance of the VisioForge.Core.Types.Events.AudioLevelEventArgs class with empty arrays for the specified number of channels.

public AudioLevelEventArgs(int channels)

Parameters

channels int

The number of audio channels to initialize arrays for. Must be greater than 0.

Examples

// Initialize for 6-channel (5.1 surround) audio
var args = new AudioLevelEventArgs(6);
// Arrays are now allocated but contain default values
// Populate the arrays later:
args.ChannelLevels[0] = 85;  // Front left
args.ChannelLevelsDb[0] = -3.5f;
// ... set other channels

Remarks

This constructor creates empty arrays for channel level data that can be populated later. It is useful when the number of channels is known but the level data will be filled in subsequently. The VisioForge.Core.Types.Events.AudioLevelEventArgs.Average and VisioForge.Core.Types.Events.AudioLevelEventArgs.AverageDb properties are initialized to their default values (0).

Exceptions

ArgumentOutOfRangeException

Thrown when channels is less than or equal to 0.

Properties

Average

Gets or sets the average audio level across all channels as a percentage value.

public byte Average { get; set; }

Property Value

byte

Remarks

This value provides a quick reference for overall audio activity without needing to process individual channels. It is useful for simple level meters or threshold-based audio detection.

AverageDb

Gets or sets the average audio level across all channels in decibels (dB).

public float AverageDb { get; set; }

Property Value

float

Remarks

This provides the average level in a logarithmic scale, which is more suitable for professional audio applications and level matching between different audio sources.

ChannelLevels

Gets or sets the audio levels for each channel as percentage values.

public byte[] ChannelLevels { get; set; }

Property Value

byte[]

Remarks

For stereo audio, index 0 typically represents the left channel and index 1 represents the right channel. For multi-channel audio (e.g., 5.1 surround), the channel mapping follows standard audio conventions.

ChannelLevelsDb

Gets or sets the audio levels for each channel in decibels (dB).

public float[] ChannelLevelsDb { get; set; }

Property Value

float[]

Remarks

Decibel values provide a logarithmic representation of audio levels, which better matches human perception of loudness. A value of -6 dB represents approximately half the perceived loudness of 0 dB. Values below -60 dB are typically considered effectively silent.

Timestamp

Gets or sets the timestamp indicating when this audio level measurement was taken.

public TimeSpan Timestamp { get; set; }

Property Value

TimeSpan

Remarks

This property is optional and may not be populated in all scenarios. When available, it allows for synchronization of audio level data with the media timeline, useful for creating waveform visualizations or time-based audio analysis.