ppb_audio_encoder.h

Go to the documentation of this file.

/* 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.
 */

/* From ppb_audio_encoder.idl modified Mon Sep  7 10:17:53 2015. */

#ifndef PPAPI_C_PPB_AUDIO_ENCODER_H_
#define PPAPI_C_PPB_AUDIO_ENCODER_H_

#include "ppapi/c/pp_array_output.h"
#include "ppapi/c/pp_bool.h"
#include "ppapi/c/pp_codecs.h"
#include "ppapi/c/pp_completion_callback.h"
#include "ppapi/c/pp_instance.h"
#include "ppapi/c/pp_macros.h"
#include "ppapi/c/pp_resource.h"
#include "ppapi/c/pp_stdint.h"
#include "ppapi/c/ppb_audio_buffer.h"

#define PPB_AUDIOENCODER_INTERFACE_0_1 "PPB_AudioEncoder;0.1" /* dev */
/**
 * @file
 * This file defines the <code>PPB_AudioEncoder</code> interface.
 */


/**
 * @addtogroup Interfaces
 * @{
 */
/**
 * Audio encoder interface.
 *
 * Typical usage:
 * - Call Create() to create a new audio encoder resource.
 * - Call GetSupportedProfiles() to determine which codecs and profiles are
 *   available.
 * - Call Initialize() to initialize the encoder for a supported profile.
 * - Call GetBuffer() to get an empty buffer and fill it in, or get an audio
 *   buffer 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 buffer.
 * - 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.
 */
struct PPB_AudioEncoder_0_1 { /* dev */
  /**
   * 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)(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)(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)(PP_Resource audio_encoder,
                                  struct PP_ArrayOutput output,
                                  struct 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)(PP_Resource audio_encoder,
                        uint32_t channels,
                        PP_AudioBuffer_SampleRate input_sample_rate,
                        PP_AudioBuffer_SampleSize input_sample_size,
                        PP_AudioProfile output_profile,
                        uint32_t initial_bitrate,
                        PP_HardwareAcceleration acceleration,
                        struct 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().
   *
   * @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)(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.
   *
   * @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)(PP_Resource audio_encoder,
                       PP_Resource* audio_buffer,
                       struct 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)(PP_Resource audio_encoder,
                    PP_Resource audio_buffer,
                    struct 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)(
      PP_Resource audio_encoder,
      struct PP_AudioBitstreamBuffer* bitstream_buffer,
      struct 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)(
      PP_Resource audio_encoder,
      const struct 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)(PP_Resource audio_encoder, 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)(PP_Resource audio_encoder);
};
/**
 * @}
 */

#endif  /* PPAPI_C_PPB_AUDIO_ENCODER_H_ */