1/* Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6/** 7 * This file defines the <code>PPB_Audio</code> interface, which provides 8 * realtime stereo audio streaming capabilities. 9 */ 10 11label Chrome { 12 M14 = 1.0, 13 M31 = 1.1 14}; 15 16/** 17 * <code>PPB_Audio_Callback</code> defines the type of an audio callback 18 * function used to fill the audio buffer with data. Please see the 19 * Create() function in the <code>PPB_Audio</code> interface for 20 * more details on this callback. 21 * 22 * @param[in] sample_buffer A buffer to fill with audio data. 23 * @param[in] buffer_size_in_bytes The size of the buffer in bytes. 24 * @param[in] latency How long before the audio data is to be presented. 25 * @param[inout] user_data An opaque pointer that was passed into 26 * <code>PPB_Audio.Create()</code>. 27 */ 28typedef void PPB_Audio_Callback([out] mem_t sample_buffer, 29 [in] uint32_t buffer_size_in_bytes, 30 [in, version=1.1] PP_TimeDelta latency, 31 [inout] mem_t user_data); 32 33/** 34 * The <code>PPB_Audio</code> interface contains pointers to several functions 35 * for handling audio resources. Refer to the 36 * <a href="/native-client/devguide/coding/audio.html">Audio</a> 37 * chapter in the Developer's Guide for information on using this interface. 38 * Please see descriptions for each <code>PPB_Audio</code> and 39 * <code>PPB_AudioConfig</code> function for more details. A C example using 40 * <code>PPB_Audio</code> and <code>PPB_AudioConfig</code> follows. 41 * 42 * <strong>Example: </strong> 43 * 44 * @code 45 * void audio_callback(void* sample_buffer, 46 * uint32_t buffer_size_in_bytes, 47 * void* user_data) { 48 * ... quickly fill in the buffer with samples and return to caller ... 49 * } 50 * 51 * ...Assume the application has cached the audio configuration interface in 52 * audio_config_interface and the audio interface in 53 * audio_interface... 54 * 55 * uint32_t count = audio_config_interface->RecommendSampleFrameCount( 56 * PP_AUDIOSAMPLERATE_44100, 4096); 57 * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit( 58 * pp_instance, PP_AUDIOSAMPLERATE_44100, count); 59 * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config, 60 * audio_callback, NULL); 61 * audio_interface->StartPlayback(pp_audio); 62 * 63 * ...audio_callback() will now be periodically invoked on a separate thread... 64 * @endcode 65 */ 66interface PPB_Audio { 67 /** 68 * Create() creates an audio resource. No sound will be heard until 69 * StartPlayback() is called. The callback is called with the buffer address 70 * and given user data whenever the buffer needs to be filled. From within the 71 * callback, you should not call <code>PPB_Audio</code> functions. The 72 * callback will be called on a different thread than the one which created 73 * the interface. For performance-critical applications (i.e. low-latency 74 * audio), the callback should avoid blocking or calling functions that can 75 * obtain locks, such as malloc. The layout and the size of the buffer passed 76 * to the audio callback will be determined by the device configuration and is 77 * specified in the <code>AudioConfig</code> documentation. 78 * 79 * @param[in] instance A <code>PP_Instance</code> identifying one instance 80 * of a module. 81 * @param[in] config A <code>PP_Resource</code> corresponding to an audio 82 * config resource. 83 * @param[in] audio_callback A <code>PPB_Audio_Callback</code> callback 84 * function that the browser calls when it needs more samples to play. 85 * @param[in] user_data A pointer to user data used in the callback function. 86 * 87 * @return A <code>PP_Resource</code> containing the audio resource if 88 * successful or 0 if the configuration cannot be honored or the callback is 89 * null. 90 */ 91 PP_Resource Create( 92 [in] PP_Instance instance, 93 [in] PP_Resource config, 94 [in] PPB_Audio_Callback audio_callback, 95 [inout] mem_t user_data); 96 97 /** 98 * IsAudio() determines if the provided resource is an audio resource. 99 * 100 * @param[in] resource A <code>PP_Resource</code> corresponding to a generic 101 * resource. 102 * 103 * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code> 104 * if the given resource is an Audio resource, otherwise 105 * <code>PP_FALSE</code>. 106 */ 107 PP_Bool IsAudio( 108 [in] PP_Resource resource); 109 110 /** 111 * GetCurrrentConfig() returns an audio config resource for the given audio 112 * resource. 113 * 114 * @param[in] config A <code>PP_Resource</code> corresponding to an audio 115 * resource. 116 * 117 * @return A <code>PP_Resource</code> containing the audio config resource if 118 * successful. 119 */ 120 PP_Resource GetCurrentConfig( 121 [in] PP_Resource audio); 122 123 /** 124 * StartPlayback() starts the playback of the audio resource and begins 125 * periodically calling the callback. 126 * 127 * @param[in] config A <code>PP_Resource</code> corresponding to an audio 128 * resource. 129 * 130 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if 131 * successful, otherwise <code>PP_FALSE</code>. Also returns 132 * <code>PP_TRUE</code> (and be a no-op) if called while playback is already 133 * in progress. 134 */ 135 PP_Bool StartPlayback( 136 [in] PP_Resource audio); 137 138 /** 139 * StopPlayback() stops the playback of the audio resource. 140 * 141 * @param[in] config A <code>PP_Resource</code> corresponding to an audio 142 * resource. 143 * 144 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if 145 * successful, otherwise <code>PP_FALSE</code>. Also returns 146 * <code>PP_TRUE</code> (and is a no-op) if called while playback is already 147 * stopped. If a callback is in progress, StopPlayback() will block until the 148 * callback completes. 149 */ 150 PP_Bool StopPlayback( 151 [in] PP_Resource audio); 152}; 153 154