<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC"><title>MIDI Playing</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to play MIDI data using the MIDI Client. </p> <section id="GUID-53D7B505-C4AE-51E4-A898-AABCD4E2C037"><title>Purpose</title> <p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>CMidiClientUtility</apiname></xref> 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. </p> <p>For the purposes of this description, the playing process has been broken down into the following sections. </p> <ul><li id="GUID-90EBD7DC-CD75-5938-917D-550D3BF90196"><p> <xref href="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC.dita#GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC/GUID-FD49B0DB-2CC8-53CF-B114-FE9D62C3FC5F">Playing</xref> - describes the options for playing MIDI resources. This includes the ability to play MIDI events in realtime during playback. </p> </li> <li id="GUID-6F69D654-70EF-58AA-BD50-FC266B16689E"><p> <xref href="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC.dita#GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC/GUID-D7DF30C6-5763-521C-808C-189B04E7B576">Opening</xref> - describes the options available for opening MIDI resources after the <codeph>CMidiClientUtility</codeph> object has been instantiated. </p> </li> <li id="GUID-3079F694-D68F-5358-87F1-7D80A0444F24"><p> <xref href="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC.dita#GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC/GUID-32FDA9B1-099C-5FC3-9B52-AE2F288F6B9C">Control</xref> - describes how to control the MIDI player, or a MIDI song. </p> </li> <li id="GUID-B1D70D5F-3D60-566A-A6F6-8B65B0D43C99"><p> <xref href="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC.dita#GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC/GUID-E7257586-812E-52D6-A379-1077F67F1393">Information</xref> - describes how you can retrieve information from the MIDI player. </p> </li> <li id="GUID-A4076EEF-3C35-5F5D-8FAB-83BB201BD628"><p> <xref href="GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC.dita#GUID-A9AAADAF-12B1-5D0C-B8B3-6E7FDB9823DC/GUID-DE0AB6B1-70E7-5DD2-8ED6-410861FDF939">Events</xref> - handling MIDI events and notifications. </p> </li> </ul> </section> <section id="GUID-FD49B0DB-2CC8-53CF-B114-FE9D62C3FC5F"><title>Playing</title> <p>This class is intended for playing MIDI resources only. <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>CMidiClientUtility</apiname></xref> is capable of playing more than one clip within the same instance of the object. </p> <p>The play related methods are as follows: </p> <ul><li id="GUID-96545E05-E2EE-559D-90D3-29DCD27488C2"><p> <b>Starting and Stopping</b>  </p> <p>You can use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>Play</apiname></xref> 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 <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetPositionMicroSecondsL</apiname></xref> to set a starting position. </p> <p>You can also play a MIDI note even without a MIDI source, using <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>PlayNote</apiname></xref>, for example: </p> <codeblock id="GUID-2866D894-4189-5F8F-BA3E-980AD52C85B5" xml:space="preserve">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();

</codeblock> <p>When you use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>Stop</apiname></xref> 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. </p> </li> <li id="GUID-39951BBE-2949-5DF6-A2B7-4A36797FC3D2"><p> <b>MIPs and Events</b>  </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SendMipMessageL</apiname></xref> to send an SP-MIDI MIP message to the MIDI player. </p> <p>You can send real-time MIDI events to the MIDI player using <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>PlayNote</apiname></xref> or <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NoteOnL</apiname></xref>, or <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>StopNote</apiname></xref> and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NoteOffL</apiname></xref>. The MIDI file must be available to play back at the same time. </p> </li> <li id="GUID-8B3E305F-2BEF-5963-91DA-9B82F3335E2B"><p> <b>Timing</b>  </p> <p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetPositionMicroSecondsL</apiname></xref> provides a mechanism to synchronise the playback of the MIDI player with an external time base (the MIDI player act as a slave). </p> </li> </ul> </section> <section id="GUID-D7DF30C6-5763-521C-808C-189B04E7B576"><title>Opening</title> <p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>CMidiClientUtility</apiname></xref> provides methods to play multiple MIDI resources within a single instance. MIDI resources are not be opened during instantiation of the <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>CMidiClientUtility</apiname></xref> object. Instead, all MIDI resources must be opened using one of the open methods listed below. </p> <p>The following open methods are provided: </p> <codeblock id="GUID-92269EFD-C239-5377-A8D3-58086202535C" xml:space="preserve">OpenFileL(const TDesC&amp; aFileName);

OpenDesL(const TDesC8& aDescriptor);

OpenUrlL(const TDesC&amp; aUrl, TInt aIapId = KUseDefaultIap, const TDesC8&amp; aMimeType=KNullDesC8);</codeblock> <p>As soon as the open method has completed, successfully or otherwise, the callback function <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MMIDIClientUtilityObserver::MmcuoStateChanged()</apiname></xref> is called. </p> <p>If a MIDI file is already open and playing, use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>Stop()</apiname></xref> followed by <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>Close()</apiname></xref> to unload the clip before specifying new MIDI data to open. </p> </section> <section id="GUID-32FDA9B1-099C-5FC3-9B52-AE2F288F6B9C"><title>Control</title> <p>You can control the MIDI player, or a MIDI song, in the following ways: </p> <ul><li id="GUID-93109D35-7EC1-5F91-8DD1-E5761DDA4705"><p> <b>Setting the head position</b>  </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetPositionMicroSecondsLSet</apiname></xref> to set the playback head according to the time interval measured from the beginning of the MIDI data. </p> </li> <li id="GUID-AE9AFBAF-FC40-5A6E-A857-A1C42C0F9C66"><p> <b>Timing</b>  </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetRepeatsL</apiname></xref> 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. </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetStopTimeLSet</apiname></xref> to set the media time that the player must stop. </p> </li> <li id="GUID-F8830C38-4E52-55C2-8F08-01693294E05C"><p> <b>Muting</b>  </p> <p>Mute or unmute a MIDI channel or track with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetMuteL</apiname></xref>. </p> </li> <li id="GUID-2CA8A15E-D449-5D7B-87F6-0CC3D50F585B"><p> <b>Sound</b>  </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetTempoL</apiname></xref> to set the playback tempo of the current MIDI song. </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetPitchTranspositionL</apiname></xref> to set the global pitch transposition for the current MIDI song. </p> <p>Use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetVolumeL</apiname></xref> to sets the volume of the specified MIDI channel. </p> <p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetInstrumentL</apiname></xref> sets the program for the specified MIDI channel. </p> <p>You can send a "note on" message to a MIDI channel with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NoteOnL</apiname></xref>, and send a "note off" message with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NoteOffL</apiname></xref>. </p> </li> <li id="GUID-C9E56A2D-1C55-5084-BF06-15C55A37F3E0"><p> <b>Sound bank</b>  </p> <p>If you want to send a user instrument to the sound bank to replace a factory instrument, use <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>LoadInstrumentL</apiname></xref>. </p> <p>Set an alternative sound bank to the default with<xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetInstrumentLActivate</apiname></xref>, and reset to the default soundbank with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>SetInstrumentLReturn</apiname></xref>. </p> </li> </ul> </section> <section id="GUID-E7257586-812E-52D6-A379-1077F67F1393"><title>Information</title> <p>The <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>CMidiClientUtility</apiname></xref> class can return information about the MIDI player or MIDI songs in the following ways: </p> <ul><li id="GUID-FEDAA9AB-04F4-5C2E-8D7D-AA447AEAD45D"><p> <b>Timing</b>  </p> <p>The player's current media time is gained from <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>PositionMicroSeconds</apiname></xref>. 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. </p> <p>The duration of the MIDI data is retrieved with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>DurationMicroSecondsL</apiname></xref> (temporal) and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>DurationMicroBeatsL</apiname></xref> (metrical). The duration is based on the MIDI data played back at its default rate. </p> <p>The defined time at which the player will stop is returned by <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>StopTimeL</apiname></xref>. In case the stop time is not set, the API returns a pre-defined constant value. </p> </li> <li id="GUID-6312E100-D907-5B50-83C5-624958559018"><p> <b>Formats</b>  </p> <p>You can get the format of the MIDI data (such as SMF, XMF, MIME ) <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>using MimeTypeL</apiname></xref>. </p> <p>Use these functions to get the MIME content types supported <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NumberOfMimeTypesSupportedL</apiname></xref> and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MimeTypeL</apiname></xref>. </p> </li> <li id="GUID-68502473-DF7A-5FCB-963A-5F3F69AD04C5"><p> <b>Song information</b>  </p> <p>You can discover a wide range of information about the current MIDI data. </p> <table id="GUID-94A17BB9-B088-57B1-B402-5A009EEFB336"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p>The number of channels in the MIDI data </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>ChannelsUsedL</apiname></xref>  </p> </entry> </row> <row><entry><p>The number of tracks in the MIDI data </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NumTracksL</apiname></xref>  </p> </entry> </row> <row><entry><p>The current playback tempo of the MIDI song </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>TempoMicroBeatsPerMinuteL</apiname></xref>  </p> </entry> </row> <row><entry><p>The global pitch transposition currently in use </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>PitchTranspositionCentsL</apiname></xref>  </p> </entry> </row> <row><entry><p>The volume assigned to a specified MIDI channel </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>VolumeL</apiname></xref>  </p> </entry> </row> <row><entry><p>A list of installed instrument banks </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NumberOfBanksL</apiname></xref> and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>GetBankIdL</apiname></xref>. </p> </entry> </row> <row><entry><p>Program numbers for a given instrument bank </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NumberOfInstrumentsL</apiname></xref> and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>GetInstrumentIdL</apiname></xref>  </p> </entry> </row> <row><entry><p>The name of the program for a given instrument bank and program number </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>InstrumentNameL</apiname></xref>  </p> </entry> </row> <row><entry><p>The name of the key for a given instrument bank, program number and key </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>PercussionKeyNameL</apiname></xref>  </p> </entry> </row> <row><entry><p>Information regarding whether the sound bank can be queried </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>NumberOfBanksL</apiname></xref> and <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>GetBankIdL</apiname></xref>  </p> </entry> </row> </tbody> </tgroup> </table> </li> </ul> </section> <section id="GUID-DE0AB6B1-70E7-5DD2-8ED6-410861FDF939"><title>Events</title> <p>The MIDI API allows you to monitor MIDI progress. </p> <ul><li id="GUID-88647BBF-920E-5C66-A971-070C85AC65A9"><p> <b>Status</b>  </p> <p>You can discover the current state of the MIDI data with <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>Status</apiname></xref>. This can tell you if MIDI data is playing, or a MIDI file is open but no playback operation is in progress. </p> </li> <li id="GUID-9D4C8BF4-B4F6-584C-B9C2-0294C88E1A0E"><p> <b>Callback mechanisms</b>  </p> <p>The MIDI player provides a set of callback mechanisms. </p> <table id="GUID-433A8323-521A-5CD0-98B9-4001502B45DC"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><tbody><row><entry><p>The player has stopped: </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoStateChanged</apiname></xref>. You can pass the media time that the player stopped with the callback mechanism. </p> </entry> </row> <row><entry><p>The player has reached the end of the media </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoStateChanged</apiname></xref>. The playback has been completed. You can pass the media time that the player stopped with the callback mechanism. </p> </entry> </row> <row><entry><p>The playback tempo has changed </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoTempoChanged</apiname></xref>. The callback returns the new tempo as a parameter. </p> </entry> </row> <row><entry><p>A SP-MIDI MIP message has been received </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoMipMessageReceived</apiname></xref>  </p> </entry> </row> <row><entry><p>Metadata found </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoMetaDataEntryFound</apiname></xref>. The metadata contained in the MIDI data is passed to the application. </p> </entry> </row> <row><entry><p>The playback of SP-MIDI file has gone silent due to system constraints </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoStateChanged</apiname></xref>  </p> </entry> </row> <row><entry><p>The song position has been changed </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoPositionChanged</apiname></xref>. The callback returns the new song position as a parameter. </p> </entry> </row> <row><entry><p>The playback state has changed </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoStateChanged</apiname></xref>. The callback returns the new playback state as a parameter. </p> </entry> </row> <row><entry><p>The volume of one of the channels has been changed </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoVolumeChanged</apiname></xref>. The API provides a callback mechanism to indicate that. The callback returns the channel number and the new volume level as parameters. </p> </entry> </row> <row><entry><p>One of the channels' muting status has been changed </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoMuteChanged</apiname></xref>. The callback returns the channel number and the new channel muting status as parameters. </p> </entry> </row> <row><entry><p>The audio policy has taken over the MIDI player resources </p> </entry> <entry><p> <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoStateChanged</apiname></xref>  </p> </entry> </row> </tbody> </tgroup> </table> </li> </ul> <p>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): <xref href="GUID-533353BF-BBDC-3841-A46F-12B5FD67E186.dita"><apiname>MmcuoSyncUpdateL</apiname></xref>  </p> </section> <section><title>See also</title> <p> <xref href="GUID-61E219A3-7D9D-5AAA-B6B3-61F0749E12B3.dita">MIDI Client Overview</xref>  </p> </section> </conbody></concept>