<doc>
	<legacy_id></legacy_id>
	<name>mobilePlaySoundOnChannel</name>
	<type>command</type>

	<syntax>
		<example>mobilePlaySoundOnChannel <i>sound</i>, <i>channel</i>, <i>type</i></example>
	</syntax>

	<synonyms>
		<synonym>iphonePlaySoundOnChannel</synonym>
	</synonyms>

	<summary>Plays a sound on a given channel.</summary>

	<examples>
<example>mobilePlaySoundOnChannel theSound, theChannel, theType</example>
<example>mobilePlaySoundOnChannel &quot;sounds/warning.mp4&quot;, &quot;queued&quot;, &quot;next&quot;</example>
<example><p>put specialFolderPath(&quot;engine&quot;) &amp; &quot;/sounds/applause.mp4&quot; into tSoundFile</p><p>mobilePlaySoundOnChannel tSoundFile, &quot;current&quot;, &quot;now&quot;</p></example>
	</examples>

	<history>
		<introduced version="4.6">Introduced</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="5.5">Android support added</changed>
	</history>

	<objects>
	</objects>

	<platforms>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>sound</category>
	</classification>

	<references>
		<function tag="mobileSoundChannelVolume">mobileSoundChannelVolume Function</function>
		<function tag="mobileSoundOnChannel">mobileSoundOnChannel Function</function>
		<function tag="mobileNextSoundOnChannel">mobileNextSoundOnChannel Function</function>
		<function tag="mobileSoundChannels">mobileSoundChannels Function</function>
		<function tag="mobileSoundChannelStatus">mobileSoundChannelStatus Function</function>
		<command tag="mobilePlaySoundOnChannel">mobilePlaySoundOnChannel Command</command>
		<command tag="mobileStopPlayingOnChannel">mobileStopPlayingOnChannel Command</command>
		<command tag="mobilePausePlayingOnChannel">mobilePausePlayingOnChannel Command</command>
		<command tag="mobileResumePlayingOnChannel">mobileResumePlayingOnChannel Command</command>
		<command tag="mobileSetSoundChannelVolume">mobileSetSoundChannelVolume Command</command>
		<command tag="mobileDeleteSoundChannel">mobileDeleteSoundChannel Command</command>
		<message tag="soundFinishedOnChannel">soundFinishedOnChannel Message</message>
	</references>

	<description>
	<overview>Use the <b>mobilePlaySoundOnChannel</b> command to play a sound on a given channel.</overview>

		<parameters>
  <parameter>
    <name>sound</name>
    <description>The sound file to be played.</description>
  </parameter>
  <parameter>
    <name>channel</name>
    <description>The name of the channel to play the sound on.</description>
  </parameter>
  <parameter>
    <name>type</name>
    <description>One of:</description>
    <options title="">
      <option>
        <item>now</item>
        <description>The sound is played immediately, replacing any current sound (and queued sound) on the channel.</description>
      </option>
      <option>
        <item>next</item>
        <description>The sound is queued to play immediately after the current sound. If no sound is playing the sound is prepared to play now, but the channel is immediately paused. This allows the sound to be prepared in advance of it being needed.</description>
      </option>
      <option>
        <item>looping</item>
        <description>The sound is played immediately, replacing any current sound (and queued sound) on the channel and is looped indefinitely.</description>
      </option>
    </options>
  </parameter>		</parameters>

	<value></value>
	<comments>If a sound channel with the given name doesn't exist a new one is created. When queuing a sound using <i>next</i>, the engine will 'pre-prepare' the sound long before the current sound is played, this ensures minimal latency between the current sound ending and the next one beginning.<p></p><p>If an empty string is passed as the <i>sound</i> parameter, the current and scheduled sound on the given channel will be stopped and cleared.</p><p></p><p>When the sound has finished playing naturally (not stopped/replaced) on a given channel, a <message tag="soundFinishedOnChannel">soundFinishedOnChannel</message> message is sent to the object which played the sound.</p></comments>
	</description>
</doc>