1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /* 18 * This file defines an NDK API. 19 * Do not remove methods. 20 * Do not change method signatures. 21 * Do not change the value of constants. 22 * Do not change the size of any of the classes defined in here. 23 * Do not reference types that are not part of the NDK. 24 * Do not #include files that aren't part of the NDK. 25 */ 26 27 #ifndef _NDK_MEDIA_CODEC_H 28 #define _NDK_MEDIA_CODEC_H 29 30 #include <stdint.h> 31 #include <sys/cdefs.h> 32 33 #include "NdkMediaCrypto.h" 34 #include "NdkMediaError.h" 35 #include "NdkMediaFormat.h" 36 37 __BEGIN_DECLS 38 39 struct ANativeWindow; 40 typedef struct ANativeWindow ANativeWindow; 41 42 43 struct AMediaCodec; 44 typedef struct AMediaCodec AMediaCodec; 45 46 struct AMediaCodecBufferInfo { 47 int32_t offset; 48 int32_t size; 49 int64_t presentationTimeUs; 50 uint32_t flags; 51 }; 52 typedef struct AMediaCodecBufferInfo AMediaCodecBufferInfo; 53 typedef struct AMediaCodecCryptoInfo AMediaCodecCryptoInfo; 54 55 enum { 56 AMEDIACODEC_BUFFER_FLAG_CODEC_CONFIG = 2, 57 AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM = 4, 58 AMEDIACODEC_BUFFER_FLAG_PARTIAL_FRAME = 8, 59 60 AMEDIACODEC_CONFIGURE_FLAG_ENCODE = 1, 61 AMEDIACODEC_INFO_OUTPUT_BUFFERS_CHANGED = -3, 62 AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED = -2, 63 AMEDIACODEC_INFO_TRY_AGAIN_LATER = -1, 64 }; 65 66 /** 67 * Called when an input buffer becomes available. 68 * The specified index is the index of the available input buffer. 69 */ 70 typedef void (*AMediaCodecOnAsyncInputAvailable)( 71 AMediaCodec *codec, 72 void *userdata, 73 int32_t index); 74 /** 75 * Called when an output buffer becomes available. 76 * The specified index is the index of the available output buffer. 77 * The specified bufferInfo contains information regarding the available output buffer. 78 */ 79 typedef void (*AMediaCodecOnAsyncOutputAvailable)( 80 AMediaCodec *codec, 81 void *userdata, 82 int32_t index, 83 AMediaCodecBufferInfo *bufferInfo); 84 /** 85 * Called when the output format has changed. 86 * The specified format contains the new output format. 87 */ 88 typedef void (*AMediaCodecOnAsyncFormatChanged)( 89 AMediaCodec *codec, 90 void *userdata, 91 AMediaFormat *format); 92 /** 93 * Called when the MediaCodec encountered an error. 94 * The specified actionCode indicates the possible actions that client can take, 95 * and it can be checked by calling AMediaCodecActionCode_isRecoverable or 96 * AMediaCodecActionCode_isTransient. If both AMediaCodecActionCode_isRecoverable() 97 * and AMediaCodecActionCode_isTransient() return false, then the codec error is fatal 98 * and the codec must be deleted. 99 * The specified detail may contain more detailed messages about this error. 100 */ 101 typedef void (*AMediaCodecOnAsyncError)( 102 AMediaCodec *codec, 103 void *userdata, 104 media_status_t error, 105 int32_t actionCode, 106 const char *detail); 107 108 struct AMediaCodecOnAsyncNotifyCallback { 109 AMediaCodecOnAsyncInputAvailable onAsyncInputAvailable; 110 AMediaCodecOnAsyncOutputAvailable onAsyncOutputAvailable; 111 AMediaCodecOnAsyncFormatChanged onAsyncFormatChanged; 112 AMediaCodecOnAsyncError onAsyncError; 113 }; 114 115 #if __ANDROID_API__ >= 21 116 117 /** 118 * Create codec by name. Use this if you know the exact codec you want to use. 119 * When configuring, you will need to specify whether to use the codec as an 120 * encoder or decoder. 121 */ 122 AMediaCodec* AMediaCodec_createCodecByName(const char *name); 123 124 /** 125 * Create codec by mime type. Most applications will use this, specifying a 126 * mime type obtained from media extractor. 127 */ 128 AMediaCodec* AMediaCodec_createDecoderByType(const char *mime_type); 129 130 /** 131 * Create encoder by name. 132 */ 133 AMediaCodec* AMediaCodec_createEncoderByType(const char *mime_type); 134 135 /** 136 * delete the codec and free its resources 137 */ 138 media_status_t AMediaCodec_delete(AMediaCodec*); 139 140 /** 141 * Configure the codec. For decoding you would typically get the format from an extractor. 142 */ 143 media_status_t AMediaCodec_configure( 144 AMediaCodec*, 145 const AMediaFormat* format, 146 ANativeWindow* surface, 147 AMediaCrypto *crypto, 148 uint32_t flags); 149 150 /** 151 * Start the codec. A codec must be configured before it can be started, and must be started 152 * before buffers can be sent to it. 153 */ 154 media_status_t AMediaCodec_start(AMediaCodec*); 155 156 /** 157 * Stop the codec. 158 */ 159 media_status_t AMediaCodec_stop(AMediaCodec*); 160 161 /* 162 * Flush the codec's input and output. All indices previously returned from calls to 163 * AMediaCodec_dequeueInputBuffer and AMediaCodec_dequeueOutputBuffer become invalid. 164 */ 165 media_status_t AMediaCodec_flush(AMediaCodec*); 166 167 /** 168 * Get an input buffer. The specified buffer index must have been previously obtained from 169 * dequeueInputBuffer, and not yet queued. 170 */ 171 uint8_t* AMediaCodec_getInputBuffer(AMediaCodec*, size_t idx, size_t *out_size); 172 173 /** 174 * Get an output buffer. The specified buffer index must have been previously obtained from 175 * dequeueOutputBuffer, and not yet queued. 176 */ 177 uint8_t* AMediaCodec_getOutputBuffer(AMediaCodec*, size_t idx, size_t *out_size); 178 179 /** 180 * Get the index of the next available input buffer. An app will typically use this with 181 * getInputBuffer() to get a pointer to the buffer, then copy the data to be encoded or decoded 182 * into the buffer before passing it to the codec. 183 */ 184 ssize_t AMediaCodec_dequeueInputBuffer(AMediaCodec*, int64_t timeoutUs); 185 186 /* 187 * __USE_FILE_OFFSET64 changes the type of off_t in LP32, which changes the ABI 188 * of these declarations to not match the platform. In that case, define these 189 * APIs in terms of int32_t instead. Passing an off_t in this situation will 190 * result in silent truncation unless the user builds with -Wconversion, but the 191 * only alternative it to not expose them at all for this configuration, which 192 * makes the whole API unusable. 193 * 194 * https://github.com/android-ndk/ndk/issues/459 195 */ 196 #if defined(__USE_FILE_OFFSET64) && !defined(__LP64__) 197 #define _off_t_compat int32_t 198 #else 199 #define _off_t_compat off_t 200 #endif /* defined(__USE_FILE_OFFSET64) && !defined(__LP64__) */ 201 202 #if (defined(__cplusplus) && __cplusplus >= 201103L) || \ 203 __STDC_VERSION__ >= 201112L 204 #include <assert.h> 205 static_assert(sizeof(_off_t_compat) == sizeof(long), 206 "_off_t_compat does not match the NDK ABI. See " 207 "https://github.com/android-ndk/ndk/issues/459."); 208 #endif 209 210 /** 211 * Send the specified buffer to the codec for processing. 212 */ 213 media_status_t AMediaCodec_queueInputBuffer(AMediaCodec*, size_t idx, 214 _off_t_compat offset, size_t size, 215 uint64_t time, uint32_t flags); 216 217 /** 218 * Send the specified buffer to the codec for processing. 219 */ 220 media_status_t AMediaCodec_queueSecureInputBuffer(AMediaCodec*, size_t idx, 221 _off_t_compat offset, 222 AMediaCodecCryptoInfo*, 223 uint64_t time, uint32_t flags); 224 225 #undef _off_t_compat 226 227 /** 228 * Get the index of the next available buffer of processed data. 229 */ 230 ssize_t AMediaCodec_dequeueOutputBuffer(AMediaCodec*, AMediaCodecBufferInfo *info, 231 int64_t timeoutUs); 232 AMediaFormat* AMediaCodec_getOutputFormat(AMediaCodec*); 233 234 /** 235 * Get format of the buffer. The specified buffer index must have been previously obtained from 236 * dequeueOutputBuffer. 237 */ 238 AMediaFormat* AMediaCodec_getBufferFormat(AMediaCodec*, size_t index); 239 240 /** 241 * If you are done with a buffer, use this call to return the buffer to 242 * the codec. If you previously specified a surface when configuring this 243 * video decoder you can optionally render the buffer. 244 */ 245 media_status_t AMediaCodec_releaseOutputBuffer(AMediaCodec*, size_t idx, bool render); 246 247 /** 248 * Dynamically sets the output surface of a codec. 249 * 250 * This can only be used if the codec was configured with an output surface. The 251 * new output surface should have a compatible usage type to the original output surface. 252 * E.g. codecs may not support switching from a SurfaceTexture (GPU readable) output 253 * to ImageReader (software readable) output. 254 * 255 * For more details, see the Java documentation for MediaCodec.setOutputSurface. 256 */ 257 media_status_t AMediaCodec_setOutputSurface(AMediaCodec*, ANativeWindow* surface); 258 259 /** 260 * If you are done with a buffer, use this call to update its surface timestamp 261 * and return it to the codec to render it on the output surface. If you 262 * have not specified an output surface when configuring this video codec, 263 * this call will simply return the buffer to the codec. 264 * 265 * For more details, see the Java documentation for MediaCodec.releaseOutputBuffer. 266 */ 267 media_status_t AMediaCodec_releaseOutputBufferAtTime( 268 AMediaCodec *mData, size_t idx, int64_t timestampNs); 269 270 #if __ANDROID_API__ >= 26 271 272 /** 273 * Creates a Surface that can be used as the input to encoder, in place of input buffers 274 * 275 * This can only be called after the codec has been configured via 276 * AMediaCodec_configure(..); and before AMediaCodec_start() has been called. 277 * 278 * The application is responsible for releasing the surface by calling 279 * ANativeWindow_release() when done. 280 * 281 * For more details, see the Java documentation for MediaCodec.createInputSurface. 282 */ 283 media_status_t AMediaCodec_createInputSurface( 284 AMediaCodec *mData, ANativeWindow **surface); 285 286 /** 287 * Creates a persistent Surface that can be used as the input to encoder 288 * 289 * Persistent surface can be reused by MediaCodec instances and can be set 290 * on a new instance via AMediaCodec_setInputSurface(). 291 * A persistent surface can be connected to at most one instance of MediaCodec 292 * at any point in time. 293 * 294 * The application is responsible for releasing the surface by calling 295 * ANativeWindow_release() when done. 296 * 297 * For more details, see the Java documentation for MediaCodec.createPersistentInputSurface. 298 */ 299 media_status_t AMediaCodec_createPersistentInputSurface( 300 ANativeWindow **surface); 301 302 /** 303 * Set a persistent-surface that can be used as the input to encoder, in place of input buffers 304 * 305 * The surface provided *must* be a persistent surface created via 306 * AMediaCodec_createPersistentInputSurface() 307 * This can only be called after the codec has been configured by calling 308 * AMediaCodec_configure(..); and before AMediaCodec_start() has been called. 309 * 310 * For more details, see the Java documentation for MediaCodec.setInputSurface. 311 */ 312 media_status_t AMediaCodec_setInputSurface( 313 AMediaCodec *mData, ANativeWindow *surface); 314 315 /** 316 * Signal additional parameters to the codec instance. 317 * 318 * Parameters can be communicated only when the codec is running, i.e 319 * after AMediaCodec_start() has been called. 320 * 321 * NOTE: Some of these parameter changes may silently fail to apply. 322 */ 323 media_status_t AMediaCodec_setParameters( 324 AMediaCodec *mData, const AMediaFormat* params); 325 326 /** 327 * Signals end-of-stream on input. Equivalent to submitting an empty buffer with 328 * AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM set. 329 * 330 * Returns AMEDIA_ERROR_INVALID_OPERATION when used with an encoder not in executing state 331 * or not receiving input from a Surface created by AMediaCodec_createInputSurface or 332 * AMediaCodec_createPersistentInputSurface. 333 * 334 * Returns the previous codec error if one exists. 335 * 336 * Returns AMEDIA_OK when completed succesfully. 337 * 338 * For more details, see the Java documentation for MediaCodec.signalEndOfInputStream. 339 */ 340 media_status_t AMediaCodec_signalEndOfInputStream(AMediaCodec *mData); 341 342 #endif /* __ANDROID_API__ >= 26 */ 343 344 #if __ANDROID_API__ >= 28 345 346 /** 347 * Get the component name. If the codec was created by createDecoderByType 348 * or createEncoderByType, what component is chosen is not known beforehand. 349 * Caller shall call AMediaCodec_releaseName to free the returned pointer. 350 */ 351 media_status_t AMediaCodec_getName(AMediaCodec*, char** out_name); 352 353 /** 354 * Free the memory pointed by name which is returned by AMediaCodec_getName. 355 */ 356 void AMediaCodec_releaseName(AMediaCodec*, char* name); 357 358 /** 359 * Set an asynchronous callback for actionable AMediaCodec events. 360 * When asynchronous callback is enabled, the client should not call 361 * AMediaCodec_getInputBuffers(), AMediaCodec_getOutputBuffers(), 362 * AMediaCodec_dequeueInputBuffer() or AMediaCodec_dequeueOutputBuffer(). 363 * 364 * Also, AMediaCodec_flush() behaves differently in asynchronous mode. 365 * After calling AMediaCodec_flush(), you must call AMediaCodec_start() to 366 * "resume" receiving input buffers, even if an input surface was created. 367 * 368 * Refer to the definition of AMediaCodecOnAsyncNotifyCallback on how each 369 * callback function is called and what are specified. 370 * The specified userdata is the pointer used when those callback functions are 371 * called. 372 * 373 * All callbacks are fired on one NDK internal thread. 374 * AMediaCodec_setAsyncNotifyCallback should not be called on the callback thread. 375 * No heavy duty task should be performed on callback thread. 376 */ 377 media_status_t AMediaCodec_setAsyncNotifyCallback( 378 AMediaCodec*, 379 AMediaCodecOnAsyncNotifyCallback callback, 380 void *userdata); 381 382 /** 383 * Release the crypto if applicable. 384 */ 385 media_status_t AMediaCodec_releaseCrypto(AMediaCodec*); 386 387 /** 388 * Call this after AMediaCodec_configure() returns successfully to get the input 389 * format accepted by the codec. Do this to determine what optional configuration 390 * parameters were supported by the codec. 391 */ 392 AMediaFormat* AMediaCodec_getInputFormat(AMediaCodec*); 393 394 /** 395 * Returns true if the codec cannot proceed further, but can be recovered by stopping, 396 * configuring, and starting again. 397 */ 398 bool AMediaCodecActionCode_isRecoverable(int32_t actionCode); 399 400 /** 401 * Returns true if the codec error is a transient issue, perhaps due to 402 * resource constraints, and that the method (or encoding/decoding) may be 403 * retried at a later time. 404 */ 405 bool AMediaCodecActionCode_isTransient(int32_t actionCode); 406 407 #endif /* __ANDROID_API__ >= 28 */ 408 409 typedef enum { 410 AMEDIACODECRYPTOINFO_MODE_CLEAR = 0, 411 AMEDIACODECRYPTOINFO_MODE_AES_CTR = 1, 412 AMEDIACODECRYPTOINFO_MODE_AES_WV = 2, 413 AMEDIACODECRYPTOINFO_MODE_AES_CBC = 3 414 } cryptoinfo_mode_t; 415 416 typedef struct { 417 int32_t encryptBlocks; 418 int32_t skipBlocks; 419 } cryptoinfo_pattern_t; 420 421 /** 422 * Create an AMediaCodecCryptoInfo from scratch. Use this if you need to use custom 423 * crypto info, rather than one obtained from AMediaExtractor. 424 * 425 * AMediaCodecCryptoInfo describes the structure of an (at least 426 * partially) encrypted input sample. 427 * A buffer's data is considered to be partitioned into "subsamples", 428 * each subsample starts with a (potentially empty) run of plain, 429 * unencrypted bytes followed by a (also potentially empty) run of 430 * encrypted bytes. 431 * numBytesOfClearData can be null to indicate that all data is encrypted. 432 * This information encapsulates per-sample metadata as outlined in 433 * ISO/IEC FDIS 23001-7:2011 "Common encryption in ISO base media file format files". 434 */ 435 AMediaCodecCryptoInfo *AMediaCodecCryptoInfo_new( 436 int numsubsamples, 437 uint8_t key[16], 438 uint8_t iv[16], 439 cryptoinfo_mode_t mode, 440 size_t *clearbytes, 441 size_t *encryptedbytes); 442 443 /** 444 * delete an AMediaCodecCryptoInfo created previously with AMediaCodecCryptoInfo_new, or 445 * obtained from AMediaExtractor 446 */ 447 media_status_t AMediaCodecCryptoInfo_delete(AMediaCodecCryptoInfo*); 448 449 /** 450 * Set the crypto pattern on an AMediaCryptoInfo object 451 */ 452 void AMediaCodecCryptoInfo_setPattern( 453 AMediaCodecCryptoInfo *info, 454 cryptoinfo_pattern_t *pattern); 455 456 /** 457 * The number of subsamples that make up the buffer's contents. 458 */ 459 size_t AMediaCodecCryptoInfo_getNumSubSamples(AMediaCodecCryptoInfo*); 460 461 /** 462 * A 16-byte opaque key 463 */ 464 media_status_t AMediaCodecCryptoInfo_getKey(AMediaCodecCryptoInfo*, uint8_t *dst); 465 466 /** 467 * A 16-byte initialization vector 468 */ 469 media_status_t AMediaCodecCryptoInfo_getIV(AMediaCodecCryptoInfo*, uint8_t *dst); 470 471 /** 472 * The type of encryption that has been applied, 473 * one of AMEDIACODECRYPTOINFO_MODE_CLEAR or AMEDIACODECRYPTOINFO_MODE_AES_CTR. 474 */ 475 cryptoinfo_mode_t AMediaCodecCryptoInfo_getMode(AMediaCodecCryptoInfo*); 476 477 /** 478 * The number of leading unencrypted bytes in each subsample. 479 */ 480 media_status_t AMediaCodecCryptoInfo_getClearBytes(AMediaCodecCryptoInfo*, size_t *dst); 481 482 /** 483 * The number of trailing encrypted bytes in each subsample. 484 */ 485 media_status_t AMediaCodecCryptoInfo_getEncryptedBytes(AMediaCodecCryptoInfo*, size_t *dst); 486 487 #endif /* __ANDROID_API__ >= 21 */ 488 489 __END_DECLS 490 491 #endif //_NDK_MEDIA_CODEC_H 492