<library name="Audio">
	<description>Provides audio functionality for games using the Game library. All sound resources must be OGG files. </description>
	<namespace name="Audio">
		<class name="MusicNotFoundException" parent="Core.Exception">
			<description>An exception thrown when the music being attempted to load is not found.</description>
		</class>

		<class name="Music">
			<description>Encapsulates a sound file for the purpose of playing music. Supports looping and fading transitions, but only supports one sound playback at a time.</description>
			<function name="loadFromResource" static="true">
				<arg name="path" type="string" description="path to a bundled OGG resource"/>
				<returns type="Audio.Music" description="A new Audio.Music instance"/>
			</function>
			<function name="getCurrent" static="true">
				<returns type="Audio.Music" description="The currently playing music."/>
			</function>
			<function name="fadeOutAndIn">
				<arg name="loop" type="bool" optional="true" default="true" description="True if this music should loop indefinitely."/>
				<arg name="outTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade the current music out"/>
				<arg name="inTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade this music in"/>
				<description>Fades out the currently playing music (if any) and fades in this music.</description>
			</function>
			<function name="fadeOutAndPlay">
				<arg name="loop" type="bool" optional="true" default="true" description="True if this music should loop indefinitely."/>
				<arg name="outTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade the current music out"/>
				<description>Fades out the currently playing music (if any) and starts playing this music.</description>
			</function>
			<function name="play">
				<arg name="loop" type="bool" optional="true" default="true" description="True if this music should loop indefinitely."/>
				<description>Stops the currently playing music (if any) and starts playing this music.</description>
			</function>
			<function name="fadeOut">
				<arg name="outTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade out"/>
				<description>Fades out this music if it is currently playing. See also Music.fadeOutCurrent()</description>
			</function>
			<function name="fadeOutCurrent" static="true">
				<arg name="outTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade the current music out"/>
				<description>Fades out the current music, if any.</description>
			</function>
			<function name="stop" static="true">
				<description>Stops the current music, if any.</description>
			</function>
			<function name="fadeIn">
				<arg name="loop" type="bool" optional="true" default="true" description="True if this music should loop indefinitely."/>
				<arg name="inTransition" type="float" optional="true" default="2.0" description="Number of seconds to fade this music in"/>
				<description>Stops the currently playing music (if any) and fades in this music.</description>
			</function>
		</class>

		<enum name="SoundPlayState" description="Current state of a sound">
			<value name="PLAYING" description="Sound is currently playing"/>
			<value name="PAUSED" description="Sound is paused"/>
			<value name="STOPPED" description="Sound has stopped"/>
		</enum>

		<class name="Sound">
			<description>
				Represents a sound that is currently active.
				Sound instances are created from the SoundResource.play() method.
			</description>
			<function name="getState">
				<returns type="Audio.SoundPlayState" description="Current state of the sound playback."/>
				<description>Gets the current state of the sound playback.</description>
			</function>
			<function name="resume">
				<description>Resumes a sound that has been paused.</description>
			</function>
			<function name="stop">
				<description>Stops a sound that is playing. It cannot be resumed. If you want to resume playback, use pause() instead.</description>
			</function>
			<function name="getResource">
				<returns type="Audio.SoundResource" description="Reference to the original SoundResource"/>
				<description>Gets a reference to the original SoundResource object of this Sound.</description>
			</function>
			<function name="setPan">
				<arg name="value" type="float" description="The pan value as a ratio from -1.0 to 1.0. 0.0 represents a centered sound, while -1 will play exclusively from the left speak and 1 will play from the right speaker."/>
				<description>Sets the pan value for this sound. Pan is not always supported by the platform, in which case this function will do nothing.</description>
			</function>
			<function name="getPan">
				<returns type="float">Pan value</returns>
				<description>
					Gets the pan value for this sound. 
					Pan is a value from -1.0 to 1.0 that represents which speaker this sound should come out of. 
					-1.0 is the left speaker, 1.0 is the right speaker, and 0.0 is centered. 
					Pan is not supported on all platforms, but this value is still persisted and returned after setting it with setPan or play.
				</description>
			</function>
			<function name="setVolume">
				<arg name="ratio" type="float" description="A volume ratio between 0.0 and 1.0"/>
				<description>Sets the volume of the currently playing sound. See also Audio.SoundResource.setDefaultVolume.</description>
			</function>
			<function name="getVolume">
				<returns type="float" description="The current volume of the sound as a ratio from 0.0 to 1.0"/>
				<description>Gets the the current volume of the playing sound.</description>
			</function>
		</class>

		<class name="SoundResource">
			<description>Represents a file that can be played as a sound effect.</description>
			<function name="setDefaultVolume">
				<arg name="ratio" type="float" description="A volume ratio from 0.0 to 1.0."/>
				<description>Sets the default volume ratio for Audio.Sound objects that are played from this resource.</description>
			</function>
			<function name="getDefaultVolume">
				<returns type="float" description="Volume ratio from 0.0 to 1.0."/>
				<description>Gets the default volume ratio for Audio.Sound objects that are played from this resource.</description>
			</function>
			<function name="loadFromFile" static="true">
				<arg name="path" type="string" description="Absolute or relative path to a sound file on the local disk."/>
				<returns type="Audio.SoundResource"/>
				<description>Creates a new Audio.SoundResource instance for the given file.</description>
			</function>
			<function name="loadFromResource" static="true">
				<arg name="path" type="string" description="Path to a bundled resource"/>
				<returns type="Audio.SoundResource"/>
				<description>Creates a new Audio.SoundResource instance for the given bundled resource.</description>
			</function>
			<function name="play">
				<arg name="pan" type="float" optional="true" default="0.0" description="Default pan value for playing this sound."/>
				<returns type="Audio.Sound" description="A reference to the Sound scoped to this playback instance that can be used to pause, change volume, change pan, etc."/>
				<description>
					Plays this SoundResource.
					Returns a handle to a Audio.Sound instance which represents the current playback session. 
					This handle can be used to pause the sound or change attributes of the playback such as volume and pan.
					Ignoring this handle is okay as well, if you want the sound to play normally without changing attributes or pausing it.
					You can optionally also pass in a default pan value to control which speakers this sound plays from (rather than adjusting it while it's playing).
				</description>
			</function>
		</class>

	</namespace>
</library>
