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