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