Class MidiFile

Represents a MIDI file.
Inheritance
object
MidiFile
Inherited Members
Namespace: Melanchall.DryWetMidi.Core
Assembly: Melanchall.DryWetMidi.dll
Syntax
public sealed class MidiFile
Remarks

An instance of MidiFile can be obtained via one of Read (Read(string, ReadingSettings) or Read(Stream, ReadingSettings)) static methods or via constructor which allows to create a MIDI file from scratch.

Content of MIDI file available via Chunks property which contains instances of following chunk classes (derived from MidiChunk):

To save MIDI data to file on disk or to stream use appropriate Write method (Write(string, bool, MidiFileFormat, WritingSettings) or Write(Stream, MidiFileFormat, WritingSettings)).

See https://midi.org/standard-midi-files-specification for detailed MIDI file specification.

Constructors

MidiFile()

Initializes a new instance of the MidiFile.
Declaration
public MidiFile()

MidiFile(params MidiChunk[])

Initializes a new instance of the MidiFile with the specified chunks.
Declaration
public MidiFile(params MidiChunk[] chunks)
Parameters
Type Name Description
MidiChunk[] chunks Chunks to add to the file.
Remarks

Note that the library doesn't provide class for MIDI file header chunk so it cannot be added into the collection. Use OriginalFormat and TimeDivision properties instead. Header chunk with appropriate information will be written to a file automatically on Write method.

Exceptions
Type Condition
ArgumentNullException chunks is null.

MidiFile(IEnumerable<MidiChunk>)

Initializes a new instance of the MidiFile with the specified chunks.
Declaration
public MidiFile(IEnumerable<MidiChunk> chunks)
Parameters
Type Name Description
IEnumerable<MidiChunk> chunks Chunks to add to the file.
Remarks

Note that the library doesn't provide class for MIDI file header chunk so it cannot be added into the collection. Use OriginalFormat and TimeDivision properties instead. Header chunk with appropriate information will be written to a file automatically on Write method.

Exceptions
Type Condition
ArgumentNullException chunks is null.

Properties

Chunks

Gets collection of chunks of a MIDI file.
Declaration
public ChunksCollection Chunks { get; }
Property Value
Type Description
ChunksCollection
Remarks

MIDI files are made up of chunks. Collection returned by this property may contain chunks of the following types:

You cannot create instance of the UnknownChunk. It will be created by the library on reading unknown chunk (neither track chunk nor custom one).

OriginalFormat

Gets original format of the file that was read or null if the current MidiFile was created by constructor.
Declaration
public MidiFileFormat OriginalFormat { get; }
Property Value
Type Description
MidiFileFormat
Exceptions
Type Condition
UnknownFileFormatException File format is unknown.
InvalidOperationException Unable to get original format of the file. It means the current MidiFile was created not as a result of reading the file.

TimeDivision

Gets or sets the time division of a MIDI file.
Declaration
public TimeDivision TimeDivision { get; set; }
Property Value
Type Description
TimeDivision
Remarks

Time division specifies the meaning of the delta-times of MIDI events within TrackChunk. There are two types of the time division: ticks per quarter note and SMPTE. The first type represented by TicksPerQuarterNoteTimeDivision class and the second one represented by SmpteTimeDivision class.

Methods

Clone()

Clones the current MidiFile creating a copy of it.
Declaration
public MidiFile Clone()
Returns
Type Description
MidiFile Copy of the current MidiFile.

Equals(MidiFile, MidiFile)

Determines whether two specified MidiFile objects have the same content.
Declaration
public static bool Equals(MidiFile midiFile1, MidiFile midiFile2)
Parameters
Type Name Description
MidiFile midiFile1 The first file to compare, or null.
MidiFile midiFile2 The second file to compare, or null.
Returns
Type Description
bool true if the midiFile1 is equal to the midiFile2; otherwise, false.

Equals(MidiFile, MidiFile, MidiFileEqualityCheckSettings)

Determines whether two specified MidiFile objects have the same content.
Declaration
public static bool Equals(MidiFile midiFile1, MidiFile midiFile2, MidiFileEqualityCheckSettings settings)
Parameters
Type Name Description
MidiFile midiFile1 The first file to compare, or null.
MidiFile midiFile2 The second file to compare, or null.
MidiFileEqualityCheckSettings settings Settings according to which files should be compared.
Returns
Type Description
bool true if the midiFile1 is equal to the midiFile2; otherwise, false.

Equals(MidiFile, MidiFile, MidiFileEqualityCheckSettings, out string)

Determines whether two specified MidiFile objects have the same content using the specified comparison settings.
Declaration
public static bool Equals(MidiFile midiFile1, MidiFile midiFile2, MidiFileEqualityCheckSettings settings, out string message)
Parameters
Type Name Description
MidiFile midiFile1 The first file to compare, or null.
MidiFile midiFile2 The second file to compare, or null.
MidiFileEqualityCheckSettings settings Settings according to which files should be compared.
string message Message containing information about what exactly is different in midiFile1 and midiFile2.
Returns
Type Description
bool true if the midiFile1 is equal to the midiFile2; otherwise, false.

Equals(MidiFile, MidiFile, out string)

Determines whether two specified MidiFile objects have the same content.
Declaration
public static bool Equals(MidiFile midiFile1, MidiFile midiFile2, out string message)
Parameters
Type Name Description
MidiFile midiFile1 The first file to compare, or null.
MidiFile midiFile2 The second file to compare, or null.
string message Message containing information about what exactly is different in midiFile1 and midiFile2.
Returns
Type Description
bool true if the midiFile1 is equal to the midiFile2; otherwise, false.

Read(Stream, ReadingSettings)

Reads a MIDI file from the specified stream.
Declaration
public static MidiFile Read(Stream stream, ReadingSettings settings = null)
Parameters
Type Name Description
Stream stream Stream to read file from.
ReadingSettings settings Settings according to which the file must be read. Specify null to use default settings.
Returns
Type Description
MidiFile An instance of the MidiFile representing a MIDI file was read from the stream.
Remarks
Stream must be readable, seekable and be able to provide its position and length via Position and Length properties.
Exceptions
Type Condition
ArgumentNullException stream is null.
ArgumentException One of the following errors occurred:
  • stream doesn't support reading.
  • stream is already read.
IOException An I/O error occurred while reading the file.
ObjectDisposedException stream is disposed.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • The caller does not have the required permission.
NoHeaderChunkException There is no header chunk in a file and that should be treated as error according to the NoHeaderChunkPolicy of the settings.
InvalidChunkSizeException Actual header or track chunk's size differs from the one declared in its header and that should be treated as error according to the InvalidChunkSizePolicy of the settings.
UnknownChunkException Chunk to be read has unknown ID and that should be treated as error according to the UnknownChunkIdPolicy of the settings.
UnexpectedTrackChunksCountException Actual track chunks count differs from the expected one (declared in the file header) and that should be treated as error according to the UnexpectedTrackChunksCountPolicy of the specified settings.
UnknownFileFormatException The header chunk of the file specifies unknown file format and that should be treated as error according to the UnknownFileFormatPolicy of the settings.
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 of the settings.
InvalidMetaEventParameterValueException Value of a meta event's parameter just read is invalid and that should be treated as error according to the InvalidMetaEventParameterValuePolicy of the settings.
UnknownChannelEventException Reader has encountered an unknown channel event and that should be treated as error according to the UnknownChannelEventPolicy of the settings.
NotEnoughBytesException MIDI file data cannot be read since the reader's underlying stream doesn't have enough bytes and that should be treated as error according to the NotEnoughBytesPolicy of the settings.
UnexpectedRunningStatusException Unexpected running status is encountered.
MissedEndOfTrackEventException Track chunk doesn't end with End Of Track event and that should be treated as error according to the MissedEndOfTrackPolicy of the settings.
InvalidOperationException Buffer of settings is null in case of BufferingPolicy set to UseCustomBuffer.

Read(string, ReadingSettings)

Reads a MIDI file specified by its full path.
Declaration
public static MidiFile Read(string filePath, ReadingSettings settings = null)
Parameters
Type Name Description
string filePath Path to the file to read.
ReadingSettings settings Settings according to which the file must be read. Specify null to use default settings.
Returns
Type Description
MidiFile An instance of the MidiFile representing a MIDI file.
Exceptions
Type Condition
ArgumentException filePath is a zero-length string, contains only white space, or contains one or more invalid characters as defined by InvalidPathChars.
ArgumentNullException filePath is null.
PathTooLongException The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
DirectoryNotFoundException The specified path is invalid (for example, it is on an unmapped drive).
IOException An I/O error occurred while reading the file.
NotSupportedException filePath is in an invalid format.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • filePath specified a directory.
  • The caller does not have the required permission.
NoHeaderChunkException There is no header chunk in a file and that should be treated as error according to the NoHeaderChunkPolicy of the settings.
InvalidChunkSizeException Actual header or track chunk's size differs from the one declared in its header and that should be treated as error according to the InvalidChunkSizePolicy of the settings.
UnknownChunkException Chunk to be read has unknown ID and that should be treated as error according to the UnknownChunkIdPolicy of the settings.
UnexpectedTrackChunksCountException Actual track chunks count differs from the expected one (declared in the file header) and that should be treated as error according to the UnexpectedTrackChunksCountPolicy of the specified settings.
UnknownFileFormatException The header chunk of the file specifies unknown file format and that should be treated as error according to the UnknownFileFormatPolicy of the settings.
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 of the settings.
InvalidMetaEventParameterValueException Value of a meta event's parameter just read is invalid and that should be treated as error according to the InvalidMetaEventParameterValuePolicy of the settings.
UnknownChannelEventException Reader has encountered an unknown channel event and that should be treated as error according to the UnknownChannelEventPolicy of the settings.
NotEnoughBytesException MIDI file data cannot be read since the reader's underlying stream doesn't have enough bytes and that should be treated as error according to the NotEnoughBytesPolicy of the settings.
UnexpectedRunningStatusException Unexpected running status is encountered.
MissedEndOfTrackEventException Track chunk doesn't end with End Of Track event and that should be treated as error according to the MissedEndOfTrackPolicy of the settings.
InvalidOperationException Buffer of settings is null in case of BufferingPolicy set to UseCustomBuffer.

ReadLazy(Stream, ReadingSettings)

Creates an instance of the MidiTokensReader allowing to read a MIDI file from the specified stream sequentially token by token keeping low memory consumption. See Lazy reading/writing article to learn more.
Declaration
public static MidiTokensReader ReadLazy(Stream stream, ReadingSettings settings = null)
Parameters
Type Name Description
Stream stream Stream to read file from.
ReadingSettings settings Settings according to which the file must be read. Specify null to use default settings.
Returns
Type Description
MidiTokensReader An instance of the MidiTokensReader wrapped around the stream.
Remarks
Stream must be readable, seekable and be able to provide its position and length via Position and Length properties.
Exceptions
Type Condition
ArgumentNullException stream is null.
ArgumentException One of the following errors occurred:
  • stream doesn't support reading.
  • stream is already read.
IOException An I/O error occurred while reading the file.
ObjectDisposedException stream is disposed.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • The caller does not have the required permission.

ReadLazy(string, ReadingSettings)

Creates an instance of the MidiTokensReader allowing to read a MIDI file sequentially token by token keeping low memory consumption. See Lazy reading/writing article to learn more.
Declaration
public static MidiTokensReader ReadLazy(string filePath, ReadingSettings settings = null)
Parameters
Type Name Description
string filePath Path to the file to read.
ReadingSettings settings Settings according to which the file must be read. Specify null to use default settings.
Returns
Type Description
MidiTokensReader An instance of the MidiTokensReader wrapped around the specified file.
Exceptions
Type Condition
ArgumentException filePath is a zero-length string, contains only white space, or contains one or more invalid characters as defined by InvalidPathChars.
ArgumentNullException filePath is null.
PathTooLongException The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
DirectoryNotFoundException The specified path is invalid (for example, it is on an unmapped drive).
IOException An I/O error occurred while reading the file.
NotSupportedException filePath is in an invalid format.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • filePath specified a directory.
  • The caller does not have the required permission.

Write(Stream, MidiFileFormat, WritingSettings)

Writes current MidiFile to the stream.
Declaration
public void Write(Stream stream, MidiFileFormat format = MidiFileFormat.MultiTrack, WritingSettings settings = null)
Parameters
Type Name Description
Stream stream Stream to write file's data to.
MidiFileFormat format Format of the file to be written.
WritingSettings settings Settings according to which the file must be written. Specify null to use default settings.
Exceptions
Type Condition
ArgumentNullException stream is null.
ArgumentException stream doesn't support writing.
InvalidEnumArgumentException format specified an invalid value.
InvalidOperationException Time division is null.
IOException An I/O error occurred while writing to the stream.
ObjectDisposedException stream is disposed.
TooManyTrackChunksException Count of track chunks presented in the file exceeds maximum value allowed for MIDI file.

Write(string, bool, MidiFileFormat, WritingSettings)

Writes the MIDI file to location specified by full path.
Declaration
public void Write(string filePath, bool overwriteFile = false, MidiFileFormat format = MidiFileFormat.MultiTrack, WritingSettings settings = null)
Parameters
Type Name Description
string filePath Full path of the file to write to.
bool overwriteFile If true and file specified by filePath already exists it will be overwritten; if false and the file exists exception will be thrown.
MidiFileFormat format Format of a MIDI file.
WritingSettings settings Settings according to which the file must be written. Specify null to use default settings.
Exceptions
Type Condition
ArgumentException filePath is a zero-length string, contains only white space, or contains one or more invalid characters as defined by InvalidPathChars.
ArgumentNullException filePath is null.
InvalidEnumArgumentException format specified an invalid value.
PathTooLongException The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
DirectoryNotFoundException The specified path is invalid (for example, it is on an unmapped drive).
IOException An I/O error occurred while writing the file.
NotSupportedException filePath is in an invalid format.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • filePath specified a directory.
  • The caller does not have the required permission.
InvalidOperationException Time division is null.
TooManyTrackChunksException Count of track chunks presented in the file exceeds maximum value allowed for MIDI file.

WriteLazy(Stream, WritingSettings, MidiFileFormat, TimeDivision)

Creates an instance of the MidiTokensWriter allowing to write data to the specified stream sequentially token by token keeping low memory consumption. See Lazy reading/writing article to learn more.
Declaration
public static MidiTokensWriter WriteLazy(Stream stream, WritingSettings settings = null, MidiFileFormat format = MidiFileFormat.MultiTrack, TimeDivision timeDivision = null)
Parameters
Type Name Description
Stream stream Stream to write file's data to.
WritingSettings settings Settings according to which the file must be written. Specify null to use default settings.
MidiFileFormat format Format of the file to be written.
TimeDivision timeDivision The time division to write to a file. Specify null (default value) to use the default one - DefaultTicksPerQuarterNote ticks per quarter note.
Returns
Type Description
MidiTokensWriter An instance of the MidiTokensWriter wrapped around the stream.
Exceptions
Type Condition
ArgumentException stream doesn't support writing.
InvalidEnumArgumentException format specified an invalid value.
InvalidOperationException Time division is null.
IOException An I/O error occurred while writing to the stream.
ObjectDisposedException stream is disposed.
TooManyTrackChunksException Count of track chunks presented in the file exceeds maximum value allowed for MIDI file.
UnauthorizedAccessException One of the following errors occurred:
  • stream doesn't support writing (CanWrite is false).
  • stream doesn't support seeking (CanSeek is false).

WriteLazy(string, bool, MidiFileFormat, WritingSettings, TimeDivision)

Creates an instance of the MidiTokensWriter allowing to write data to a MIDI file sequentially token by token keeping low memory consumption. See Lazy reading/writing article to learn more.
Declaration
public static MidiTokensWriter WriteLazy(string filePath, bool overwriteFile = false, MidiFileFormat format = MidiFileFormat.MultiTrack, WritingSettings settings = null, TimeDivision timeDivision = null)
Parameters
Type Name Description
string filePath Full path of the file to write to.
bool overwriteFile If true and file specified by filePath already exists it will be overwritten; if false and the file exists exception will be thrown.
MidiFileFormat format Format of a MIDI file (default value is MultiTrack).
WritingSettings settings Settings according to which the file must be written. Specify null (default value) to use default settings.
TimeDivision timeDivision The time division to write to a file. Specify null (default value) to use the default one - DefaultTicksPerQuarterNote ticks per quarter note.
Returns
Type Description
MidiTokensWriter An instance of the MidiTokensWriter wrapped around the specified file.
Exceptions
Type Condition
ArgumentException filePath is a zero-length string, contains only white space, or contains one or more invalid characters as defined by InvalidPathChars.
ArgumentNullException filePath is null.
InvalidEnumArgumentException format specified an invalid value.
PathTooLongException The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.
DirectoryNotFoundException The specified path is invalid (for example, it is on an unmapped drive).
IOException An I/O error occurred while writing the file.
NotSupportedException filePath is in an invalid format.
UnauthorizedAccessException One of the following errors occurred:
  • This operation is not supported on the current platform.
  • filePath specified a directory.
  • The caller does not have the required permission.
InvalidOperationException Time division is null.
TooManyTrackChunksException Count of track chunks presented in the file exceeds maximum value allowed for MIDI file.

Extension Methods

See Also