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 NdkMediaExtractor.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_EXTRACTOR_H 37 #define _NDK_MEDIA_EXTRACTOR_H 38 39 #include <stdbool.h> 40 #include <sys/cdefs.h> 41 #include <sys/types.h> 42 43 #include "NdkMediaCodec.h" 44 #include "NdkMediaDataSource.h" 45 #include "NdkMediaFormat.h" 46 #include "NdkMediaCrypto.h" 47 48 __BEGIN_DECLS 49 50 struct AMediaExtractor; 51 typedef struct AMediaExtractor AMediaExtractor; 52 53 #if __ANDROID_API__ >= 21 54 55 /** 56 * Create new media extractor. 57 * 58 * Available since API level 21. 59 */ 60 AMediaExtractor* AMediaExtractor_new() __INTRODUCED_IN(21); 61 62 /** 63 * Delete a previously created media extractor. 64 * 65 * Available since API level 21. 66 */ 67 media_status_t AMediaExtractor_delete(AMediaExtractor*) __INTRODUCED_IN(21); 68 69 /** 70 * Set the file descriptor from which the extractor will read. 71 * 72 * Available since API level 21. 73 */ 74 media_status_t AMediaExtractor_setDataSourceFd(AMediaExtractor*, int fd, off64_t offset, 75 off64_t length) __INTRODUCED_IN(21); 76 77 /** 78 * Set the URI from which the extractor will read. 79 * 80 * Available since API level 21. 81 */ 82 media_status_t AMediaExtractor_setDataSource(AMediaExtractor*, 83 const char *location) __INTRODUCED_IN(21); 84 85 #if __ANDROID_API__ >= 28 86 87 /** 88 * Set the custom data source implementation from which the extractor will read. 89 * 90 * Available since API level 28. 91 */ 92 media_status_t AMediaExtractor_setDataSourceCustom(AMediaExtractor*, 93 AMediaDataSource *src) __INTRODUCED_IN(28); 94 95 #endif /* __ANDROID_API__ >= 28 */ 96 97 /** 98 * Return the number of tracks in the previously specified media file 99 * 100 * Available since API level 21. 101 */ 102 size_t AMediaExtractor_getTrackCount(AMediaExtractor*) __INTRODUCED_IN(21); 103 104 /** 105 * Return the format of the specified track. The caller must free the returned format 106 * 107 * Available since API level 21. 108 */ 109 AMediaFormat* AMediaExtractor_getTrackFormat(AMediaExtractor*, size_t idx) __INTRODUCED_IN(21); 110 111 /** 112 * Select the specified track. Subsequent calls to readSampleData, getSampleTrackIndex and 113 * getSampleTime only retrieve information for the subset of tracks selected. 114 * Selecting the same track multiple times has no effect, the track is 115 * only selected once. 116 * 117 * Available since API level 21. 118 */ 119 media_status_t AMediaExtractor_selectTrack(AMediaExtractor*, size_t idx) __INTRODUCED_IN(21); 120 121 /** 122 * Unselect the specified track. Subsequent calls to readSampleData, getSampleTrackIndex and 123 * getSampleTime only retrieve information for the subset of tracks selected. 124 * 125 * Available since API level 21. 126 */ 127 media_status_t AMediaExtractor_unselectTrack(AMediaExtractor*, size_t idx) __INTRODUCED_IN(21); 128 129 /** 130 * Read the current sample. 131 * 132 * Available since API level 21. 133 */ 134 ssize_t AMediaExtractor_readSampleData(AMediaExtractor*, 135 uint8_t *buffer, size_t capacity) __INTRODUCED_IN(21); 136 137 /** 138 * Read the current sample's flags. 139 * 140 * Available since API level 21. 141 */ 142 uint32_t AMediaExtractor_getSampleFlags(AMediaExtractor*) __INTRODUCED_IN(21); 143 144 /** 145 * Returns the track index the current sample originates from (or -1 146 * if no more samples are available) 147 * 148 * Available since API level 21. 149 */ 150 int AMediaExtractor_getSampleTrackIndex(AMediaExtractor*) __INTRODUCED_IN(21); 151 152 /** 153 * Returns the current sample's presentation time in microseconds. 154 * or -1 if no more samples are available. 155 * 156 * Available since API level 21. 157 */ 158 int64_t AMediaExtractor_getSampleTime(AMediaExtractor*) __INTRODUCED_IN(21); 159 160 /** 161 * Advance to the next sample. Returns false if no more sample data 162 * is available (end of stream). 163 * 164 * Available since API level 21. 165 */ 166 bool AMediaExtractor_advance(AMediaExtractor*) __INTRODUCED_IN(21); 167 168 typedef enum { 169 AMEDIAEXTRACTOR_SEEK_PREVIOUS_SYNC, 170 AMEDIAEXTRACTOR_SEEK_NEXT_SYNC, 171 AMEDIAEXTRACTOR_SEEK_CLOSEST_SYNC 172 } SeekMode; 173 174 /** 175 * Available since API level 21. 176 */ 177 media_status_t AMediaExtractor_seekTo(AMediaExtractor*, 178 int64_t seekPosUs, SeekMode mode) __INTRODUCED_IN(21); 179 180 /** 181 * mapping of crypto scheme uuid to the scheme specific data for that scheme 182 */ 183 typedef struct PsshEntry { 184 AMediaUUID uuid; 185 size_t datalen; 186 void *data; 187 } PsshEntry; 188 189 /** 190 * list of crypto schemes and their data 191 */ 192 typedef struct PsshInfo { 193 size_t numentries; 194 PsshEntry entries[0]; 195 } PsshInfo; 196 197 /** 198 * Get the PSSH info if present. 199 * 200 * Available since API level 21. 201 */ 202 PsshInfo* AMediaExtractor_getPsshInfo(AMediaExtractor*) __INTRODUCED_IN(21); 203 204 /** 205 * Available since API level 21. 206 */ 207 AMediaCodecCryptoInfo *AMediaExtractor_getSampleCryptoInfo(AMediaExtractor *) __INTRODUCED_IN(21); 208 209 enum { 210 AMEDIAEXTRACTOR_SAMPLE_FLAG_SYNC = 1, 211 AMEDIAEXTRACTOR_SAMPLE_FLAG_ENCRYPTED = 2, 212 }; 213 214 #if __ANDROID_API__ >= 28 215 216 /** 217 * Returns the format of the extractor. The caller must free the returned format 218 * using AMediaFormat_delete(format). 219 * 220 * This function will always return a format; however, the format could be empty 221 * (no key-value pairs) if the media container does not provide format information. 222 * 223 * Available since API level 28. 224 */ 225 AMediaFormat* AMediaExtractor_getFileFormat(AMediaExtractor*) __INTRODUCED_IN(28); 226 227 /** 228 * Returns the size of the current sample in bytes, or -1 when no samples are 229 * available (end of stream). This API can be used in in conjunction with 230 * AMediaExtractor_readSampleData: 231 * 232 * ssize_t sampleSize = AMediaExtractor_getSampleSize(ex); 233 * uint8_t *buf = new uint8_t[sampleSize]; 234 * AMediaExtractor_readSampleData(ex, buf, sampleSize); 235 * 236 * Available since API level 28. 237 */ 238 ssize_t AMediaExtractor_getSampleSize(AMediaExtractor*) __INTRODUCED_IN(28); 239 240 /** 241 * Returns the duration of cached media samples downloaded from a network data source 242 * (AMediaExtractor_setDataSource with a "http(s)" URI) in microseconds. 243 * 244 * This information is calculated using total bitrate; if total bitrate is not in the 245 * media container it is calculated using total duration and file size. 246 * 247 * Returns -1 when the extractor is not reading from a network data source, or when the 248 * cached duration cannot be calculated (bitrate, duration, and file size information 249 * not available). 250 * 251 * Available since API level 28. 252 */ 253 int64_t AMediaExtractor_getCachedDuration(AMediaExtractor *) __INTRODUCED_IN(28); 254 255 /** 256 * Read the current sample's metadata format into |fmt|. Examples of sample metadata are 257 * SEI (supplemental enhancement information) and MPEG user data, both of which can embed 258 * closed-caption data. 259 * 260 * Returns AMEDIA_OK on success or AMEDIA_ERROR_* to indicate failure reason. 261 * Existing key-value pairs in |fmt| would be removed if this API returns AMEDIA_OK. 262 * The contents of |fmt| is undefined if this API returns AMEDIA_ERROR_*. 263 * 264 * Available since API level 28. 265 */ 266 media_status_t AMediaExtractor_getSampleFormat(AMediaExtractor *ex, 267 AMediaFormat *fmt) __INTRODUCED_IN(28); 268 269 #endif /* __ANDROID_API__ >= 28 */ 270 271 #endif /* __ANDROID_API__ >= 21 */ 272 273 __END_DECLS 274 275 #endif // _NDK_MEDIA_EXTRACTOR_H 276 277 /** @} */ 278