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