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