Class Playback

Provides a way to play MIDI data through the specified output MIDI device. More info in the Playback article.
Inheritance
object
Playback
Implements
Inherited Members
Namespace: Melanchall.DryWetMidi.Multimedia
Assembly: Melanchall.DryWetMidi.dll
Syntax
public class Playback : IDisposable, IClockDrivenObject
Remarks
You can derive from the Playback class to create your own playback logic. Please see Custom playback article to learn more.

Constructors

Playback(IEnumerable<ITimedObject>, TempoMap, IOutputDevice, PlaybackSettings)

Initializes a new instance of the Playback with the specified collection of timed objects, tempo map and output MIDI device to play events through.
Declaration
public Playback(IEnumerable<ITimedObject> timedObjects, TempoMap tempoMap, IOutputDevice outputDevice, PlaybackSettings playbackSettings = null)
Parameters
Type Name Description
IEnumerable<ITimedObject> timedObjects Collection of timed objects to play.
TempoMap tempoMap Tempo map used to calculate events times.
IOutputDevice outputDevice Output MIDI device to play timedObjects through.
PlaybackSettings playbackSettings Settings according to which a playback should be created.
Exceptions
Type Condition
ArgumentNullException

One of the following errors occurred:

  • timedObjects is null.
  • tempoMap is null.
  • outputDevice is null.

Playback(IEnumerable<ITimedObject>, TempoMap, PlaybackSettings)

Initializes a new instance of the Playback with the specified collection of timed objects and tempo map.
Declaration
public Playback(IEnumerable<ITimedObject> timedObjects, TempoMap tempoMap, PlaybackSettings playbackSettings = null)
Parameters
Type Name Description
IEnumerable<ITimedObject> timedObjects Collection of timed objects to play.
TempoMap tempoMap Tempo map used to calculate events times.
PlaybackSettings playbackSettings Settings according to which a playback should be created.
Exceptions
Type Condition
ArgumentNullException

One of the following errors occurred:

  • timedObjects is null.
  • tempoMap is null.

Properties

EventCallback

Gets or sets callback used to process MIDI event to be played.
Declaration
public EventCallback EventCallback { get; set; }
Property Value
Type Description
EventCallback
Remarks
Note that NoteOnEvent and NoteOffEvent won't be passed to EventCallback. Since processing of a note requires syncing between pairs of corresponding events, such pairs are handled by NoteCallback to be sure that a note's integrity is not broken.
Examples

The following example filters out all Program Change events: 

playback.EventCallback = (midiEvent, rawTime, playbackTime) =>
    midiEvent.EventType == MidiEventType.ProgramChange
        ? null
        : midiEvent;

Next example shows how to replace program 1 in all Program Change events to program 2: 

playback.EventCallback = (midiEvent, rawTime, playbackTime) =>
    ((midiEvent is ProgramChangeEvent programChangeEvent) && programChangeEvent.ProgramNumber == 1)
        ? new ProgramChangeEvent((SevenBitNumber)2) { Channel = programChangeEvent.Channel }
        : midiEvent;

InterruptNotesOnStop

Gets or sets a value indicating whether currently playing notes must be stopped on playback stop or not.
Declaration
public bool InterruptNotesOnStop { get; set; }
Property Value
Type Description
bool

IsRunning

Gets a value indicating whether playing is currently running or not.
Declaration
public bool IsRunning { get; }
Property Value
Type Description
bool

Loop

Gets or sets a value indicating whether playing should automatically start from the first event after the last one played.
Declaration
public bool Loop { get; set; }
Property Value
Type Description
bool

NoteCallback

Gets or sets callback used to process note to be played.
Declaration
public NoteCallback NoteCallback { get; set; }
Property Value
Type Description
NoteCallback
Examples

In the following example every note to be played will be transposed by 10 half-steps up: 

var playback = midiFile.GetPlayback(outputDevice);
playback.NoteCallback = (rawNoteData, rawTime, rawLength, playbackTime) =>
    new NotePlaybackData(
        (SevenBitNumber)(rawNoteData.NoteNumber + 10),
        rawNoteData.Velocity,     // leave velocity as is
        rawNoteData.OffVelocity,  // leave off velocity as is
        rawNoteData.Channel);     // leave channel as is

playback.Start();

Next example shows how you can filter out notes with velocity below 100: 

playback.NoteCallback = (rawNoteData, rawTime, rawLength, playbackTime) =>
    rawNoteData.Velocity < 100
        ? null
        : rawNoteData;

OutputDevice

Gets or sets the output MIDI device to play MIDI data through.
Declaration
public IOutputDevice OutputDevice { get; set; }
Property Value
Type Description
IOutputDevice

PlaybackEnd

Gets or sets the end time of the current playback. It defines end time of the region to play back.
Declaration
public ITimeSpan PlaybackEnd { get; set; }
Property Value
Type Description
ITimeSpan
Remarks
In conjunction with PlaybackStart you can define a region within the current playback which will be played. If you set the property to null the end of playback will be used.

PlaybackStart

Gets or sets the start time of the current playback. It defines start time of the region to play back.
Declaration
public ITimeSpan PlaybackStart { get; set; }
Property Value
Type Description
ITimeSpan
Remarks
In conjunction with PlaybackEnd you can define a region within the current playback which will be played. If you set the property to null the start of playback (zero) will be used.

Snapping

Gets an object to manage playback's snap points.
Declaration
public PlaybackSnapping Snapping { get; }
Property Value
Type Description
PlaybackSnapping

Speed

Gets or sets the speed of events playing. 1 means normal speed. For example, to play events twice slower this property should be set to 0.5. Value of 2 will make playback twice faster.
Declaration
public double Speed { get; set; }
Property Value
Type Description
double
Examples

Example below shows how you can use Speed property to set new BPM (if original data doesn't have tempo changes): 

var tempoMap = midiFile.GetTempoMap();
var originalBpm = tempoMap.GetTempoAtTime((MidiTimeSpan)0).BeatsPerMinute;

var newBpm = 240;
playback.Speed = newBpm / originalBpm;

We want to have BPM of 240 here so we just divide it by original BPM value. If original BPM was 120, we'll get 2 which is exactly what we want - double the speed. If original value is 480, we'll get 0.5 which means speed will be slowed down by two times.

Exceptions
Type Condition
ArgumentOutOfRangeException value is zero or negative.
ObjectDisposedException The current Playback is disposed.

TempoMap

Gets the tempo map used to calculate events times.
Declaration
public TempoMap TempoMap { get; }
Property Value
Type Description
TempoMap

TrackControlValue

Gets or sets a value indicating whether controller values must be tracked or not. If true, any jump in time will force playback send ControlChangeEvent corresponding to the controller value at new time, if needed. The default value is false. More info in the Data tracking: MIDI parameters values tracking article.
Declaration
public bool TrackControlValue { get; set; }
Property Value
Type Description
bool
Exceptions
Type Condition
InvalidOperationException Can't enable control value tracking due to the DisableControlValueTracking hint has been specified on the playback creation.

TrackNotes

Gets or sets a value indicating whether notes must be tracked or not. If false, notes will be treated as just Note On/Note Off events. The default value is false. More info in the Data tracking: Notes tracking article.
Declaration
public bool TrackNotes { get; set; }
Property Value
Type Description
bool
Exceptions
Type Condition
InvalidOperationException Can't enable notes tracking due to the DisableNotesTracking hint has been specified on the playback creation.

TrackPitchValue

Gets or sets a value indicating whether pitch value must be tracked or not. If true, any jump in time will force playback send PitchBendEvent corresponding to the pitch value at new time, if needed. The default value is false. More info in the Data tracking: MIDI parameters values tracking article.
Declaration
public bool TrackPitchValue { get; set; }
Property Value
Type Description
bool
Exceptions
Type Condition
InvalidOperationException Can't enable pitch value tracking due to the DisablePitchValueTracking hint has been specified on the playback creation.

TrackProgram

Gets or sets a value indicating whether program must be tracked or not. If true, any jump in time will force playback send ProgramChangeEvent corresponding to the program at new time, if needed. The default value is false. More info in the Data tracking: MIDI parameters values tracking article.
Declaration
public bool TrackProgram { get; set; }
Property Value
Type Description
bool
Exceptions
Type Condition
InvalidOperationException Can't enable program tracking due to the DisableProgramTracking hint has been specified on the playback creation.

Methods

Dispose()

Releases all resources used by the current Playback.
Declaration
public void Dispose()

~Playback()

Finalizes the current instance of the Playback.
Declaration
protected ~Playback()

GetCurrentTime(TimeSpanType)

Retrieves the current time of the playback in the specified format.
Declaration
public ITimeSpan GetCurrentTime(TimeSpanType timeType)
Parameters
Type Name Description
TimeSpanType timeType Type that will represent the current time.
Returns
Type Description
ITimeSpan The current time of the playback as an instance of time span defined by timeType.
Exceptions
Type Condition
InvalidEnumArgumentException timeType specified an invalid value.

GetCurrentTime<TTimeSpan>()

Retrieves the current time of the playback in the specified format.
Declaration
public TTimeSpan GetCurrentTime<TTimeSpan>() where TTimeSpan : ITimeSpan
Returns
Type Description
TTimeSpan The current time of the playback as an instance of TTimeSpan.
Type Parameters
Name Description
TTimeSpan Type that will represent the current time.

GetDuration(TimeSpanType)

Retrieves the duration of the playback in the specified format.
Declaration
public ITimeSpan GetDuration(TimeSpanType durationType)
Parameters
Type Name Description
TimeSpanType durationType Type that will represent the duration.
Returns
Type Description
ITimeSpan The duration of the playback as an instance of time span defined by durationType.
Exceptions
Type Condition
InvalidEnumArgumentException durationType specified an invalid value.

GetDuration<TTimeSpan>()

Retrieves the duration of the playback in the specified format.
Declaration
public TTimeSpan GetDuration<TTimeSpan>() where TTimeSpan : ITimeSpan
Returns
Type Description
TTimeSpan The duration of the playback as an instance of TTimeSpan.
Type Parameters
Name Description
TTimeSpan Type that will represent the duration.

GetTimedEvents(ITimedObject)

Returns collection of TimedEvent representing the specified timed object.
Declaration
protected virtual IEnumerable<TimedEvent> GetTimedEvents(ITimedObject timedObject)
Parameters
Type Name Description
ITimedObject timedObject Timed object to get collection of TimedEvent from.
Returns
Type Description
IEnumerable<TimedEvent> Collection of TimedEvent representing the timedObject.
Remarks
The method can be useful in case of custom playback and custom input object.

MoveBack(ITimeSpan)

Shifts playback position back by the specified step.
Declaration
public void MoveBack(ITimeSpan step)
Parameters
Type Name Description
ITimeSpan step Amount of time to shift playback position by.
Exceptions
Type Condition
ArgumentNullException step is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveForward(ITimeSpan)

Shifts playback position forward by the specified step.
Declaration
public void MoveForward(ITimeSpan step)
Parameters
Type Name Description
ITimeSpan step Amount of time to shift playback position by.
Exceptions
Type Condition
ArgumentNullException step is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToFirstSnapPoint()

Sets playback position to the time of first snap point.
Declaration
public bool MoveToFirstSnapPoint()
Returns
Type Description
bool true if playback position successfully changed to the time of first snap point; otherwise, false.
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToFirstSnapPoint<TData>(TData)

Sets playback position to the time of first snap point holding the specified data.
Declaration
public bool MoveToFirstSnapPoint<TData>(TData data)
Parameters
Type Name Description
TData data Data of a snap point to move to.
Returns
Type Description
bool true if playback position successfully changed to the time of first snap point with the specified data; otherwise, false.
Type Parameters
Name Description
TData
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToNextSnapPoint()

Sets playback position to the time of next snap point (relative to the current time of playback).
Declaration
public bool MoveToNextSnapPoint()
Returns
Type Description
bool true if playback position successfully changed to the time of a next snap point; otherwise, false.
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToNextSnapPoint(SnapPointsGroup)

Sets playback position to the time of next snap point (relative to the current time of playback) that belongs to the specified SnapPointsGroup.
Declaration
public bool MoveToNextSnapPoint(SnapPointsGroup snapPointsGroup)
Parameters
Type Name Description
SnapPointsGroup snapPointsGroup SnapPointsGroup that defines snap points to select the one from.
Returns
Type Description
bool true if playback position successfully changed to the time of a next snap point within snapPointsGroup; otherwise, false.
Exceptions
Type Condition
ArgumentNullException snapPointsGroup is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToNextSnapPoint<TData>(TData)

Sets playback position to the time of next snap point (relative to the current time of playback) holding the specified data.
Declaration
public bool MoveToNextSnapPoint<TData>(TData data)
Parameters
Type Name Description
TData data
Returns
Type Description
bool true if playback position successfully changed to the time of a next snap point with the specified data; otherwise, false.
Type Parameters
Name Description
TData
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToPreviousSnapPoint()

Sets playback position to the time of previous snap point (relative to the current time of playback).
Declaration
public bool MoveToPreviousSnapPoint()
Returns
Type Description
bool true if playback position successfully changed to the time of a previous snap point; otherwise, false.
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToPreviousSnapPoint(SnapPointsGroup)

Sets playback position to the time of the previous snap point (relative to the current time of playback) that belongs to the specified SnapPointsGroup.
Declaration
public bool MoveToPreviousSnapPoint(SnapPointsGroup snapPointsGroup)
Parameters
Type Name Description
SnapPointsGroup snapPointsGroup SnapPointsGroup that defines snap points to select the one from.
Returns
Type Description
bool true if playback position successfully changed to the time of a previous snap point within snapPointsGroup; otherwise, false.
Exceptions
Type Condition
ArgumentNullException snapPointsGroup is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToPreviousSnapPoint<TData>(TData)

Sets playback position to the time of previous snap point (relative to the current time of playback) holding the specified data.
Declaration
public bool MoveToPreviousSnapPoint<TData>(TData data)
Parameters
Type Name Description
TData data Data of a snap point to move to.
Returns
Type Description
bool true if playback position successfully changed to the time of a previous snap point with the specified data; otherwise, false.
Type Parameters
Name Description
TData
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToSnapPoint(SnapPoint)

Sets playback position to the time of the specified snap point.
Declaration
public bool MoveToSnapPoint(SnapPoint snapPoint)
Parameters
Type Name Description
SnapPoint snapPoint Snap point to move to.
Returns
Type Description
bool true if playback position successfully changed to the time of snapPoint; otherwise, false.
Exceptions
Type Condition
ArgumentNullException snapPoint is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToStart()

Sets playback position to the beginning of the MIDI data.
Declaration
public void MoveToStart()
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

MoveToTime(ITimeSpan)

Sets playback position to the specified time from the beginning of the MIDI data.
Declaration
public void MoveToTime(ITimeSpan time)
Parameters
Type Name Description
ITimeSpan time Time from the beginning of the MIDI data to set playback position to.
Exceptions
Type Condition
ArgumentNullException time is null.
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

Play()

Starts playing of the MIDI data. This method will block execution of a program until all MIDI data is played.
Declaration
public void Play()
Remarks
If Loop is set to true, this method will execute forever.
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

Start()

Starts playing of the MIDI data. This method is non-blocking.
Declaration
public void Start()
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

Stop()

Stops playing of the MIDI data. Note that this method doesn't reset playback position. If you call Start(), playing will be resumed from the point where Stop() was called.
Declaration
public void Stop()
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.
MidiDeviceException An error occurred on device.

TickClock()

Ticks internal clock.
Declaration
public void TickClock()
Exceptions
Type Condition
ObjectDisposedException The current Playback is disposed.

TryPlayEvent(MidiEvent, object)

Tries to play the specified MIDI event. By default just sends the event to output device returning true.
Declaration
protected virtual bool TryPlayEvent(MidiEvent midiEvent, object metadata)
Parameters
Type Name Description
MidiEvent midiEvent MIDI event to try to play.
object metadata Metadata attached to midiEvent.
Returns
Type Description
bool true if midiEvent was played; otherwise, false.
Remarks
Please see Custom playback article to learn more about how to use metadata parameter.

Events

DeviceErrorOccurred

Occurs when an error got from output device.
Declaration
public event EventHandler<ErrorOccurredEventArgs> DeviceErrorOccurred
Event Type
Type Description
EventHandler<ErrorOccurredEventArgs>

EventPlayed

Occurs when MIDI event played.
Declaration
public event EventHandler<MidiEventPlayedEventArgs> EventPlayed
Event Type
Type Description
EventHandler<MidiEventPlayedEventArgs>

Finished

Occurs when playback finished, i.e. last event has been played and no need to restart playback due to value of the Loop.
Declaration
public event EventHandler Finished
Event Type
Type Description
EventHandler

NotesPlaybackFinished

Occurs when notes finished to play. It will raised if playback's cursor gets out from notes.
Declaration
public event EventHandler<NotesEventArgs> NotesPlaybackFinished
Event Type
Type Description
EventHandler<NotesEventArgs>

NotesPlaybackStarted

Occurs when notes started to play. It will raised if playback's cursor gets in to notes.
Declaration
public event EventHandler<NotesEventArgs> NotesPlaybackStarted
Event Type
Type Description
EventHandler<NotesEventArgs>

RepeatStarted

Occurs when playback started new cycle of the data playing in case of Loop set to true.
Declaration
public event EventHandler RepeatStarted
Event Type
Type Description
EventHandler

Started

Occurs when playback started via Start() or Play() methods.
Declaration
public event EventHandler Started
Event Type
Type Description
EventHandler

Stopped

Occurs when playback stopped via Stop() method.
Declaration
public event EventHandler Stopped
Event Type
Type Description
EventHandler

Implements