MidiSequencePlayer

MidiSequencePlayer plays a MidiSequence to one or more endpoints.

The player gives its messages to the service with a timestamp on each one, and lets the service send them at the right time. It doesn’t wake up to send each one itself. That’s what keeps playback steady, and it’s why a sequence has to be prepared before it starts.

Getting a player

A player can borrow a connection your app already has open, or open one of its own. Borrowing is better. A connection costs memory and setup time, and an app that already has one shouldn’t have to pay for a second.

Properties

Methods

Events

Remarks

Starting partway in sends the channel settings again. When Play starts partway into the sequence, or the position moves while playing, the player first sends the bank, program, controllers, and pitch bend each channel should have at that point. So starting in the middle of a file doesn’t play the rest of it with the wrong sound. It only sends values the sequence set, and never resets a controller to zero. Set ChaseOptions to None to turn this off.

Held notes come back only if you ask. Add HeldNotes to ChaseOptions, and the player also restarts every note that should be sounding at that point, at the velocity it started with. Organ stops held on a control channel, drones, and pads need this. Leave it out for piano and drums, where a note restarted partway through gets a new attack. A note that ends exactly where playback starts isn’t restarted, and neither is a note on a muted track. With HeldNotes on, muting or soloing a track while playing also restarts what the tracks you can still hear should be holding, because the silence a mute or solo sends turns off every held note. Unmuting a track restarts that track’s held notes.

A seek while playing waits for its own silence. The silence sent on stop, pause, and seek goes out twice: once right away, and again about a third of a second later, after anything the service was already given. If playback starts again before that second pass lands, the music and the channel settings wait for it, so it can’t cut off the new notes.

Muting and soloing only hold back new notes. Everything else is still sent. Otherwise, a track would come back with the wrong sound, and with a chord still sounding.

SilenceAllNotes is called for you. It runs when you stop, pause, or seek, and at the end of a sequence. It sends note offs for what’s sounding, and then sustain off, all notes off, all sound off, and pitch bend center on each channel the sequence uses. Only call it yourself if you have some other reason to.

Read Position on a timer, instead of waiting for an event. A transport display updates tens of times a second, and an event for every frame would cost more than the drawing does.

PlaybackRate changes the speed, not the music. Every tempo in the sequence is scaled the same way, and the notes aren’t changed, so the pitch stays the same. That makes it useful for learning a part slowly. A change made while playing is heard within about a quarter of a second, and nothing that’s sounding is cut off. Position stays in the sequence’s own time, so at half speed a two-minute sequence still reports a two-minute DurationMicroseconds, and BeatsPerMinute is still the tempo written in the file. Multiply it by PlaybackRate for the tempo you hear. The rate stays set when you load another sequence.

TransposeSemitones changes the key, and leaves the drums alone. On a drum kit, the note number picks which drum plays, so moving it would swap a snare for a tom. So notes on channel 10 never move. Neither do notes on any other channel the sequence has switched to a drum kit, with a bank select of 120 (General MIDI 2) or 127 (XG), or with a GS or XG message that makes it a rhythm part. A GM, GS or XG reset puts every channel back to normal. Poly pressure and the MIDI 2.0 per-note messages move with their note, and so does a MIDI 2.0 pitch attribute. A note moved below 0 or above 127 isn’t played.

A key change while playing never leaves a note hanging. It’s heard within about a quarter of a second. A note that’s already sounding keeps its pitch until it ends, the way a keyboard’s transpose button works, and its note off still reaches it. If a key is struck again before its first note ends, and the key changed in between, the player ends the first note before it starts the new one. The transposition stays set when you load another sequence.

You can’t set how far ahead messages are given to the service, on purpose. The right amount depends on how often the player checks for messages to send, and on how late a high-resolution timer wakes up. Your app can’t know either one. And the service refuses anything scheduled more than five minutes ahead anyway.

Example

// borrow a connection the app already has open
MidiSequencePlayer player{ connection, MidiGroup{ (uint8_t)0 } };

co_await player.SetSequenceAsync(sequence);

player.StateChanged([](auto&& sender, auto&&)
{
    // update the transport buttons
});

player.Play();

Samples

• C++/WinRT midi-file-player and C# midi-file-player for pausing and resuming, reading Position to show the bar and beat, and handling PlaybackEnded
• C++/WinRT sequence-builder and C# sequence-builder for playing one sequence after another on the same player

Both borrow a connection the app opened, instead of letting the player open its own.

Complete code samples available on GitHub