MIDI Playing

This tutorial describes how to play MIDI data using the MIDI Client.

Purpose

[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]CMidiClientUtility provides an interface to open, play and obtain information in MIDI format. The MIDI data can supplied either in a file, a descriptor or a URL.

For the purposes of this description, the playing process has been broken down into the following sections.

Playing - describes the options for playing MIDI resources. This includes the ability to play MIDI events in realtime during playback.
Opening - describes the options available for opening MIDI resources after the CMidiClientUtility object has been instantiated.
Control - describes how to control the MIDI player, or a MIDI song.
Information - describes how you can retrieve information from the MIDI player.
Events - handling MIDI events and notifications.

Playing

This class is intended for playing MIDI resources only. [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]CMidiClientUtility is capable of playing more than one clip within the same instance of the object.

The play related methods are as follows:

Starting and Stopping

You can use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]Play to start a playback of the initialised MIDI resource at the current volume and priority levels, starting from the current playback head position, or together with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetPositionMicroSecondsL to set a starting position.

You can also play a MIDI note even without a MIDI source, using [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]PlayNote, for example:
```
CMidiClientUtility* midi=CMidiClientUtility::NewL(*this);
CleanupStack::PushL(midi);
TTimeIntervalMicroSeconds duration(1000000);
midi->PlayNoteL(1, 60, duration, 64, 64) //play middle C on channel 1 for 1 second at average velocity.
CleanupStack::PopAndDestroy();
```
When you use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]Stop to halt the playback of the audio sample as soon as possible, nothing happens if playback has already completed. The head is positioned at the last played data.
MIPs and Events

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SendMipMessageL to send an SP-MIDI MIP message to the MIDI player.

You can send real-time MIDI events to the MIDI player using [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]PlayNote or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]NoteOnL, or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]StopNote and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]NoteOffL. The MIDI file must be available to play back at the same time.
Timing

[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetPositionMicroSecondsL provides a mechanism to synchronise the playback of the MIDI player with an external time base (the MIDI player act as a slave).

Opening

[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]CMidiClientUtility provides methods to play multiple MIDI resources within a single instance. MIDI resources are not be opened during instantiation of the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]CMidiClientUtility object. Instead, all MIDI resources must be opened using one of the open methods listed below.

The following open methods are provided:

OpenFileL(const TDesC& aFileName);

OpenDesL(const TDesC8& aDescriptor);

OpenUrlL(const TDesC& aUrl, TInt aIapId = KUseDefaultIap, const TDesC8& aMimeType=KNullDesC8);

As soon as the open method has completed, successfully or otherwise, the callback function [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]MMIDIClientUtilityObserver::MmcuoStateChanged() is called.

If a MIDI file is already open and playing, use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]Stop() followed by [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]Close() to unload the clip before specifying new MIDI data to open.

Control

You can control the MIDI player, or a MIDI song, in the following ways:

Setting the head position

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetPositionMicroSecondsLSet to set the playback head according to the time interval measured from the beginning of the MIDI data.
Timing

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetRepeatsL to set the number of times the playback of the MIDI source is to be repeated. This can be set to infinite. You can also insert a period of silence after each repitition.

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetStopTimeLSet to set the media time that the player must stop.
Muting

Mute or unmute a MIDI channel or track with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetMuteL.
Sound

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetTempoL to set the playback tempo of the current MIDI song.

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetPitchTranspositionL to set the global pitch transposition for the current MIDI song.

Use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetVolumeL to sets the volume of the specified MIDI channel.

[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetInstrumentL sets the program for the specified MIDI channel.

You can send a "note on" message to a MIDI channel with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]NoteOnL, and send a "note off" message with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]NoteOffL.
Sound bank

If you want to send a user instrument to the sound bank to replace a factory instrument, use [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]LoadInstrumentL.

Set an alternative sound bank to the default with[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetInstrumentLActivate, and reset to the default soundbank with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]SetInstrumentLReturn.

Information

The [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]CMidiClientUtility class can return information about the MIDI player or MIDI songs in the following ways:

Timing

The player's current media time is gained from [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]PositionMicroSeconds. This is the current playback head position for the MIDI data. The media time can be set both in temporal as well as metrical formats.

The duration of the MIDI data is retrieved with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]DurationMicroSecondsL (temporal) and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]DurationMicroBeatsL (metrical). The duration is based on the MIDI data played back at its default rate.

The defined time at which the player will stop is returned by [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]StopTimeL. In case the stop time is not set, the API returns a pre-defined constant value.
Formats

You can get the format of the MIDI data (such as SMF, XMF, MIME ) [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]using MimeTypeL.

Use these functions to get the MIME content types supported [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]NumberOfMimeTypesSupportedL and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]MimeTypeL.

Song information

You can discover a wide range of information about the current MIDI data.

The number of channels in the MIDI data	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`ChannelsUsedL`
The number of tracks in the MIDI data	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`NumTracksL`
The current playback tempo of the MIDI song	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`TempoMicroBeatsPerMinuteL`
The global pitch transposition currently in use	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`PitchTranspositionCentsL`
The volume assigned to a specified MIDI channel	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`VolumeL`
A list of installed instrument banks	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`NumberOfBanksL` and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`GetBankIdL`.
Program numbers for a given instrument bank	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`NumberOfInstrumentsL` and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`GetInstrumentIdL`
The name of the program for a given instrument bank and program number	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`InstrumentNameL`
The name of the key for a given instrument bank, program number and key	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`PercussionKeyNameL`
Information regarding whether the sound bank can be queried	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`NumberOfBanksL` and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`GetBankIdL`

Events

The MIDI API allows you to monitor MIDI progress.

Status

You can discover the current state of the MIDI data with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]Status. This can tell you if MIDI data is playing, or a MIDI file is open but no playback operation is in progress.

Callback mechanisms

The MIDI player provides a set of callback mechanisms.

The player has stopped:	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoStateChanged`. You can pass the media time that the player stopped with the callback mechanism.
The player has reached the end of the media	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoStateChanged`. The playback has been completed. You can pass the media time that the player stopped with the callback mechanism.
The playback tempo has changed	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoTempoChanged`. The callback returns the new tempo as a parameter.
A SP-MIDI MIP message has been received	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoMipMessageReceived`
Metadata found	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoMetaDataEntryFound`. The metadata contained in the MIDI data is passed to the application.
The playback of SP-MIDI file has gone silent due to system constraints	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoStateChanged`
The song position has been changed	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoPositionChanged`. The callback returns the new song position as a parameter.
The playback state has changed	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoStateChanged`. The callback returns the new playback state as a parameter.
The volume of one of the channels has been changed	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoVolumeChanged`. The API provides a callback mechanism to indicate that. The callback returns the channel number and the new volume level as parameters.
One of the channels' muting status has been changed	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoMuteChanged`. The callback returns the channel number and the new channel muting status as parameters.
The audio policy has taken over the MIDI player resources	[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]`MmcuoStateChanged`

The API also provides a callback mechanism to synchronise the playback of an external device with MIDI player's time base (MIDI player acting as a master): [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CMidiClientUtility']]]MmcuoSyncUpdateL