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