<ul class="toc">
<li><a href="#volume">Volume Control</a></li>
<li><a href="#type">Sound Session Types</a></li>
+ <li><a href="#stream">Sound Stream Policy</a></li>
<li><a href="#query">Sound Device Query</a></li>
</ul>
<p class="toc-title">Related Info</p>
<li><a href="#volume">Volume control</a>
<p>Control the output volume by managing the sound type and its volume level.</p></li>
-<li><a href="#type">Sound session types</a>
-<p>Set the sound session type, which specifies the behavior of your application sound across the system.</p></li>
+<li><a href="#type">Sound session types (Deprecated)</a>
+<p>Set the sound session type, which specifies the behavior of your application sound across the system. (see <a href="#stream">Sound Stream Policy</a> for substitute)</p></li>
+
+<li><a href="#stream">Sound Stream Policy (Since 2.4)</a>
+<p>Set the attributes of your application's sound stream, which specify the behavior of the sound stream across the system.</p></li>
<li><a href="#query">Sound device query</a>
<p>Using the query functions, you can get various information, such as the state of the sound devices.</p></li>
</tbody>
</table>
-<h2 id="type" name="type">Sound Session Types</h2>
+<h2 id="type" name="type">Sound Session Types (Deprecated)</h2>
<p>The Sound Manager API offers 5 different sound session types: media, alarm, notification, emergency and VOIP. According to these types, your application's audio works in a specific way to mix with sounds of other applications or to respond to an audio interruption made by another application.</p>
<p>You can also set options for resuming the media session when the interruption ends by using the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__SOUND__MANAGER__SESSION__MODULE.html#ga20d1d7fa84dc322f03b58d42806cd9d9">sound_session_option_for_resumption_e</a> enumerator. The sound system notifies the media session when the interruption ends, and you are able to resume your session.</p>
+<h2 id="stream" name="stream">Sound Stream Policy (Since 2.4)</h2>
+
+<p>Setting sound stream policy is a newly added concept to replace sound session. Instead of sound session types, Sound Manager now provides sound stream types, and stream focus to moderate the sound streams.</p>
+
+<h3>Obtain sound stream informaion handle</h3>
+
+<p>Use the sound_manager_create_stream_information() function to create a stream info handle, and set the stream type to the handle. Once created, this handle will be used throughout the playback or recording stream APIs(e.g., Player, Wave-Player, Audio-Io, etc.). Your application can have multiple stream info handles and each handles can have multiple sound streams.</p>
+
+<p>There are 8 sound stream types to define the nature of your sound steam, and those are:</p>
+
+<ul><li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_MEDIA</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_SYSTEM</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_ALARM</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_NOTIFICATION</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_EMERGENCY</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_VOICE_INFORMATION</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_VOICE_RECOGNITION</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_RINGTONE_VOIP</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_TYPE_VOIP</span></li></ul>
+
+<p>Fundamentally, SYSTEM, ALARM, NOTIFICATION, EMERGENCY, VOICE_INFORMATION and RINGTONE_VOIP types are considered as playback stream, and VOICE_RECOGNITION type as recording stream. MEDIA type can be both playback and recording stream uppon your usage, and VOIP type has the nature of both playback and recording stream. According to these type, the routing path, and sound type are determined internally through the system.</p>
+
+<p>Notice that only playback stream types are matched to sound types which are used for <a href="#volume">Volume control</a>.</p>
+
+<table>
+<caption>
+Table: Correspoding sound types for playback stream types
+</caption>
+<tbody>
+<tr>
+<th>Sound Stream Type</th>
+<th>Sound Type</th>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_MEDIA</td>
+<td>SOUND_TYPE_MEDIA</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_SYSTEM</td>
+<td>SOUND_TYPE_SYSTEM</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_ALARM</td>
+<td>SOUND_TYPE_ALARM</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_NOTIFICATION</td>
+<td>SOUND_TYPE_NOTIFICATION</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_VOICE_INFORMATION</td>
+<td>SOUND_TYPE_VOICE</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_RINGTONE_VOIP</td>
+<td>SOUND_TYPE_RINGTONE</td>
+</tr>
+<tr>
+<td>SOUND_STREAM_TYPE_VOIP</td>
+<td>SOUND_TYPE_VOIP</td>
+</tr>
+</tbody>
+</table>
+
+<h3>Managing Stream Focus</h3>
+
+<p>Unlike setting sound session types, setting sound stream types and acquiring focus relatively give you more independence for your application's audio behavior. In sound session concept, it is the system that has the authority whether to stop or play the stream. However, in stream focus concept, you have the authority to control the steam of sound accross the system.</P>
+
+<p>To activate your sound stream, you should acquire stream focus. Once acquired, you are free to start playback or recording sound. Acquiring stream focus is possible anytime after the stream info handle has been creaated.</p>
+
+<p>Sound Manager offers steam focus for both playback and recording, meaning you can independetly control the playback and recording steam.</p>
+
+<ul><li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_FOCUS_FOR_PLAYBACK = 0x0001</span></li>
+<li><span style="font-family: Courier New,Courier,monospace">SOUND_STREAM_FOCUS_FOR_RECORDING = 0x0002</span></li></ul>
+
+<p>Let's say your stream type is for playback, and there are two different streams are activated, one for playback, the other for recording. If you want to activate your playback stream and has no intention to interrupt the current recording stream, you only need to acquire playback focus, to stop the current playback stream, and start to play yours. And vice versa.</p>
+
+<p>However, don't be misguided that you can only acquire stream focus based on the strem types of yours. Even though your stream type is playback, you can also acquire recording focus if you want to stop recording stream while your stream playing. To long story make short, you can acquire both playback and recording focus for your stream at the same time.</p>
+
+<p>To acquire stream focus, use the sound_manager_acquire_focus()function. You will need a stream info hadle to specify which sound stream you want to acquire the focus.</p>
+
+<p>Don't forget to call the sound_manager_release_focus() function when you no longer need the stream focus, so that the other sound stream might resume.</p>
+
+<p>You are able to get a notice when the sate of stream focus changes through the sound_stream_focus_state_changed_cb() callback you've set when creating the stream info handle. If released, you are obliged to stop your sound stream. If acquired, you might want to resume your stream.</p>
+
<h2 id="query" name="query">Sound Device Query</h2>
<p>The audio behavior of your application must differ in accordance with the various sound devices that are connected.</p>
</script>
</body>
-</html>
\ No newline at end of file
+</html>
<p class="toc-title">Content</p>
<ul class="toc">
<li><a class="opensection" href="#set">Setting the Sound Session Type</a></li>
+ <li><a class="opensection" href="#stream">Setting the Sound Stream Information</a></li>
+ <li><a class="opensection" href="#focus">Managing Stream Focus</a></li>
<li><a class="opensection" href="#manage">Managing Volume Control</a></li>
<li><a class="opensection" href="#query">Querying Sound Devices</a></li>
<li><a class="opensection" href="#session">Managing Sound Manager Session Parameters</a></li>
<p>Become familiar with the Sound Manager API basics by learning about:</p>
<ul>
-<li><a class="opensection" href="#set">Setting the Sound Session Type</a>
+<li><a class="opensection" href="#set">Setting the Sound Session Type (deprecated)</a>
<p>Set a sound session type for your application.</p></li>
+<li><a class="opensection" href="#stream">Setting the Sound Stream Information (since 2.4)</a>
+<p>Create a sound stream information handle.</p></li>
+
+<li><a class="opensection" href="#focus">Managing Stream Focus (since 2.4)</a>
+<p>Control the stream focus of your sound stream.</p></li>
+
<li><a class="opensection" href="#manage">Managing Volume Control</a>
<p>Control the volume of your application.</p></li>
<pre class="prettyprint">error_code = sound_manager_set_session_interrupted_cb(_sound_session_interrupted_cb, NULL);
</pre></li></ol>
</div>
- </li>
+ </li>
+
+ <ul class="devicespecifications">
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="stream" name="stream" class="items-tit-h2">Setting the Sound Stream Information</h2>
+<span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+<p>To creat and set sound stream informaion handle:</p>
+
+
+<ol><li><p>To use the functions and data types of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__SOUND__MANAGER__MODULE.html">Sound Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sound_manager.h></span> header file in your application:</p>
+<pre class="prettyprint">
+#include <sound_manager.h>
+</pre></li>
+
+<li>Create the sound stream informaion handle.
+<p>Create the sound stream info handle using the <span style="font-family: Courier New,Courier,monospace">sound_manager_create_stream_information()</span> function. The function sets the type of your sound stream, and registers the sound_stream_focus_state_cahnged_cb() callback function.</p>
+
+<p>The <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__SOUND__MANAGER__SESSION__MODULE.html#ga125699870d48881ea153a4fce7140958">sound_stream_type_e</a> enumeration defines the available sound stream types.</p>
+<pre class="prettyprint">int error_code;
+sound_stream_info_h stream_info;
+
+error_code = sound_manager_create_stream_information(SOUND_STREAM_TYPE_MEDIA, _sound_stream_focus_state_changed_cb, NULL, &stream_info);
+</pre>
+<p>Use this stream_info to handle your playback/recording stream.</p>
+<p>See <a class="opensection" href="#focus">Managing Stream Focus</a> to define sound_stream_focus_state_cahnged_cb() callback</li></ol>
+ </div>
+ </li>
+ <li>
+ <div class="devicespec-tit">
+ <h2 id="focus" name="focus" class="items-tit-h2">Managing Stream Focus</h2>
+<span class="fr"><a href="#" class="bt-arr"><em>Hide</em></a></span>
+ </div>
+ <div class="devicespec-con">
+<p>Control the stream focus of your sound stream:</p>
+
+
+<ol><li><p>To use the functions and data types of the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__SOUND__MANAGER__MODULE.html">Sound Manager</a> API, include the <span style="font-family: Courier New,Courier,monospace"><sound_manager.h></span> header file in your application:</p>
+<pre class="prettyprint">
+#include <sound_manager.h>
+</pre></li>
+
+<li>Managing stream focus.
+<p>Acquire a stream focus for your sound stream using the <span style="font-family: Courier New,Courier,monospace">sound_manager_acquire_focus()</span> function. Pass the stream_info handle you've create to specify which sound stream you want to acquire the focus. Once you succeed to acquire the focus, you are free to activate your sound stream.</p>
+<p>Release the stream focus when you no longer need the focus for your sound stream using the <span style="font-family: Courier New,Courier,monospace">sound_manager_release_focus()</span> function. Also, pass the stream_info handle to specify the sound stream.
+<p>Use the <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MEDIA__SOUND__MANAGER__SESSION__MODULE.html#ga125699870d48881ea153a4fce7140958">sound_stream_focus_mask_e</a> enumeration to set the type of stream focus.</p>
+<pre class="prettyprint">int error_code;
+sound_stream_focus_mask_e focus_mask;
+
+focus_mask = SOUND_STREAM_FOCUS_FOR_PLAYBACK | SOUND_STREAM_FOCUS_FOR_RECORDING;
+//Masking is possible to acquire both playback and recording focus.
+
+error_code = sound_manager_acquire_focus(stream_info, focus_mask, NULL);
+if (!error_code)
+ //Activate your sound stream
+
+//Your sound stream has finished
+error_code = sound_manager_release_focus(stream_info, focus_mask, NULL);
+</pre></li>
+
+<li>Subscribe to the stream focus change notifications.
+<p>To be informed when a stream focus change has occurred, define the <span style="font-family: Courier New,Courier,monospace">sound_stream_focus_state_changed_cb()</span> callback function:</p>
+<p>You need to call the sound_manager_get_focus_state() function to get current state of your stream focus.</p>
+<p>The snippet below is for the sound stream which has both playback and recording focus.</p>
+
+<pre class="prettyprint">static void sound_stream_focus_state_changed_cb(sound_stream_info_h stream_info, sound_stream_focus_change_reason_e reason_for_change, const char *additional_info, void *user_data)
+{
+ int error_code;
+ sound_stream_focus_state_e state_for_playback;
+ sound_stream_focus_state_e state_for_recording;
+
+ error_code = sound_manager_get_focus_state(stream_info, &state_for_playback, &state_for_recording);
+ if(!error_code) {
+ if(state_for_playback == SOUND_STREAM_FOCUS_STATE_RELEASED || state_for_recording == SOUND_STREAM_FOCUS_STATE_RELEASED)
+ //You lost your focus, pause/stop your sound stream
+ if(state_for_playback == SOUND_STREAM_FOCUS_STATE_ACQUIRED && state_for_recording == SOUND_STREAM_FOCUS_STATE_ACQUIRED)
+ //You regained your focus, you might resume your sound stream
+ printf("The stream focus changed by [%d]", reason_for_change);
+}
+</pre></li>
+<p>Register the callback fucntion when you create the stream_info handle. See <a class="opensection" href="#stream">Setting the Sound Stream Information</a> to create the stream_info handle.</p>
+ </div>
+ </li>
<li>
<div class="devicespec-tit">
<h2 id="manage" name="manage" class="items-tit-h2">Managing Volume Control</h2>
<p>To start and stop playing a tone:</p>
<ol>
-<li>To start playback, use the <span style="font-family: Courier New,Courier,monospace">tone_player_start()</span> function. The player ID is assigned if the function succeeds. The function takes the following parameters:
+<li>To start playback, use the <span style="font-family: Courier New,Courier,monospace">tone_player_start()</span> function (deprecated, use tone_player_start_with_stream_info() instead). The player ID is assigned if the function succeeds. The function takes the following parameters:
<ul class="ul">
<li>Tone type, selected from the <span style="font-family: Courier New,Courier,monospace">tone_type_e</span> enum, defines which tone type to use (such as DTMF0 or DTMF1).</li>
<li>Media sound type, from the <span style="font-family: Courier New,Courier,monospace">sound_type_e</span> enum, defines which sound type is used (such as <span style="font-family: Courier New,Courier,monospace">NOTIFICATION</span>, <span style="font-family: Courier New,Courier,monospace">ALARM</span>, or <span style="font-family: Courier New,Courier,monospace">RINGTONE</span>).</li>
<pre class="prettyprint">tone_player_start(TONE_TYPE_DEFAULT, SOUND_TYPE_MEDIA, -1, &tone_player_id);</pre>
</li>
+<li>Since Tizen 2.4, it is recommended to use the <span style="font-family: Courier New,Courier,monospace">tone_player_start_with_stream_info()</span> function to start playback. The player ID is assigned if the function succeeds. The function takes the following parameters:
+ <ul class="ul">
+ <li>Tone type, selected from the <span style="font-family: Courier New,Courier,monospace">tone_type_e</span> enum, defines which tone type to use (such as DTMF0 or DTMF1).</li>
+ <li>Sound stream information handle, you've created with <span style="font-family: Courier New,Courier,monospace">sound_manager_create_stream_informaion()</span> function, defines which sound stream is used (see <a href="sound_manager_tutorial_n.htm">Sound Manager Tutorial</a> to learn how to create the sound stream information handle).</li>
+ <li>Tone duration in milliseconds. If the duration is set to -1, the playback continues infinitely.</li>
+ <li>Player ID is an output parameter, and its value is set by the function. The ID of the tone player that started first is 0, the ID of the second is 1, and so on. If you determine the value to be <span style="font-family: Courier New,Courier,monospace">NULL</span>, the ID is not returned.</li>
+ </ul>
+
+<pre class="prettyprint">tone_player_start_with_stream_info(TONE_TYPE_DEFAULT, stream_info, -1, &tone_player_id);</pre>
+</li>
+
<li>To stop the playback, use the <span style="font-family: Courier New,Courier,monospace">tone_player_stop()</span> function with the ID of the player which you want to stop:
<pre class="prettyprint">tone_player_stop(tone_player_id);</pre>
</li>
</div>
<div class="devicespec-con">
-<p>To start playing a tone, use the <span style="font-family: Courier New,Courier,monospace">tone_player_start()</span> function with the tone type, sound type, and duration time as parameters. In this example, a congestion tone is played as a call sound for 1 second (1000 milliseconds):</p>
-<pre class="prettyprint">tone_player_start(TONE_TYPE_SUP_CONGESTION, SOUND_TYPE_CALL, 1000, &tone_player_id);</pre>
+<p>To start playing a tone, use the <span style="font-family: Courier New,Courier,monospace">tone_player_start_with_stream_info()</span> function with the tone type, stream_info handle, and duration time as parameters. In this example, a congestion tone is played as a call sound for 1 second (1000 milliseconds):</p>
+<pre class="prettyprint">tone_player_start_with_stream_info(TONE_TYPE_SUP_CONGESTION, stream_info, 1000, &tone_player_id);
+</pre>
<p>When the duration is set to a specified time, playing is stopped automatically. You can also use the <span style="font-family: Courier New,Courier,monospace">tone_player_stop()</span> function to stop the playback manually.</p>
</div>
</li>
<p>Implement a callback function that is called when the WAV file is no longer being played.</p>
-<p>Declare a variable which keeps the return value of the function. Invoke the <span style="font-family: Courier New,Courier,monospace">wav_player_start()</span> function to play the WAV file:</p>
-
+<p>Declare a variable which keeps the return value of the function. Invoke the <span style="font-family: Courier New,Courier,monospace">wav_player_start_with_stream_info() or wav_player_start()</span> function to play the WAV file.</p>
+<p>Notice that the <span style="font-family: Courier New,Courier,monospace">wav_player_start()</span> is deprecated. It is recommended to use the <span style="font-family: Courier New,Courier,monospace">wav_player_start_with_stream_info()</span> since Tizen 2.4.</p>
+<p>You need a sound stream information handle to pass to the <span style="font-family: Courier New,Courier,monospace">wav_player_start_with_stream_info()</span>. see <a href="sound_manager_tutorial_n.htm">Sound Manager Tutorial</a> to learn how to create the sound stream information handle.</p>
<pre class="prettyprint">
static void _playback_completed_cb(int id, void *user_data)
int wav_player_id;
wav_player_error_e ret;
const char* wav_path = "/tmp/test.wav";
+ sound_stream_info_h stream_info;
+
+ ...
- ret = wav_player_start(wav_path, SOUND_TYPE_MEDIA, _playback_completed_cb, (void*)wav_path, &wav_player_id);
+ ret = wav_player_start_with_stream_info(wav_path, stream_info, _playback_completed_cb, (void*)wav_path, &wav_player_id); //Since Tizen 2.4
+ ret = wav_player_start(wav_path, SOUND_TYPE_MEDIA, _playback_completed_cb, (void*)wav_path, &wav_player_id); //Depricated
}
</pre>
</li>
projects / sdk / online-doc.git / commitdiff
