MIDI Playing

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.

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).

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.

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.

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

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

• Multi Media Framework Client Overview - general overview of the various components of the MMF Client API and the functionality they provide.

• Audio Recording, Conversion and Playing - advanced audio file manipulation features; specifically, the ability to record, convert and playback sound clips as well as to manipulate meta data.

• Audio Streaming - the interface to streaming sampled audio.

• Audio Tone Player - a simple interface for tone generation (synthesized sounds) that is supported on all audio-capable devices.

• Video Recording and Playing - video manipulation features; specifically, the ability to record and playback video clips as well as to manipulate meta data.