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:

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

See also

MIDI Client Overview