ppapi: define PPB_AudioEncoder API

ppapi/api/ppb_audio_encoder.idl

+/* Copyright 2015 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 <code>PPB_AudioEncoder</code> interface.
+ */
+
+[generate_thunk]
+
+label Chrome {
+  [channel=dev] M44 = 0.1
+};
+
+/**
+ * Audio encoder interface.
+ *
+ * Typical usage:
+ * - Call Create() to create a new audio encoder resource.
+ * - Call GetSupportedFormats() to determine which codecs and profiles are

[bbudge, 2015/09/04 16:26:50]

GetSupportedProfiles

[llandwerlin-old, 2015/09/07 09:37:25]

Done.

+ *   available.
+ * - Call Initialize() to initialize the encoder for a supported profile.
+ * - Call GetBuffer() to get a blank frame and fill it in, or get an audio

[bbudge, 2015/09/04 16:26:50]

Frame is kind of confusing terminology here.
s/blank frame/empty buffer

and below.

[llandwerlin-old, 2015/09/07 09:37:25]

Done.

+ *   frame from another resource, e.g. <code>PPB_MediaStreamAudioTrack</code>.
+ * - Call Encode() to push the audio buffer to the encoder. If an external
+ *   buffer is pushed, wait for completion to recycle the frame.
+ * - Call GetBitstreamBuffer() continuously (waiting for each previous call to
+ *   complete) to pull encoded buffers from the encoder.
+ * - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
+ *   buffer.
+ * - To destroy the encoder, the plugin should release all of its references to
+ *   it. Any pending callbacks will abort before the encoder is destroyed.
+ *
+ * Available audio codecs vary by platform.
+ * All: opus.
+ */
+interface PPB_AudioEncoder {
+  /**
+   * Creates a new audio encoder resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying the instance
+   * with the audio encoder.
+   *
+   * @return A <code>PP_Resource</code> corresponding to an audio encoder if
+   * successful or 0 otherwise.
+   */
+  PP_Resource Create([in] PP_Instance instance);
+
+  /**
+   * Determines if the given resource is an audio encoder.
+   *
+   * @param[in] resource A <code>PP_Resource</code> identifying a resource.
+   *
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>PPB_AudioEncoder</code>, <code>PP_FALSE</code> if the resource is
+   * invalid or some other type.
+   */
+  PP_Bool IsAudioEncoder([in] PP_Resource resource);
+
+  /**
+   * Gets an array of supported audio encoder profiles.
+   * These can be used to choose a profile before calling Initialize().
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[in] output A <code>PP_ArrayOutput</code> to receive the supported
+   * <code>PP_AudioProfileDescription</code> structs.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return If >= 0, the number of supported profiles returned, otherwise an
+   * error code from <code>pp_errors.h</code>.
+   */
+  int32_t GetSupportedProfiles([in] PP_Resource audio_encoder,
+                               [in] PP_ArrayOutput output,
+                               [in] PP_CompletionCallback callback);
+
+  /**
+   * Initializes an audio encoder resource. The plugin should call Initialize()
+   * successfully before calling any of the functions below.
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[in] channels The number of audio channels to encode.
+   * @param[in] input_sampling_rate The sampling rate of the input audio buffer.
+   * @param[in] input_sample_size The sample size of the input audio buffer.
+   * @param[in] output_profile A <code>PP_AudioProfile</code> specifying the
+   * codec profile of the encoded output stream.
+   * @param[in] initial_bitrate The initial bitrate for the encoder.
+   * @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
+   * whether to use a hardware accelerated or a software implementation.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_NOTSUPPORTED if audio encoding is not available, or the
+   * requested codec profile is not supported.
+   */
+  int32_t Initialize([in] PP_Resource audio_encoder,
+                     [in] uint32_t channels,
+                     [in] PP_AudioBuffer_SampleRate input_sample_rate,
+                     [in] PP_AudioBuffer_SampleSize input_sample_size,
+                     [in] PP_AudioProfile output_profile,
+                     [in] uint32_t initial_bitrate,
+                     [in] PP_HardwareAcceleration acceleration,
+                     [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the number of audio samples per channel that audio buffers
+   * must contain in order to be processed by the encoder. This will
+   * be the number of samples per channels contained in buffers
+   * returned by GetBuffer().

[bbudge, 2015/09/04 16:26:50]

nit: formatting

[llandwerlin-old, 2015/09/07 09:37:25]

Done.

+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @return An int32_t containing the number of samples required, or an error
+   * code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t GetNumberOfSamples([in] PP_Resource audio_encoder);
+
+  /**
+   * Gets a blank audio buffer (with metadata given by the Initialize()
+   * call) which can be filled with audio data and passed to the
+   * encoder.

[bbudge, 2015/09/04 16:26:50]

nit: this could fit on previous line.

[llandwerlin-old, 2015/09/07 09:37:24]

Done.

+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[out] audio_buffer A blank <code>PPB_AudioBuffer</code> resource.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t GetBuffer([in] PP_Resource audio_encoder,
+                    [out] PP_Resource audio_buffer,
+                    [in] PP_CompletionCallback callback);
+
+  /**
+   * Encodes an audio buffer.
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[in] audio_buffer The <code>PPB_AudioBuffer</code> to be encoded.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion. Plugins that pass <code>PPB_AudioBuffer</code> resources owned
+   * by other resources should wait for completion before reusing them.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   */
+  int32_t Encode([in] PP_Resource audio_encoder,
+                 [in] PP_Resource audio_buffer,
+                 [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets the next encoded bitstream buffer from the encoder.
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
+   * encoded audio data.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion. The plugin can call GetBitstreamBuffer from the callback in
+   * order to continuously "pull" bitstream buffers from the encoder.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
+   * Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
+   * Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
+   * not completed.
+   */
+  int32_t GetBitstreamBuffer([in] PP_Resource audio_encoder,
+                             [out] PP_AudioBitstreamBuffer bitstream_buffer,
+                             [in] PP_CompletionCallback callback);
+
+  /**
+   * Recycles a bitstream buffer back to the encoder.
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
+   * longer needed by the plugin.
+   */
+  void RecycleBitstreamBuffer([in] PP_Resource audio_encoder,
+                              [in] PP_AudioBitstreamBuffer bitstream_buffer);
+
+  /**
+   * Requests a change to the encoding bitrate. This is only a request,
+   * fulfilled on a best-effort basis.
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   * @param[in] bitrate The requested new bitrate, in bits per second.
+   */
+  void RequestBitrateChange([in] PP_Resource audio_encoder,
+                            [in] uint32_t bitrate);
+
+  /**
+   * Closes the audio encoder, and cancels any pending encodes. Any pending
+   * callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
+   * not valid to call any encoder functions after a call to this method.
+   * <strong>Note:</strong> Destroying the audio encoder closes it implicitly,
+   * so you are not required to call Close().
+   *
+   * @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
+   * encoder.
+   */
+  void Close([in] PP_Resource audio_encoder);
+};