• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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