summaryrefslogtreecommitdiffstats
path: root/ppapi/api/ppb_audio_config.idl
blob: fd4cef4fe05a29be87838179a869583816d65f44 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

/**
 * This file defines the PPB_AudioConfig interface for establishing an
 * audio configuration resource within the browser.
 */

label Chrome {
  M14 = 1.0,
  M19 = 1.1
};

/**
 * This enumeration contains audio frame count constants.
 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> is the minimum possible frame
 * count. <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> is the maximum possible
 * frame count.
 */
[unnamed] enum PP_AudioFrameSize {
  PP_AUDIOMINSAMPLEFRAMECOUNT = 64,
  PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768
};


/**
 * PP_AudioSampleRate is an enumeration of the different audio sampling rates.
 * <code>PP_AUDIOSAMPLERATE_44100</code> is the sample rate used on CDs and
 * <code>PP_AUDIOSAMPLERATE_48000</code> is the sample rate used on DVDs and
 * Digital Audio Tapes.
 */
[assert_size(4)]
enum PP_AudioSampleRate {
  PP_AUDIOSAMPLERATE_NONE = 0,
  PP_AUDIOSAMPLERATE_44100 = 44100,
  PP_AUDIOSAMPLERATE_48000 = 48000
} ;


/**
 * The <code>PPB_AudioConfig</code> interface contains pointers to several
 * functions for establishing your audio configuration within the browser.
 * This interface only supports 16-bit stereo output.
 *
 * Refer to the
 * <a href="/native-client/devguide/coding/audio.html">Audio
 * </a> chapter in the Developer's Guide for information on using this
 * interface.
 */
[macro="PPB_AUDIO_CONFIG_INTERFACE"]
interface PPB_AudioConfig {
  /**
   * CreateStereo16bit() creates a 16 bit audio configuration resource. The
   * <code>sample_rate</code> should be the result of calling
   * <code>RecommendSampleRate</code> and <code>sample_frame_count</code> should
   * be the result of calling <code>RecommendSampleFrameCount</code>. If the
   * sample frame count or bit rate isn't supported, this function will fail and
   * return a null resource.
   *
   * A single sample frame on a stereo device means one value for the left
   * channel and one value for the right channel.
   *
   * Buffer layout for a stereo int16 configuration:
   * <code>int16_t *buffer16;</code>
   * <code>buffer16[0]</code> is the first left channel sample.
   * <code>buffer16[1]</code> is the first right channel sample.
   * <code>buffer16[2]</code> is the second left channel sample.
   * <code>buffer16[3]</code> is the second right channel sample.
   * ...
   * <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left
   * channel sample.
   * <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last
   * right channel sample.
   * Data will always be in the native endian format of the platform.
   *
   * @param[in] instance A <code>PP_Instance</code> identifying one instance
   * of a module.
   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
   * <code>PP_AUDIOSAMPLERATE_44100</code> or
   * <code>PP_AUDIOSAMPLERATE_48000</code>.
   * @param[in] sample_frame_count A <code>uint32_t</code> frame count returned
   * from the <code>RecommendSampleFrameCount</code> function.
   *
   * @return A <code>PP_Resource</code> containing the
   * <code>PPB_Audio_Config</code> if successful or a null resource if the
   * sample frame count or bit rate are not supported.
   */
  PP_Resource CreateStereo16Bit(
      [in] PP_Instance instance,
      [in] PP_AudioSampleRate sample_rate,
      [in] uint32_t sample_frame_count);

  /**
   * This comment block applies to version 1.0, which is deprecated in favor of
   * the same function but with slightly different signature and behavior.
   *
   * RecommendSampleFrameCount() returns the supported sample frame count
   * closest to the requested count. The sample frame count determines the
   * overall latency of audio. Since one "frame" is always buffered in advance,
   * smaller frame counts will yield lower latency, but higher CPU utilization.
   * For best audio performance, use the value returned by RecommendSampleRate
   * as the input sample rate, then use the RecommendSampleFrameCount return
   * value when creating the audio configuration resource.
   *
   * Sample counts less than
   * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
   * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
   * system, but values in between aren't necessarily glitch-free.
   *
   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
   * <code>PP_AUDIOSAMPLERATE_44100</code> or
   * <code>PP_AUDIOSAMPLERATE_48000.</code>
   * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
   * frame count.
   *
   * @return A <code>uint32_t</code> containing the recommended sample frame
   * count if successful.
   */
  [deprecate=1.1]
  uint32_t RecommendSampleFrameCount(
      [in] PP_AudioSampleRate sample_rate,
      [in] uint32_t requested_sample_frame_count);

  /**
   * RecommendSampleFrameCount() returns the supported sample frame count
   * closest to the requested count. The sample frame count determines the
   * overall latency of audio. Since one "frame" is always buffered in advance,
   * smaller frame counts will yield lower latency, but higher CPU utilization.
   *
   * Supported sample frame counts will vary by hardware and system (consider
   * that the local system might be anywhere from a cell phone or a high-end
   * audio workstation). Sample counts less than
   * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
   * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
   * system, but values in between aren't necessarily valid. This function
   * will return a supported count closest to the requested frame count.
   *
   * RecommendSampleFrameCount() result is intended for audio output devices.
   *
   * @param[in] instance
   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
   * <code>PP_AUDIOSAMPLERATE_44100</code> or
   * <code>PP_AUDIOSAMPLERATE_48000.</code>
   * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
   * frame count.
   *
   * @return A <code>uint32_t</code> containing the recommended sample frame
   * count if successful.
   */
  [version=1.1]
  uint32_t RecommendSampleFrameCount(
      [in] PP_Instance instance,
      [in] PP_AudioSampleRate sample_rate,
      [in] uint32_t requested_sample_frame_count);

  /**
   * IsAudioConfig() determines if the given resource is a
   * <code>PPB_Audio_Config</code>.
   *
   * @param[in] resource A <code>PP_Resource</code> corresponding to an audio
   * config resource.
   * 
   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
   * resource is an <code>AudioConfig</code> resource, otherwise
   * <code>PP_FALSE</code>.
   */
  PP_Bool IsAudioConfig(
      [in] PP_Resource resource);

  /**
   * GetSampleRate() returns the sample rate for the given
   * <code>PPB_Audio_Config</code>.
   *
   * @param[in] config A <code>PP_Resource</code> corresponding to a
   * <code>PPB_Audio_Config</code>.
   *
   * @return A <code>PP_AudioSampleRate</code> containing sample rate or
   * <code>PP_AUDIOSAMPLERATE_NONE</code> if the resource is invalid.
   */
  PP_AudioSampleRate GetSampleRate(
      [in] PP_Resource config);

  /**
   * GetSampleFrameCount() returns the sample frame count for the given
   * <code>PPB_Audio_Config</code>.
   *
   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
   * config resource.
   *
   * @return A <code>uint32_t</code> containing sample frame count or
   * 0 if the resource is invalid. Refer to
   * RecommendSampleFrameCount() for more on sample frame counts.
   */
  uint32_t GetSampleFrameCount(
      [in] PP_Resource config);

  /**
   * RecommendSampleRate() returns the native sample rate that the browser
   * is using in the backend.  Applications that use the recommended sample
   * rate will have potentially better latency and fidelity.  The return value
   * is intended for audio output devices.  If the output sample rate cannot be
   * determined, this function can return PP_AUDIOSAMPLERATE_NONE.
   *
   * @param[in] instance
   *
   * @return A <code>uint32_t</code> containing the recommended sample frame
   * count if successful.
   */
  [version=1.1]
  PP_AudioSampleRate RecommendSampleRate(
      [in] PP_Instance instance);

};