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 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 with SetInstrumentLActivate, 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:

Events

The MIDI API allows you to monitor MIDI progress.

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): CMidiClientUtility::MmcuoSyncUpdateL

© Nokia 2011.