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

IDisposable

IClockDrivenObject

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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. The default value is true.

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

IsSnappingEnabled

Gets or sets a value indicating whether playback snapping is enabled or not. The property lets turn on or off all snap points at once.

Declaration

public bool IsSnappingEnabled { get; set; }

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.

SendNoteOffEventsForNonActiveNotes

Gets or sets a value indicating whether to send Note Off events for non-active notes (which look redundant) or not. The default value is false.

Declaration

public bool SendNoteOffEventsForNonActiveNotes { get; set; }

Property Value

Type	Description
bool

Remarks

If there is a Note Off event and we are in the point (for example, by jumping with the MoveToTime(ITimeSpan)) where there is no currently playing note with the same note number and channel, the event won't be played when this property set to false (which is the default value). To send Note Off event anyway, set this property to true.

SendNoteOnEventsForActiveNotes

Gets or sets a value indicating whether to send Note On events for active notes (which look redundant) or not. The default value is false.

Declaration

public bool SendNoteOnEventsForActiveNotes { get; set; }

Property Value

Type	Description
bool

Remarks

If there is a Note On event and we are in the point (for example, by jumping with the MoveToTime(ITimeSpan)) where there is currently playing note with the same note number and channel, the event won't be played when this property set to false (which is the default value). To send Note On event anyway, set this property to true.

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. You should use this property when the current playback has been created from a IObservableTimedObjectsCollection (more info in the Dynamic changes article).

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 true. More info in the Data tracking: MIDI parameters values tracking article.

Declaration

public bool TrackControlValue { get; set; }

Property Value

Type	Description
bool

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 true. More info in the Data tracking: Notes tracking article.

Declaration

public bool TrackNotes { get; set; }

Property Value

Type	Description
bool

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 true. More info in the Data tracking: MIDI parameters values tracking article.

Declaration

public bool TrackPitchValue { get; set; }

Property Value

Type	Description
bool

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 true. More info in the Data tracking: MIDI parameters values tracking article.

Declaration

public bool TrackProgram { get; set; }

Property Value

Type	Description
bool

Methods

AddSnapPoint(ITimeSpan)

Adds a snap point at the specified time.

Declaration

public SnapPoint AddSnapPoint(ITimeSpan time)

Parameters

Type	Name	Description
ITimeSpan	time	Time to add snap point at.

Returns

Type	Description
SnapPoint	An instance of the SnapPoint representing a snap point at time.

Exceptions

Type	Condition
ArgumentNullException	time is null.

AddSnapPoint<TData>(ITimeSpan, TData)

Adds a snap point with the specified data at given time.

Declaration

public SnapPoint<TData> AddSnapPoint<TData>(ITimeSpan time, TData data)

Parameters

Type	Name	Description
ITimeSpan	time	Time to add snap point at.
TData	data	Data to attach to snap point.

Returns

Type	Description
SnapPoint<TData>	An instance of the SnapPoint<TData> representing a snap point with data at time.

Type Parameters

Name	Description
TData	Type of data that will be attached to a snap point.

Exceptions

Type	Condition
ArgumentNullException	time is null.

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.

RemoveAllSnapPoints()

Removes all snap points.

Declaration

public void RemoveAllSnapPoints()

RemoveSnapPoint(SnapPoint)

Removes a snap point.

Declaration

public void RemoveSnapPoint(SnapPoint snapPoint)

Parameters

Type	Name	Description
SnapPoint	snapPoint	Snap point to remove.

Exceptions

Type	Condition
ArgumentNullException	snapPoint is null.

RemoveSnapPointsByData<TData>(Predicate<TData>)

Removes all snap points that match the conditions defined by the specified predicate.

Declaration

public void RemoveSnapPointsByData<TData>(Predicate<TData> predicate)

Parameters

Type	Name	Description
Predicate<TData>	predicate	The Predicate<T> delegate that defines the conditions of snap points to remove.

Type Parameters

Name	Description
TData	Type of data attached to snap points to remove.

Exceptions

Type	Condition
ArgumentNullException	predicate is null.

RemoveSnapPointsGroup(SnapPointsGroup)

Removes the specified SnapPointsGroup from the list of snap points groups of the current Playback.

Declaration

public void RemoveSnapPointsGroup(SnapPointsGroup snapPointsGroup)

Parameters

Type	Name	Description
SnapPointsGroup	snapPointsGroup	SnapPointsGroup to remove.

Exceptions

Type	Condition
ArgumentNullException	snapPointsGroup is null.

SnapToEvents(Predicate<MidiEvent>)

Creates a new SnapPointsGroup that holds the specified predicate to select MIDI events which times will be used as snap points. For example, to get snap points at the markers points, you can use this predicate: e => e.EventType == MidiEventType.Marker.

Declaration

public SnapPointsGroup SnapToEvents(Predicate<MidiEvent> predicate)

Parameters

Type	Name	Description
Predicate<MidiEvent>	predicate	Predicate to select MIDI events.

Returns

Type	Description
SnapPointsGroup	SnapPointsGroup holding information on how to select events.

Remarks

After the group is created, it will be enabled by default. You can disable it using the IsEnabled property setting it to false.

Exceptions

Type	Condition
ArgumentNullException	predicate is null.

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 the Start() method.

Declaration

public event EventHandler Started

Event Type

Type	Description
EventHandler

Stopped

Occurs when playback stopped via the Stop() method.

Declaration

public event EventHandler Stopped

Event Type

Type	Description
EventHandler

Implements

IDisposable

IClockDrivenObject