ppapi/api/ppb_audio_encoder.idl

   1 /* Copyright 2015 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_AudioEncoder</code> interface.
   8  */
   9
  10 [generate_thunk]
  11
  12 label Chrome {
  13   [channel=dev] M47 = 0.1
  14 };
  15
  16 /**
  17  * Audio encoder interface.
  18  *
  19  * Typical usage:
  20  * - Call Create() to create a new audio encoder resource.
  21  * - Call GetSupportedProfiles() to determine which codecs and profiles are
  22  *   available.
  23  * - Call Initialize() to initialize the encoder for a supported profile.
  24  * - Call GetBuffer() to get an empty buffer and fill it in, or get an audio
  25  *   buffer from another resource, e.g. <code>PPB_MediaStreamAudioTrack</code>.
  26  * - Call Encode() to push the audio buffer to the encoder. If an external
  27  *   buffer is pushed, wait for completion to recycle the buffer.
  28  * - Call GetBitstreamBuffer() continuously (waiting for each previous call to
  29  *   complete) to pull encoded buffers from the encoder.
  30  * - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
  31  *   buffer.
  32  * - To destroy the encoder, the plugin should release all of its references to
  33  *   it. Any pending callbacks will abort before the encoder is destroyed.
  34  *
  35  * Available audio codecs vary by platform.
  36  * All: opus.
  37  */
  38 interface PPB_AudioEncoder {
  39   /**
  40    * Creates a new audio encoder resource.
  41    *
  42    * @param[in] instance A <code>PP_Instance</code> identifying the instance
  43    * with the audio encoder.
  44    *
  45    * @return A <code>PP_Resource</code> corresponding to an audio encoder if
  46    * successful or 0 otherwise.
  47    */
  48   PP_Resource Create([in] PP_Instance instance);
  49
  50   /**
  51    * Determines if the given resource is an audio encoder.
  52    *
  53    * @param[in] resource A <code>PP_Resource</code> identifying a resource.
  54    *
  55    * @return <code>PP_TRUE</code> if the resource is a
  56    * <code>PPB_AudioEncoder</code>, <code>PP_FALSE</code> if the resource is
  57    * invalid or some other type.
  58    */
  59   PP_Bool IsAudioEncoder([in] PP_Resource resource);
  60
  61   /**
  62    * Gets an array of supported audio encoder profiles.
  63    * These can be used to choose a profile before calling Initialize().
  64    *
  65    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
  66    * encoder.
  67    * @param[in] output A <code>PP_ArrayOutput</code> to receive the supported
  68    * <code>PP_AudioProfileDescription</code> structs.
  69    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
  70    * completion.
  71    *
  72    * @return If >= 0, the number of supported profiles returned, otherwise an
  73    * error code from <code>pp_errors.h</code>.
  74    */
  75   int32_t GetSupportedProfiles([in] PP_Resource audio_encoder,
  76                                [in] PP_ArrayOutput output,
  77                                [in] PP_CompletionCallback callback);
  78
  79   /**
  80    * Initializes an audio encoder resource. The plugin should call Initialize()
  81    * successfully before calling any of the functions below.
  82    *
  83    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
  84    * encoder.
  85    * @param[in] channels The number of audio channels to encode.
  86    * @param[in] input_sampling_rate The sampling rate of the input audio buffer.
  87    * @param[in] input_sample_size The sample size of the input audio buffer.
  88    * @param[in] output_profile A <code>PP_AudioProfile</code> specifying the
  89    * codec profile of the encoded output stream.
  90    * @param[in] initial_bitrate The initial bitrate for the encoder.
  91    * @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
  92    * whether to use a hardware accelerated or a software implementation.
  93    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
  94    * completion.
  95    *
  96    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
  97    * Returns PP_ERROR_NOTSUPPORTED if audio encoding is not available, or the
  98    * requested codec profile is not supported.
  99    */
 100   int32_t Initialize([in] PP_Resource audio_encoder,
 101                      [in] uint32_t channels,
 102                      [in] PP_AudioBuffer_SampleRate input_sample_rate,
 103                      [in] PP_AudioBuffer_SampleSize input_sample_size,
 104                      [in] PP_AudioProfile output_profile,
 105                      [in] uint32_t initial_bitrate,
 106                      [in] PP_HardwareAcceleration acceleration,
 107                      [in] PP_CompletionCallback callback);
 108
 109   /**
 110    * Gets the number of audio samples per channel that audio buffers must
 111    * contain in order to be processed by the encoder. This will be the number of
 112    * samples per channels contained in buffers returned by GetBuffer().
 113    *
 114    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 115    * encoder.
 116    * @return An int32_t containing the number of samples required, or an error
 117    * code from <code>pp_errors.h</code>.
 118    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 119    */
 120   int32_t GetNumberOfSamples([in] PP_Resource audio_encoder);
 121
 122   /**
 123    * Gets a blank audio buffer (with metadata given by the Initialize()
 124    * call) which can be filled with audio data and passed to the encoder.
 125    *
 126    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 127    * encoder.
 128    * @param[out] audio_buffer A blank <code>PPB_AudioBuffer</code> resource.
 129    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 130    * completion.
 131    *
 132    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 133    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 134    */
 135   int32_t GetBuffer([in] PP_Resource audio_encoder,
 136                     [out] PP_Resource audio_buffer,
 137                     [in] PP_CompletionCallback callback);
 138
 139   /**
 140    * Encodes an audio buffer.
 141    *
 142    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 143    * encoder.
 144    * @param[in] audio_buffer The <code>PPB_AudioBuffer</code> to be encoded.
 145    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 146    * completion. Plugins that pass <code>PPB_AudioBuffer</code> resources owned
 147    * by other resources should wait for completion before reusing them.
 148    *
 149    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 150    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 151    */
 152   int32_t Encode([in] PP_Resource audio_encoder,
 153                  [in] PP_Resource audio_buffer,
 154                  [in] PP_CompletionCallback callback);
 155
 156   /**
 157    * Gets the next encoded bitstream buffer from the encoder.
 158    *
 159    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 160    * encoder.
 161    * @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
 162    * encoded audio data.
 163    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 164    * completion. The plugin can call GetBitstreamBuffer from the callback in
 165    * order to continuously "pull" bitstream buffers from the encoder.
 166    *
 167    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
 168    * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 169    * Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
 170    * not completed.
 171    */
 172   int32_t GetBitstreamBuffer([in] PP_Resource audio_encoder,
 173                              [out] PP_AudioBitstreamBuffer bitstream_buffer,
 174                              [in] PP_CompletionCallback callback);
 175
 176   /**
 177    * Recycles a bitstream buffer back to the encoder.
 178    *
 179    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 180    * encoder.
 181    * @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
 182    * longer needed by the plugin.
 183    */
 184   void RecycleBitstreamBuffer([in] PP_Resource audio_encoder,
 185                               [in] PP_AudioBitstreamBuffer bitstream_buffer);
 186
 187   /**
 188    * Requests a change to the encoding bitrate. This is only a request,
 189    * fulfilled on a best-effort basis.
 190    *
 191    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 192    * encoder.
 193    * @param[in] bitrate The requested new bitrate, in bits per second.
 194    */
 195   void RequestBitrateChange([in] PP_Resource audio_encoder,
 196                             [in] uint32_t bitrate);
 197
 198   /**
 199    * Closes the audio encoder, and cancels any pending encodes. Any pending
 200    * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
 201    * not valid to call any encoder functions after a call to this method.
 202    * <strong>Note:</strong> Destroying the audio encoder closes it implicitly,
 203    * so you are not required to call Close().
 204    *
 205    * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 206    * encoder.
 207    */
 208   void Close([in] PP_Resource audio_encoder);
 209 };