Class BytesToMidiEventConverter

Provides methods to convert bytes to an instance of the MidiEvent.

Inheritance

object

BytesToMidiEventConverter

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Melanchall.DryWetMidi.Core

Assembly: Melanchall.DryWetMidi.dll

Syntax

public sealed class BytesToMidiEventConverter : IDisposable

Constructors

BytesToMidiEventConverter()

Initializes a new instance of the BytesToMidiEventConverter.

Declaration

public BytesToMidiEventConverter()

BytesToMidiEventConverter(int)

Initializes a new instance of the BytesToMidiEventConverter with the specified initial capacity of internal buffer.

Declaration

public BytesToMidiEventConverter(int capacity)

Parameters

Type	Name	Description
int	capacity	Initial capacity of the internal buffer.

Exceptions

Type	Condition
ArgumentOutOfRangeException	capacity is negative.

Properties

BytesFormat

Gets or sets the format of source bytes layout. The default is File.

Declaration

public BytesFormat BytesFormat { get; set; }

Property Value

Type	Description
BytesFormat

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

CustomMetaEventTypes

Gets or sets collection of custom meta events types.

Declaration

public EventTypesCollection CustomMetaEventTypes { get; set; }

Property Value

Type	Description
EventTypesCollection

Remarks

Types within this collection must be derived from the MetaEvent class and have parameterless constructor. No exception will be thrown if some types don't meet these requirements.

DecodeTextCallback

Gets or sets a callback used to decode a string from the specified bytes during reading a text-based meta event's text. The default is null.

Declaration

public DecodeTextCallback DecodeTextCallback { get; set; }

Property Value

Type	Description
DecodeTextCallback

Remarks

If callback is not set, TextEncoding will be used.

InvalidChannelEventParameterValuePolicy

Gets or sets reaction of the reading engine on invalid value of a channel event's parameter value. The default is Abort.

Declaration

public InvalidChannelEventParameterValuePolicy InvalidChannelEventParameterValuePolicy { get; set; }

Property Value

Type	Description
InvalidChannelEventParameterValuePolicy

Remarks

Valid values are 0-127 so, for example, 128 is the invalid one and will be processed according with this policy. If Abort is used, an instance of the InvalidChannelEventParameterValueException will be thrown if event's parameter value just read is invalid.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

InvalidMetaEventParameterValuePolicy

Gets or sets reaction of the reading engine on invalid value of a meta event's parameter value. The default is Abort.

Declaration

public InvalidMetaEventParameterValuePolicy InvalidMetaEventParameterValuePolicy { get; set; }

Property Value

Type	Description
InvalidMetaEventParameterValuePolicy

Remarks

For example, 255 is the invalid value for the Scale and will be processed according with this policy. If Abort is used, an instance of the InvalidMetaEventParameterValueException will be thrown if event's parameter value just read is invalid.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

InvalidSystemCommonEventParameterValuePolicy

Gets or sets reaction of the reading engine on invalid value of a system common event's parameter value. The default is Abort.

Declaration

public InvalidSystemCommonEventParameterValuePolicy InvalidSystemCommonEventParameterValuePolicy { get; set; }

Property Value

Type	Description
InvalidSystemCommonEventParameterValuePolicy

Remarks

For example, 255 is the invalid value for the Number and will be processed according with this policy. If Abort is used, an instance of the InvalidSystemCommonEventParameterValueException will be thrown if event's parameter value just read is invalid.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

NotEnoughBytesPolicy

Gets or sets reaction of the reading engine on lack of bytes in the underlying stream that are needed to read MIDI data (for example, DWORD requires 4 bytes available). The default is Abort.

Declaration

public NotEnoughBytesPolicy NotEnoughBytesPolicy { get; set; }

Property Value

Type	Description
NotEnoughBytesPolicy

Remarks

If Abort is used, an instance of the NotEnoughBytesException will be thrown if the reader's underlying stream doesn't have enough bytes to read MIDI data.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

ReadDeltaTimes

Gets or sets a value indicating whether incoming bytes array contains delta-times before each event data (and thus they must be read) or not. The default value is false.

Declaration

public bool ReadDeltaTimes { get; set; }

Property Value

Type	Description
bool

SilentNoteOnPolicy

Gets or sets reaction of the reading engine on Note On events with velocity of zero. The default is NoteOff.

Declaration

public SilentNoteOnPolicy SilentNoteOnPolicy { get; set; }

Property Value

Type	Description
SilentNoteOnPolicy

Remarks

Although it is recommended to treat silent Note On event as Note Off you can turn this behavior off to get original event.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

TextEncoding

Gets or sets an Encoding that will be used to read the text of a text-based meta events. The default is ASCII.

Declaration

public Encoding TextEncoding { get; set; }

Property Value

Type	Description
Encoding

Remarks

Value of this property will be used only if DecodeTextCallback is not set.

UnknownChannelEventCallback

Gets or sets a callback used to read unknown channel event if UnknownChannelEventPolicy set to UseCallback.

Declaration

public UnknownChannelEventCallback UnknownChannelEventCallback { get; set; }

Property Value

Type	Description
UnknownChannelEventCallback

UnknownChannelEventPolicy

Gets or sets reaction of the reading engine on unknown channel event. The default is Abort.

Declaration

public UnknownChannelEventPolicy UnknownChannelEventPolicy { get; set; }

Property Value

Type	Description
UnknownChannelEventPolicy

Remarks

If Abort is used, an instance of the UnknownChannelEventException will be thrown if channel event has unknown status byte.

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

ZeroLengthDataPolicy

Gets or sets reaction of the reading engine on zero-length objects such as strings or arrays. The default is ReadAsEmptyObject.

Declaration

public ZeroLengthDataPolicy ZeroLengthDataPolicy { get; set; }

Property Value

Type	Description
ZeroLengthDataPolicy

Exceptions

Type	Condition
InvalidEnumArgumentException	value specified an invalid value.

Methods

Convert(byte, byte[])

Converts the specified status byte and data bytes to an instance of the MidiEvent.

Declaration

public MidiEvent Convert(byte statusByte, byte[] dataBytes)

Parameters

Type	Name	Description
byte	statusByte	The status byte of MIDI event.
byte[]	dataBytes	Data bytes of MIDI event (bytes except status byte). Can be null if MIDI event has no data bytes.

Returns

Type	Description
MidiEvent	MidiEvent read from statusByte and dataBytes.

Convert(byte[])

Converts the specified bytes to an instance of the MidiEvent. First byte is the status byte of MIDI event. If bytes array contains multiple events, only first one will be read.

Declaration

public MidiEvent Convert(byte[] bytes)

Parameters

Type	Name	Description
byte[]	bytes	Bytes representing a MIDI event.

Returns

Type	Description
MidiEvent	MidiEvent read from bytes.

Remarks

Use ConvertMultiple(byte[]) or ConvertMultiple(byte[], int, int) to read multiple events.

Exceptions

Type	Condition
ArgumentNullException	bytes is null.
ArgumentException	bytes is an empty array.

Convert(byte[], int, int)

Converts sub-array of the specified bytes to an instance of the MidiEvent. First byte at the specified offset is the status byte of MIDI event. If sub-array contains multiple events, only first one will be read.

Declaration

public MidiEvent Convert(byte[] bytes, int offset, int length)

Parameters

Type	Name	Description
byte[]	bytes	Bytes to take sub-array from.
int	offset	Offset of sub-array to read MIDI event from.
int	length	Length of sub-array to read MIDI event from.

Returns

Type	Description
MidiEvent	MidiEvent read from bytes starting from offset and taking length of bytes.

Remarks

Use ConvertMultiple(byte[]) or ConvertMultiple(byte[], int, int) to read multiple events.

Exceptions

Type	Condition
ArgumentNullException	bytes is null.
ArgumentException	bytes is an empty array.
ArgumentOutOfRangeException	One of the following errors occurred: offset is out of range. length is out of range.

ConvertMultiple(byte[])

Converts the specified bytes to a collection of MidiEvent.

Declaration

public ICollection<MidiEvent> ConvertMultiple(byte[] bytes)

Parameters

Type	Name	Description
byte[]	bytes	Bytes to convert to collection of MidiEvent.

Returns

Type	Description
ICollection<MidiEvent>	Collection of MidiEvent read from bytes.

Exceptions

Type	Condition
ArgumentNullException	bytes is null.
ArgumentException	bytes is an empty array.
InvalidChannelEventParameterValueException	Value of a channel event's parameter just read is invalid (is out of [0; 127] range) and that should be treated as error according to the InvalidChannelEventParameterValuePolicy.
InvalidMetaEventParameterValueException	Value of a meta event's parameter just read is invalid and that should be treated as error according to the InvalidMetaEventParameterValuePolicy.
NotEnoughBytesException	MIDI events data cannot be read since the sub-array bytes doesn't have enough bytes and that should be treated as error according to the NotEnoughBytesPolicy.
UnexpectedRunningStatusException	Unexpected running status is encountered.

ConvertMultiple(byte[], int, int)

Converts sub-array of the specified bytes to a collection of MidiEvent.

Declaration

public ICollection<MidiEvent> ConvertMultiple(byte[] bytes, int offset, int length)

Parameters

Type	Name	Description
byte[]	bytes	Bytes to take sub-array from.
int	offset	Offset of sub-array to read MIDI events from.
int	length	Length of sub-array to read MIDI events from.

Returns

Type	Description
ICollection<MidiEvent>	Collection of MidiEvent read from bytes starting from offset and taking length of bytes.

Exceptions

Type	Condition
ArgumentNullException	bytes is null.
ArgumentException	bytes is an empty array.
ArgumentOutOfRangeException	One of the following errors occurred: offset is out of range. length is out of range.
InvalidChannelEventParameterValueException	Value of a channel event's parameter just read is invalid (is out of [0; 127] range) and that should be treated as error according to the InvalidChannelEventParameterValuePolicy.
InvalidMetaEventParameterValueException	Value of a meta event's parameter just read is invalid and that should be treated as error according to the InvalidMetaEventParameterValuePolicy.
NotEnoughBytesException	MIDI events data cannot be read since the sub-array bytes doesn't have enough bytes and that should be treated as error according to the NotEnoughBytesPolicy.
UnexpectedRunningStatusException	Unexpected running status is encountered.

Dispose()

Releases all resources used by the current instance of the BytesToMidiEventConverter class.

Declaration

public void Dispose()

Implements

IDisposable