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 PPB_AudioConfig interface for establishing an
8 * audio configuration resource within the browser.
9 */
10
11label Chrome {
12  M14 = 1.0,
13  M19 = 1.1
14};
15
16/**
17 * This enumeration contains audio frame count constants.
18 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> is the minimum possible frame
19 * count. <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> is the maximum possible
20 * frame count.
21 */
22[unnamed] enum PP_AudioFrameSize {
23  PP_AUDIOMINSAMPLEFRAMECOUNT = 64,
24  PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768
25};
26
27
28/**
29 * PP_AudioSampleRate is an enumeration of the different audio sampling rates.
30 * <code>PP_AUDIOSAMPLERATE_44100</code> is the sample rate used on CDs and
31 * <code>PP_AUDIOSAMPLERATE_48000</code> is the sample rate used on DVDs and
32 * Digital Audio Tapes.
33 */
34[assert_size(4)]
35enum PP_AudioSampleRate {
36  PP_AUDIOSAMPLERATE_NONE = 0,
37  PP_AUDIOSAMPLERATE_44100 = 44100,
38  PP_AUDIOSAMPLERATE_48000 = 48000
39} ;
40
41
42/**
43 * The <code>PPB_AudioConfig</code> interface contains pointers to several
44 * functions for establishing your audio configuration within the browser.
45 * This interface only supports 16-bit stereo output.
46 *
47 * Refer to the
48 * <a href="/native-client/{{pepperversion}}/devguide/coding/audio">Audio
49 * </a> chapter in the Developer's Guide for information on using this
50 * interface.
51 */
52[macro="PPB_AUDIO_CONFIG_INTERFACE"]
53interface PPB_AudioConfig {
54  /**
55   * CreateStereo16bit() creates a 16 bit audio configuration resource. The
56   * <code>sample_rate</code> should be the result of calling
57   * <code>RecommendSampleRate</code> and <code>sample_frame_count</code> should
58   * be the result of calling <code>RecommendSampleFrameCount</code>. If the
59   * sample frame count or bit rate isn't supported, this function will fail and
60   * return a null resource.
61   *
62   * A single sample frame on a stereo device means one value for the left
63   * channel and one value for the right channel.
64   *
65   * Buffer layout for a stereo int16 configuration:
66   * <code>int16_t *buffer16;</code>
67   * <code>buffer16[0]</code> is the first left channel sample.
68   * <code>buffer16[1]</code> is the first right channel sample.
69   * <code>buffer16[2]</code> is the second left channel sample.
70   * <code>buffer16[3]</code> is the second right channel sample.
71   * ...
72   * <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left
73   * channel sample.
74   * <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last
75   * right channel sample.
76   * Data will always be in the native endian format of the platform.
77   *
78   * @param[in] instance A <code>PP_Instance</code> identifying one instance
79   * of a module.
80   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
81   * <code>PP_AUDIOSAMPLERATE_44100</code> or
82   * <code>PP_AUDIOSAMPLERATE_48000</code>.
83   * @param[in] sample_frame_count A <code>uint32_t</code> frame count returned
84   * from the <code>RecommendSampleFrameCount</code> function.
85   *
86   * @return A <code>PP_Resource</code> containing the
87   * <code>PPB_Audio_Config</code> if successful or a null resource if the
88   * sample frame count or bit rate are not supported.
89   */
90  PP_Resource CreateStereo16Bit(
91      [in] PP_Instance instance,
92      [in] PP_AudioSampleRate sample_rate,
93      [in] uint32_t sample_frame_count);
94
95  /**
96   * This comment block applies to version 1.0, which is deprecated in favor of
97   * the same function but with slightly different signature and behavior.
98   *
99   * RecommendSampleFrameCount() returns the supported sample frame count
100   * closest to the requested count. The sample frame count determines the
101   * overall latency of audio. Since one "frame" is always buffered in advance,
102   * smaller frame counts will yield lower latency, but higher CPU utilization.
103   * For best audio performance, use the value returned by RecommendSampleRate
104   * as the input sample rate, then use the RecommendSampleFrameCount return
105   * value when creating the audio configuration resource.
106   *
107   * Sample counts less than
108   * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
109   * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
110   * system, but values in between aren't necessarily glitch-free.
111   *
112   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
113   * <code>PP_AUDIOSAMPLERATE_44100</code> or
114   * <code>PP_AUDIOSAMPLERATE_48000.</code>
115   * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
116   * frame count.
117   *
118   * @return A <code>uint32_t</code> containing the recommended sample frame
119   * count if successful.
120   */
121  [deprecate=1.1]
122  uint32_t RecommendSampleFrameCount(
123      [in] PP_AudioSampleRate sample_rate,
124      [in] uint32_t requested_sample_frame_count);
125
126  /**
127   * RecommendSampleFrameCount() returns the supported sample frame count
128   * closest to the requested count. The sample frame count determines the
129   * overall latency of audio. Since one "frame" is always buffered in advance,
130   * smaller frame counts will yield lower latency, but higher CPU utilization.
131   *
132   * Supported sample frame counts will vary by hardware and system (consider
133   * that the local system might be anywhere from a cell phone or a high-end
134   * audio workstation). Sample counts less than
135   * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
136   * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
137   * system, but values in between aren't necessarily valid. This function
138   * will return a supported count closest to the requested frame count.
139   *
140   * RecommendSampleFrameCount() result is intended for audio output devices.
141   *
142   * @param[in] instance
143   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
144   * <code>PP_AUDIOSAMPLERATE_44100</code> or
145   * <code>PP_AUDIOSAMPLERATE_48000.</code>
146   * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
147   * frame count.
148   *
149   * @return A <code>uint32_t</code> containing the recommended sample frame
150   * count if successful.
151   */
152  [version=1.1]
153  uint32_t RecommendSampleFrameCount(
154      [in] PP_Instance instance,
155      [in] PP_AudioSampleRate sample_rate,
156      [in] uint32_t requested_sample_frame_count);
157
158  /**
159   * IsAudioConfig() determines if the given resource is a
160   * <code>PPB_Audio_Config</code>.
161   *
162   * @param[in] resource A <code>PP_Resource</code> corresponding to an audio
163   * config resource.
164   *
165   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
166   * resource is an <code>AudioConfig</code> resource, otherwise
167   * <code>PP_FALSE</code>.
168   */
169  PP_Bool IsAudioConfig(
170      [in] PP_Resource resource);
171
172  /**
173   * GetSampleRate() returns the sample rate for the given
174   * <code>PPB_Audio_Config</code>.
175   *
176   * @param[in] config A <code>PP_Resource</code> corresponding to a
177   * <code>PPB_Audio_Config</code>.
178   *
179   * @return A <code>PP_AudioSampleRate</code> containing sample rate or
180   * <code>PP_AUDIOSAMPLERATE_NONE</code> if the resource is invalid.
181   */
182  PP_AudioSampleRate GetSampleRate(
183      [in] PP_Resource config);
184
185  /**
186   * GetSampleFrameCount() returns the sample frame count for the given
187   * <code>PPB_Audio_Config</code>.
188   *
189   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
190   * config resource.
191   *
192   * @return A <code>uint32_t</code> containing sample frame count or
193   * 0 if the resource is invalid. Refer to
194   * RecommendSampleFrameCount() for more on sample frame counts.
195   */
196  uint32_t GetSampleFrameCount(
197      [in] PP_Resource config);
198
199  /**
200   * RecommendSampleRate() returns the native sample rate that the browser
201   * is using in the backend.  Applications that use the recommended sample
202   * rate will have potentially better latency and fidelity.  The return value
203   * is intended for audio output devices.  If the output sample rate cannot be
204   * determined, this function can return PP_AUDIOSAMPLERATE_NONE.
205   *
206   * @param[in] instance
207   *
208   * @return A <code>uint32_t</code> containing the recommended sample frame
209   * count if successful.
210   */
211  [version=1.1]
212  PP_AudioSampleRate RecommendSampleRate(
213      [in] PP_Instance instance);
214
215};
216
217