media/base/android/media_codec_bridge.h

   1 // Copyright (c) 2013 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 MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_
   6 #define MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_
   7
   8 #include <jni.h>
   9 #include <set>
  10 #include <string>
  11
  12 #include "base/android/scoped_java_ref.h"
  13 #include "base/time/time.h"
  14 #include "media/base/audio_decoder_config.h"
  15 #include "media/base/video_decoder_config.h"
  16 #include "ui/gfx/geometry/size.h"
  17
  18 namespace media {
  19
  20 struct SubsampleEntry;
  21
  22 // These must be in sync with MediaCodecBridge.MEDIA_CODEC_XXX constants in
  23 // MediaCodecBridge.java.
  24 enum MediaCodecStatus {
  25   MEDIA_CODEC_OK,
  26   MEDIA_CODEC_DEQUEUE_INPUT_AGAIN_LATER,
  27   MEDIA_CODEC_DEQUEUE_OUTPUT_AGAIN_LATER,
  28   MEDIA_CODEC_OUTPUT_BUFFERS_CHANGED,
  29   MEDIA_CODEC_OUTPUT_FORMAT_CHANGED,
  30   MEDIA_CODEC_INPUT_END_OF_STREAM,
  31   MEDIA_CODEC_OUTPUT_END_OF_STREAM,
  32   MEDIA_CODEC_NO_KEY,
  33   MEDIA_CODEC_ABORT,
  34   MEDIA_CODEC_ERROR
  35 };
  36
  37 // Codec direction.  Keep this in sync with MediaCodecBridge.java.
  38 enum MediaCodecDirection {
  39   MEDIA_CODEC_DECODER,
  40   MEDIA_CODEC_ENCODER,
  41 };
  42
  43 // This class serves as a bridge for native code to call java functions inside
  44 // Android MediaCodec class. For more information on Android MediaCodec, check
  45 // http://developer.android.com/reference/android/media/MediaCodec.html
  46 // Note: MediaCodec is only available on JB and greater.
  47 // Use AudioCodecBridge or VideoCodecBridge to create an instance of this
  48 // object.
  49 //
  50 // TODO(fischman,xhwang): replace this (and the enums that go with it) with
  51 // chromium's JNI auto-generation hotness.
  52 class MEDIA_EXPORT MediaCodecBridge {
  53  public:
  54   // Returns true if MediaCodec is available on the device.
  55   // All other static methods check IsAvailable() internally. There's no need
  56   // to check IsAvailable() explicitly before calling them.
  57   static bool IsAvailable();
  58
  59   // Returns true if MediaCodec.setParameters() is available on the device.
  60   static bool SupportsSetParameters();
  61
  62   // Returns true if MediaCodec.getName() is available on the device.
  63   static bool SupportsGetName();
  64
  65   // Returns whether MediaCodecBridge has a decoder that |is_secure| and can
  66   // decode |codec| type.
  67   static bool CanDecode(const std::string& codec, bool is_secure);
  68
  69   // Represents supported codecs on android.
  70   // TODO(qinmin): Currently the codecs string only contains one codec. Do we
  71   // need to support codecs separated by comma. (e.g. "vp8" -> "vp8, vp8.0")?
  72   struct CodecsInfo {
  73     std::string codecs;  // E.g. "vp8" or "avc1".
  74     std::string name;    // E.g. "OMX.google.vp8.decoder".
  75     MediaCodecDirection direction;
  76   };
  77
  78   // Get a list of supported codecs.
  79   static std::vector<CodecsInfo> GetCodecsInfo();
  80
  81   // Get default codec name for |mime_type|.
  82   static std::string GetDefaultCodecName(const std::string& mime_type,
  83                                          MediaCodecDirection direction);
  84
  85   // Get a list of encoder supported color formats for |mime_type|.
  86   // The mapping of color format name and its value refers to
  87   // MediaCodecInfo.CodecCapabilities.
  88   static std::set<int> GetEncoderColorFormats(const std::string& mime_type);
  89
  90   virtual ~MediaCodecBridge();
  91
  92   // Resets both input and output, all indices previously returned in calls to
  93   // DequeueInputBuffer() and DequeueOutputBuffer() become invalid.
  94   // Please note that this clears all the inputs in the media codec. In other
  95   // words, there will be no outputs until new input is provided.
  96   // Returns MEDIA_CODEC_ERROR if an unexpected error happens, or Media_CODEC_OK
  97   // otherwise.
  98   MediaCodecStatus Reset();
  99
 100   // Finishes the decode/encode session. The instance remains active
 101   // and ready to be StartAudio/Video()ed again. HOWEVER, due to the buggy
 102   // vendor's implementation , b/8125974, Stop() -> StartAudio/Video() may not
 103   // work on some devices. For reliability, Stop() -> delete and recreate new
 104   // instance -> StartAudio/Video() is recommended.
 105   void Stop();
 106
 107   // Used for getting output format. This is valid after DequeueInputBuffer()
 108   // returns a format change by returning INFO_OUTPUT_FORMAT_CHANGED
 109   void GetOutputFormat(int* width, int* height);
 110
 111   // Used for checking for new sampling rate after DequeueInputBuffer() returns
 112   // INFO_OUTPUT_FORMAT_CHANGED
 113   int GetOutputSamplingRate();
 114
 115   // Submits a byte array to the given input buffer. Call this after getting an
 116   // available buffer from DequeueInputBuffer().  If |data| is NULL, assume the
 117   // input buffer has already been populated (but still obey |size|).
 118   // |data_size| must be less than kint32max (because Java).
 119   MediaCodecStatus QueueInputBuffer(int index,
 120                                     const uint8* data,
 121                                     size_t data_size,
 122                                     const base::TimeDelta& presentation_time);
 123
 124   // Similar to the above call, but submits a buffer that is encrypted.  Note:
 125   // NULL |subsamples| indicates the whole buffer is encrypted.  If |data| is
 126   // NULL, assume the input buffer has already been populated (but still obey
 127   // |data_size|).  |data_size| must be less than kint32max (because Java).
 128   MediaCodecStatus QueueSecureInputBuffer(
 129       int index,
 130       const uint8* data,
 131       size_t data_size,
 132       const uint8* key_id,
 133       int key_id_size,
 134       const uint8* iv,
 135       int iv_size,
 136       const SubsampleEntry* subsamples,
 137       int subsamples_size,
 138       const base::TimeDelta& presentation_time);
 139
 140   // Submits an empty buffer with a EOS (END OF STREAM) flag.
 141   void QueueEOS(int input_buffer_index);
 142
 143   // Returns:
 144   // MEDIA_CODEC_OK if an input buffer is ready to be filled with valid data,
 145   // MEDIA_CODEC_ENQUEUE_INPUT_AGAIN_LATER if no such buffer is available, or
 146   // MEDIA_CODEC_ERROR if unexpected error happens.
 147   // Note: Never use infinite timeout as this would block the decoder thread and
 148   // prevent the decoder job from being released.
 149   MediaCodecStatus DequeueInputBuffer(const base::TimeDelta& timeout,
 150                                       int* index);
 151
 152   // Dequeues an output buffer, block at most timeout_us microseconds.
 153   // Returns the status of this operation. If OK is returned, the output
 154   // parameters should be populated. Otherwise, the values of output parameters
 155   // should not be used.  Output parameters other than index/offset/size are
 156   // optional and only set if not NULL.
 157   // Note: Never use infinite timeout as this would block the decoder thread and
 158   // prevent the decoder job from being released.
 159   // TODO(xhwang): Can we drop |end_of_stream| and return
 160   // MEDIA_CODEC_OUTPUT_END_OF_STREAM?
 161   MediaCodecStatus DequeueOutputBuffer(const base::TimeDelta& timeout,
 162                                        int* index,
 163                                        size_t* offset,
 164                                        size_t* size,
 165                                        base::TimeDelta* presentation_time,
 166                                        bool* end_of_stream,
 167                                        bool* key_frame);
 168
 169   // Returns the buffer to the codec. If you previously specified a surface when
 170   // configuring this video decoder you can optionally render the buffer.
 171   void ReleaseOutputBuffer(int index, bool render);
 172
 173   // Returns the number of output buffers used by the codec.
 174   // TODO(qinmin): this call is deprecated in Lollipop.
 175   int GetOutputBuffersCount();
 176
 177   // Returns the capacity of each output buffer used by the codec.
 178   // TODO(qinmin): this call is deprecated in Lollipop.
 179   size_t GetOutputBuffersCapacity();
 180
 181   // Returns an input buffer's base pointer and capacity.
 182   void GetInputBuffer(int input_buffer_index, uint8** data, size_t* capacity);
 183
 184   // Copy |dst_size| bytes from output buffer |index|'s |offset| onwards into
 185   // |*dst|.
 186   bool CopyFromOutputBuffer(int index, size_t offset, void* dst, int dst_size);
 187
 188   static bool RegisterMediaCodecBridge(JNIEnv* env);
 189
 190  protected:
 191   // Returns true if |mime_type| is known to be unaccelerated (i.e. backed by a
 192   // software codec instead of a hardware one).
 193   static bool IsKnownUnaccelerated(const std::string& mime_type,
 194                                    MediaCodecDirection direction);
 195
 196   MediaCodecBridge(const std::string& mime,
 197                    bool is_secure,
 198                    MediaCodecDirection direction);
 199
 200   // Calls start() against the media codec instance. Used in StartXXX() after
 201   // configuring media codec. Returns whether media codec was successfully
 202   // started.
 203   bool StartInternal() WARN_UNUSED_RESULT;
 204
 205   jobject media_codec() { return j_media_codec_.obj(); }
 206   MediaCodecDirection direction_;
 207
 208  private:
 209   // Fills a particular input buffer; returns false if |data_size| exceeds the
 210   // input buffer's capacity (and doesn't touch the input buffer in that case).
 211   bool FillInputBuffer(int index,
 212                        const uint8* data,
 213                        size_t data_size) WARN_UNUSED_RESULT;
 214
 215   // Java MediaCodec instance.
 216   base::android::ScopedJavaGlobalRef<jobject> j_media_codec_;
 217
 218   DISALLOW_COPY_AND_ASSIGN(MediaCodecBridge);
 219 };
 220
 221 class AudioCodecBridge : public MediaCodecBridge {
 222  public:
 223   // Returns an AudioCodecBridge instance if |codec| is supported, or a NULL
 224   // pointer otherwise.
 225   static AudioCodecBridge* Create(const AudioCodec& codec);
 226
 227   // See MediaCodecBridge::IsKnownUnaccelerated().
 228   static bool IsKnownUnaccelerated(const AudioCodec& codec);
 229
 230   // Start the audio codec bridge.
 231   bool Start(const AudioCodec& codec, int sample_rate, int channel_count,
 232              const uint8* extra_data, size_t extra_data_size,
 233              int64 codec_delay_ns, int64 seek_preroll_ns,
 234              bool play_audio, jobject media_crypto) WARN_UNUSED_RESULT;
 235
 236   // Play the output buffer. This call must be called after
 237   // DequeueOutputBuffer() and before ReleaseOutputBuffer. Returns the playback
 238   // head position expressed in frames.
 239   int64 PlayOutputBuffer(int index, size_t size);
 240
 241   // Set the volume of the audio output.
 242   void SetVolume(double volume);
 243
 244  private:
 245   explicit AudioCodecBridge(const std::string& mime);
 246
 247   // Configure the java MediaFormat object with the extra codec data passed in.
 248   bool ConfigureMediaFormat(jobject j_format, const AudioCodec& codec,
 249                             const uint8* extra_data, size_t extra_data_size,
 250                             int64 codec_delay_ns, int64 seek_preroll_ns);
 251 };
 252
 253 class MEDIA_EXPORT VideoCodecBridge : public MediaCodecBridge {
 254  public:
 255   // See MediaCodecBridge::IsKnownUnaccelerated().
 256   static bool IsKnownUnaccelerated(const VideoCodec& codec,
 257                                    MediaCodecDirection direction);
 258
 259   // Create, start, and return a VideoCodecBridge decoder or NULL on failure.
 260   static VideoCodecBridge* CreateDecoder(
 261       const VideoCodec& codec,  // e.g. media::kCodecVP8
 262       bool is_secure,
 263       const gfx::Size& size,  // Output frame size.
 264       jobject surface,        // Output surface, optional.
 265       jobject media_crypto);  // MediaCrypto object, optional.
 266
 267   // Create, start, and return a VideoCodecBridge encoder or NULL on failure.
 268   static VideoCodecBridge* CreateEncoder(
 269       const VideoCodec& codec,  // e.g. media::kCodecVP8
 270       const gfx::Size& size,    // input frame size
 271       int bit_rate,             // bits/second
 272       int frame_rate,           // frames/second
 273       int i_frame_interval,     // count
 274       int color_format);        // MediaCodecInfo.CodecCapabilities.
 275
 276   void SetVideoBitrate(int bps);
 277   void RequestKeyFrameSoon();
 278
 279   // Returns whether adaptive playback is supported for this object given
 280   // the new size.
 281   bool IsAdaptivePlaybackSupported(int width, int height);
 282
 283   // Test-only method to set the return value of IsAdaptivePlaybackSupported().
 284   // Without this function, the return value of that function will be device
 285   // dependent. If |adaptive_playback_supported| is equal to 0, the return value
 286   // will be false. If |adaptive_playback_supported| is larger than 0, the
 287   // return value will be true.
 288   void set_adaptive_playback_supported_for_testing(
 289       int adaptive_playback_supported) {
 290     adaptive_playback_supported_for_testing_ = adaptive_playback_supported;
 291   }
 292
 293  private:
 294   VideoCodecBridge(const std::string& mime,
 295                    bool is_secure,
 296                    MediaCodecDirection direction);
 297
 298   int adaptive_playback_supported_for_testing_;
 299 };
 300
 301 }  // namespace media
 302
 303 #endif  // MEDIA_BASE_ANDROID_MEDIA_CODEC_BRIDGE_H_