MIDI Playing

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

Purpose

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. 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 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 SetPositionMicroSecondsL to set a starting position.

You can also play a MIDI note even without a MIDI source, using 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 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 SendMipMessageL to send an SP-MIDI MIP message to the MIDI player.

You can send real-time MIDI events to the MIDI player using PlayNote or NoteOnL, or StopNote and NoteOffL. The MIDI file must be available to play back at the same time.
Timing

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

CMidiClientUtility provides methods to play multiple MIDI resources within a single instance. MIDI resources are not be opened during instantiation of the 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 MMIDIClientUtilityObserver::MmcuoStateChanged() is called.

If a MIDI file is already open and playing, use Stop() followed by 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 SetPositionMicroSecondsLSet to set the playback head according to the time interval measured from the beginning of the MIDI data.
Timing

Use 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 SetStopTimeLSet to set the media time that the player must stop.
Muting

Mute or unmute a MIDI channel or track with SetMuteL.
Sound

Use SetTempoL to set the playback tempo of the current MIDI song.

Use SetPitchTranspositionL to set the global pitch transposition for the current MIDI song.

Use SetVolumeL to sets the volume of the specified MIDI channel.

SetInstrumentL sets the program for the specified MIDI channel.

You can send a "note on" message to a MIDI channel with NoteOnL, and send a "note off" message with NoteOffL.
Sound bank

If you want to send a user instrument to the sound bank to replace a factory instrument, use LoadInstrumentL.

Set an alternative sound bank to the default withSetInstrumentLActivate, and reset to the default soundbank with SetInstrumentLReturn.

Information

The 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 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 DurationMicroSecondsL (temporal) and 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 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 ) using MimeTypeL.

Use these functions to get the MIME content types supported NumberOfMimeTypesSupportedL and MimeTypeL.

Song information

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

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

Events

The MIDI API allows you to monitor MIDI progress.

Status

You can discover the current state of the MIDI data with 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:	`MmcuoStateChanged`. You can pass the media time that the player stopped with the callback mechanism.
The player has reached the end of the media	`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	`MmcuoTempoChanged`. The callback returns the new tempo as a parameter.
A SP-MIDI MIP message has been received	`MmcuoMipMessageReceived`
Metadata found	`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	`MmcuoStateChanged`
The song position has been changed	`MmcuoPositionChanged`. The callback returns the new song position as a parameter.
The playback state has changed	`MmcuoStateChanged`. The callback returns the new playback state as a parameter.
The volume of one of the channels has been changed	`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	`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	`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): MmcuoSyncUpdateL