ppapi/cpp/audio_encoder.h

   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 #ifndef PPAPI_CPP_AUDIO_ENCODER_H_
   6 #define PPAPI_CPP_AUDIO_ENCODER_H_
   7
   8 #include "ppapi/c/pp_codecs.h"
   9 #include "ppapi/c/ppb_audio_buffer.h"
  10 #include "ppapi/cpp/audio_buffer.h"
  11 #include "ppapi/cpp/completion_callback.h"
  12 #include "ppapi/cpp/resource.h"
  13
  14 /// @file
  15 /// This file defines the API to create and use a AudioEncoder resource.
  16
  17 namespace pp {
  18
  19 class InstanceHandle;
  20
  21 /// Audio encoder interface.
  22 ///
  23 /// Typical usage:
  24 /// - Call Create() to create a new audio encoder resource.
  25 /// - Call GetSupportedFormats() to determine which codecs and profiles are
  26 ///   available.
  27 /// - Call Initialize() to initialize the encoder for a supported profile.
  28 /// - Call GetBuffer() to get a blank frame and fill it in, or get an audio
  29 ///   frame from another resource, e.g. <code>PPB_MediaStreamAudioTrack</code>.
  30 /// - Call Encode() to push the audio buffer to the encoder. If an external
  31 ///   buffer is pushed, wait for completion to recycle the frame.
  32 /// - Call GetBitstreamBuffer() continuously (waiting for each previous call to
  33 ///   complete) to pull encoded buffers from the encoder.
  34 /// - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
  35 ///   buffer.
  36 /// - To destroy the encoder, the plugin should release all of its references to
  37 ///   it. Any pending callbacks will abort before the encoder is destroyed.
  38 ///
  39 /// Available audio codecs vary by platform.
  40 /// All: opus.
  41 class AudioEncoder : public Resource {
  42  public:
  43   /// Default constructor for creating an is_null() <code>AudioEncoder</code>
  44   /// object.
  45   AudioEncoder();
  46
  47   /// A constructor used to create a <code>AudioEncoder</code> and associate it
  48   /// with the provided <code>Instance</code>.
  49   /// @param[in] instance The instance with which this resource will be
  50   /// associated.
  51   explicit AudioEncoder(const InstanceHandle& instance);
  52
  53   /// The copy constructor for <code>AudioEncoder</code>.
  54   /// @param[in] other A reference to a <code>AudioEncoder</code>.
  55   AudioEncoder(const AudioEncoder& other);
  56
  57   /// Gets an array of supported audio encoder profiles.
  58   /// These can be used to choose a profile before calling Initialize().
  59   ///
  60   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
  61   /// called upon completion with the PP_AudioProfileDescription structs.
  62   ///
  63   /// @return If >= 0, the number of supported profiles returned, otherwise an
  64   /// error code from <code>pp_errors.h</code>.
  65   int32_t GetSupportedProfiles(const CompletionCallbackWithOutput<
  66       std::vector<PP_AudioProfileDescription> >& cc);
  67
  68   /// Initializes a audio encoder resource. This should be called after
  69   /// GetSupportedProfiles() and before any functions below.
  70   ///
  71   /// @param[in] channels The number of audio channels to encode.
  72   /// @param[in] input_sampling_rate The sampling rate of the input audio
  73   /// buffer.
  74   /// @param[in] input_sample_size The sample size of the input audio buffer.
  75   /// @param[in] output_profile A <code>PP_AudioProfile</code> specifying the
  76   /// codec profile of the encoded output stream.
  77   /// @param[in] initial_bitrate The initial bitrate for the encoder.
  78   /// @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
  79   /// whether to use a hardware accelerated or a software implementation.
  80   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
  81   /// completion.
  82   ///
  83   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
  84   /// Returns PP_ERROR_NOTSUPPORTED if audio encoding is not available, or the
  85   /// requested codec profile is not supported.
  86   /// Returns PP_ERROR_NOMEMORY if bitstream buffers can't be created.
  87   int32_t Initialize(uint32_t channels,
  88                      PP_AudioBuffer_SampleRate input_sample_rate,
  89                      PP_AudioBuffer_SampleSize input_sample_size,
  90                      PP_AudioProfile output_profile,
  91                      uint32_t initial_bitrate,
  92                      PP_HardwareAcceleration acceleration,
  93                      const CompletionCallback& cc);
  94
  95   /// Gets the number of audio samples per channel that audio buffers
  96   /// must contain in order to be processed by the encoder. This will
  97   /// be the number of samples per channels contained in buffers
  98   /// returned by GetBuffer().
  99   ///
 100   /// @return An int32_t containing the number of samples required, or an error
 101   /// code from <code>pp_errors.h</code>.
 102   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 103   int32_t GetNumberOfSamples();
 104
 105   /// Gets a blank audio frame which can be filled with audio data and passed
 106   /// to the encoder.
 107   ///
 108   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 109   /// called upon completion with the blank <code>AudioBuffer</code> resource.
 110   ///
 111   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 112   int32_t GetBuffer(const CompletionCallbackWithOutput<AudioBuffer>& cc);
 113
 114   /// Encodes an audio buffer.
 115   ///
 116   /// @param[in] audio_buffer The <code>AudioBuffer</code> to be encoded.
 117   /// @param[in] callback A <code>CompletionCallback</code> to be called upon
 118   /// completion. Plugins that pass <code>AudioBuffer</code> resources owned
 119   /// by other resources should wait for completion before reusing them.
 120   ///
 121   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 122   /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
 123   int32_t Encode(const AudioBuffer& buffer, const CompletionCallback& cc);
 124
 125   /// Gets the next encoded bitstream buffer from the encoder.
 126   ///
 127   /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
 128   /// called upon completion with the next bitstream buffer. The plugin can call
 129   /// GetBitstreamBuffer from the callback in order to continuously "pull"
 130   /// bitstream buffers from the encoder.
 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   /// Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
 135   /// not completed.
 136   int32_t GetBitstreamBuffer(
 137       const CompletionCallbackWithOutput<PP_AudioBitstreamBuffer>& cc);
 138
 139   /// Recycles a bitstream buffer back to the encoder.
 140   ///
 141   /// @param[in] bitstream_buffer A<code>PP_AudioBitstreamBuffer</code> that
 142   /// is no longer needed by the plugin.
 143   void RecycleBitstreamBuffer(const PP_AudioBitstreamBuffer& bitstream_buffer);
 144
 145   /// Requests a change to the encoding bitrate. This is only a request,
 146   /// fulfilled on a best-effort basis.
 147   ///
 148   /// @param[in] audio_encoder A <code>PP_Resource</code> identifying the audio
 149   /// encoder.
 150   void RequestBitrateChange(uint32_t bitrate);
 151
 152   /// Closes the audio encoder, and cancels any pending encodes. Any pending
 153   /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
 154   /// not valid to call any encoder functions after a call to this method.
 155   /// <strong>Note:</strong> Destroying the audio encoder closes it implicitly,
 156   /// so you are not required to call Close().
 157   void Close();
 158 };
 159
 160 }  // namespace pp
 161
 162 #endif  // PPAPI_CPP_AUDIO_ENCODER_H_