Codebase list faad2 / 2fed97f
Add extensive API documentation in libfaad.3, courtesy of Julian Cable. Fabian Greffrath 9 years ago
2 changed file(s) with 532 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
+1
-0
debian/libfaad-dev.manpages less more
0 debian/libfaad.3
+531
-0
debian/libfaad.3 less more
0 .TH man 3 "15 Nov 2014" "The Debian Project" "libfaad Documentation"
1 .SH "NAME"
2 libfaad \- C library for AAC Decoding
3 .SH "SYNOPSIS"
4 .sp
5 .ft B
6 .nf
7
8 #include <neaacec\&.h>
9
10 .HP
11 .BI "char NEAACDECAPI *NeAACDecGetErrorMessage(" "" "unsigned char " errcode );
12
13 .HP
14 .B "unsigned long NEAACDECAPI NeAACDecGetCapabilities(void);"
15
16 .HP
17 .B "NeAACDecHandle NEAACDECAPI NeAACDecOpen(void);"
18
19 .HP
20 .B "NeAACDecConfigurationPtr NEAACDECAPI NeAACDecGetCurrentConfiguration("
21 .BI "NeAACDecHandle " hDecoder ");"
22
23 .HP
24 .B "unsigned char NEAACDECAPI NeAACDecSetConfiguration("
25 .BI "NeAACDecHandle " "hDecoder" ", NeAACDecConfigurationPtr " config ");"
26
27 .HP
28 /* Init the library based on info from the AAC file (ADTS/ADIF) */
29 .B "long NEAACDECAPI NeAACDecInit("
30 .BI "NeAACDecHandle " hDecoder ", unsigned char *" buffer ", unsigned long " "buffer_size" ","
31 .BI "unsigned long *" "samplerate" ", unsigned char *" "channels" ");"
32 .HP
33 /* Init the library using a DecoderSpecificInfo */
34 .B "char NEAACDECAPI NeAACDecInit2("
35 .BI "NeAACDecHandle " "hDecoder" ", unsigned char *" "pBuffer" ","
36 .BI "unsigned long " "SizeOfDecoderSpecificInfo" ","
37 .BI "unsigned long *" "samplerate" ", unsigned char *"channels" ");"
38 .HP
39 /* Init the library for DRM */
40 .B "char NEAACDECAPI NeAACDecInitDRM("
41 .BI "NeAACDecHandle *" "hDecoder" ", unsigned long " "samplerate" ", unsigned char " "channels" ");"
42 .HP
43 .B "void NEAACDECAPI NeAACDecPostSeekReset("
44 .BI "NeAACDecHandle " "hDecoder" ", long "frame" ");"
45 .HP
46 .BI "void NEAACDECAPI NeAACDecClose(NeAACDecHandle " "hDecoder" ");"
47 .HP
48 .B "void NEAACDECAPI *NeAACDecDecode("
49 .BI "NeAACDecHandle " "hDecoder" ", NeAACDecFrameInfo *" "hInfo" ","
50 .BI "unsigned char *" "buffer" ","
51 .BI "unsigned long " "buffer_size" ");"
52 .HP
53 .B "void NEAACDECAPI *NeAACDecDecode2("
54 .BI "NeAACDecHandle " "hDecoder" ", NeAACDecFrameInfo *" "hInfo" ","
55 .BI "unsigned char *" "buffer" ", unsigned long " "buffer_size" ","
56 .BI "void **" "sample_buffer" ", unsigned long " "sample_buffer_size" ");"
57 .HP
58 .B "char NEAACDECAPI NeAACDecAudioSpecificConfig("
59 .BI "unsigned char *" "pBuffer" ", unsigned long " "buffer_size" ","
60 .BI "mp4AudioSpecificConfig *" "mp4ASC" ");"
61 .PP
62 For normal use link it with the linker option \-lfaad\&.
63 .PP
64 For Digital Radio Mondiale link it with the linker option \-lfaad_drm\&.
65 .sp
66 .SH "DESCRIPTION"
67 .PP
68 .B NeAACDecGetErrorMessage
69 .PP
70 .B char NEAACDECAPI *NeAACDecGetErrorMessage(unsigned char errcode);
71 .PP
72 Convert an error code to text.
73 .PP
74 .B NeAACDecGetCapabilities
75 .PP
76 unsigned long NEAACAPI NeAACDecGetCapabilities(void);
77 .PP
78
79 .PP
80 This function returns the capabilities of the decoder in a 32 bit
81 unsigned integer.
82 The bits that are set in the 32 bit unsigned integer define with which
83 capabilities the library has been compiled.
84 .PP
85 The following capabilities are defined:
86 .PP
87 \
88 .PP
89 #define LC_DEC_CAP \ \ \ \ \ (1<<0) /* Can decode LC */
90 .PP
91 #define MAIN_DEC_CAP \ \ \ \ (1<<1) /* Can decode MAIN */
92 .PP
93 #define LTP_DEC_CAP \ \ \ \ \ (1<<2) /* Can decode LTP */
94 .PP
95 #define LD_DEC_CAP \ \ \ \ \ (1<<3) /* Can decode LD */
96 .PP
97 #define ERROR_RESILIENCE_CAP (1<<4) /* Can decode ER */
98 .PP
99 #define FIXED_POINT_CAP \ \ \ (1<<5) /* Fixed point */
100 .PP
101 .PP
102 This function can be called anytime.
103 .PP
104 .B NeAACDecOpen
105 .PP NeAACDecHandle NEAACAPI NeAACDecOpen(void);
106 .PP
107 Returns a handle to a decoder context.
108 .PP
109 .B NeAACDecClose
110 .PP void NEAACAPI NeAACDecClose(NeAACDecHandle hDecoder);
111 .PP
112 Closes a decoder context that has been opened by NeAACDecOpen.
113 .PP
114 .B NeAACDecGetCurrentConfiguration
115 .PP
116 NeAACDecConfigurationPtr NEAACAPI
117 NeAACDecGetCurrentConfiguration(NeAACDecHandle hDecoder);
118 .PP
119 Returns the current decoder library configuration.
120 .PP
121 .B NeAACDecSetConfiguration
122 .PP unsigned char NEAACAPI NeAACDecSetConfiguration(NeAACDecHandle hDecoder, NeAACDecConfigurationPtr config);
123 .PP
124 .PP
125 Sets a new configuration structure for the decoder library.
126 .PP
127 \
128 .PP
129 Return values:
130 .PP 0 \[en] Error, invalid configuration.
131 .PP 1 \[en] OK
132 .PP
133 .B NeAACDecInit
134 .PP
135 long NEAACAPI NeAACDecInit(NeAACDecHandle hDecoder, unsigned char
136 *buffer, unsigned long buffer_size, unsigned long *samplerate, unsigned
137 char *channels);
138 .PP
139 .PP
140 .PP
141 Initialises the decoder library using information from the AAC file.
142 The buffer parameter should hold a small part of the AAC file, so that
143 the initialization can be done based on the ADTS or ADIF header.
144 Buffer can also be NULL, but then default initialization parameters will
145 be used.
146 .PP
147 Return values:
148 .PP
149 < 0 \[en] Error
150 .PP
151 >= 0 \[en] Number of bytes read.
152 This amount of bytes should be skipped by the program using the decoder
153 library.
154 .PP
155 This function fills the samplerate and channels parameters with the
156 detected values.
157 .PP
158 .B NeAACDecInit2
159 .PP
160 char NEAACAPI NeAACDecInit2(NeAACDecHandle hDecoder, unsigned char
161 *pBuffer, unsigned long SizeOfDecoderSpecificInfo, unsigned long
162 *samplerate, unsigned char *channels);
163 .PP
164 Initialises the decoder library based on an AudioSpecificConfig as found
165 inside a MP4 file.
166 .PP
167 Return values:
168 .PP
169 < 0 \[en] Error
170 .PP
171 0 \- OK
172 .PP
173 This function fills the samplerate and channels parameters with the
174 detected values.
175 .PP
176 .B NeAACDecInitDRM
177 .PP
178 char NEAACDECAPI NeAACDecInitDRM(NeAACDecHandle *hDecoder, unsigned long samplerate, unsigned char channels);
179 .PP
180 Initialises the decoder library for Digital Radio Mondiale using the specified sample rate
181 and a DRM specific channel configuration.
182 .PP
183 Return values:
184 .PP
185 < 0 \[en] Error
186 .PP
187 0 \- OK
188 .PP
189 Values for the channel configuration:
190 .PP
191 #define DRMCH_MONO 1
192 .PP
193 #define DRMCH_STEREO 2
194 .PP
195 #define DRMCH_SBR_MONO 3
196 .PP
197 #define DRMCH_SBR_STEREO 4
198 .PP
199 #define DRMCH_SBR_PS_STEREO 5
200 .PP
201 .B NeAACDecDecode
202 .PP
203 void* NEAACAPI NeAACDecDecode(NeAACDecHandle hDecoder, NeAACDecFrameInfo
204 *hInfo, unsigned char *buffer, unsigned long buffer_size);
205 .PP
206 .PP
207 Decodes the AAC data passed in buffer.
208 .PP
209 Returns a pointer to a sample buffer or NULL.
210 Info about the decoded frame is filled in in the NeAACDecFrameInfo
211 structure.
212 This structure holds information about errors during decoding, number of
213 sample, number of channels and samplerate.
214 The returned buffer contains the channel interleaved samples of the
215 frame.
216 .PP
217 .B NeAACDecDecode2
218 .PP
219 void NEAACDECAPI *NeAACDecDecode2(NeAACDecHandle hDecoder,
220 NeAACDecFrameInfo *hInfo,
221 unsigned char *buffer,
222 unsigned long buffer_size,
223 void **sample_buffer,
224 unsigned long sample_buffer_size);
225
226
227
228 .PP
229 .B NeAACDecAudioSpecificConfig
230 .PP
231 char NEAACDECAPI NeAACDecAudioSpecificConfig(unsigned char *pBuffer,
232 unsigned long buffer_size,
233 mp4AudioSpecificConfig *mp4ASC);
234 .PP
235 .B Structures
236 .RS 4
237 .PP NeAACDecConfiguration
238 .RE
239 .PP
240 typedef struct NeAACDecConfiguration
241 .PP
242 {
243 .PP
244 \ \ unsigned char defObjectType;
245 .PP
246 \ \ unsigned long defSampleRate;
247 .PP
248 \ \ unsigned char outputFormat;
249 .PP
250 \ \ unsigned char downMatrix;
251 .PP
252 \ \ unsigned char useOldADTSFormat;
253 .PP
254 } NeAACDecConfiguration, *NeAACDecConfigurationPtr;
255 .PP
256
257 .PP
258 Members:
259 .PP
260 defObjectType: determines the default object type assumed when the
261 library is initialized without any data from the AAC file (eg: when NULL
262 is passed as buffer in NeAACDecInit()).
263 Can be any of the following values:
264 .PP
265 #define MAIN \ \ \ 1 /* MAIN */
266 .PP
267 #define LC \ \ \ \ 2 /* Low Complexity (default) */
268 .PP
269 #define SSR \ \ \ \ 3 /* Scalable SampleRate */
270 .PP
271 #define LTP \ \ \ \ 4 /* Long Term Predition */
272 .PP
273 #define HE_AAC \ \ 5 /* High Efficiency (SBR) */
274 .PP
275 #define ER_LC \ \ 17 /* Error Resilient Low Complexity */
276 .PP
277 #define ER_LTP \ \ 19 /* Error Resilient Long Term Prediction */
278 .PP
279 #define LD \ \ \ \ 23 /* Low Delay */
280 .PP
281 #define DRM_ER_LC 27 /* special object type for DRM only if linking with -lfaad_drm */
282 .PP
283 defSampleRate: determines the default samplerate assumed when the
284 library is initialized.
285 Default value is 44100.
286 .PP
287 outputFormat: determines the output format returned by the decoder
288 library.
289 Can be any of the following values:
290 .PP
291 #define FAAD_FMT_16BIT \ 1 /* 16 bit integers */
292 .PP
293 #define FAAD_FMT_24BIT \ 2 /* 24 bit values packed in 32 bit integers */
294 .PP
295 #define FAAD_FMT_32BIT \ 3 /* 32 bit integers */
296 .PP
297 #define FAAD_FMT_FLOAT \ 4 /* single precision floating point */
298 .PP
299 #define FAAD_FMT_DOUBLE 5 /* double precision floating point */
300 .PP
301 downMatrix: determines whether a 5.1 channel AAC file should be
302 downmatrixed to 2 channel output (value: 1) or whether the output should
303 stay as 5.1 channels (value: 0).
304 .PP
305 useOldADTSFormat: determines whether the decoder should assume the
306 currently defined 56 bit ADTS header (value: 0) or the 58 bit ADTS
307 header (value: 1) defined in previous versions of the AAC standard.
308 This value should normally always stay at the value 0, it only exists to
309 provide playback capabilities for people that have AAC files with the
310 old header format.
311 All current encoders should output the new ADTS format.
312 NeAACDecFrameInfo\
313 .PP
314 This structure is returned after decoding a frame and provides info
315 about the decoded frame.
316 .PP
317 typedef struct NeAACDecFrameInfo
318 .PP
319 {
320 .PP
321 \ \ unsigned long bytesconsumed;
322 .PP
323 \ \ unsigned long samples;
324 .PP
325 \ \ unsigned char channels;
326 .PP
327 \ \ unsigned char error;
328 .PP
329 \ \ unsigned long samplerate;
330 .PP
331 \ \ unsigned char sbr;
332 .PP
333 \ \ unsigned char object_type;
334 .PP
335 \ \ unsigned char header_type;
336 .PP
337 \ \ unsigned char num_front_channels;
338 .PP
339 \ \ unsigned char num_side_channels;
340 .PP
341 \ \ unsigned char num_back_channels;
342 .PP
343 \ \ unsigned char num_lfe_channels;
344 .PP
345 \ \ unsigned char channel_position[64];
346 .PP
347 \ \ unsigned char ps;
348 .PP
349 } NeAACDecFrameInfo;
350 .PP
351 \
352 .PP
353 Members:
354 .PP
355 bytesconsumed: the number of bytes consumed for decoding this frame.
356 .PP
357 samples: the number of audio samples in this frame.
358 Each channel is counted separately.
359 So when a single channel has 1024 samples and the file has 2 channels,
360 this value will be 2*1024 = 2048.
361 .PP
362 channels: number of audio channels in this frame
363 .PP
364 error: contains an error value if an error occurred, 0 otherwise.
365 .PP
366 samplerate: the samplerate of the frame.
367 .PP
368 sbr: tells wether sbr is used in this file or not.
369 Can contain any of the following values:
370 .PP
371 #define NO_SBR \ \ \ \ \ 0 /* no SBR used in this file */
372 .PP
373 #define SBR_UPSAMPLED \ \ 1 /* upsampled SBR used */
374 .PP
375 #define SBR_DOWNSAMPLED \ 2 /* downsampled SBR used */
376 .PP
377 #define NO_SBR_UPSAMPLED 3 /* no SBR used, but file is upsampled by a
378 factor 2 anyway */
379 .PP
380 object_type: contains the object type of the AAC file.
381 Can be any of the values as defined in 1.9.1.
382 .PP
383 header_type: contains the header type of the file that is being decoded.
384 Can contain any of the following values:
385 .PP
386 #define RAW \ \ \ \ 0 /* No header */
387 .PP
388 #define ADIF \ \ \ 1 /* single ADIF header at the beginning of the
389 file */
390 .PP
391 #define ADTS \ \ \ 2 /* ADTS header at the beginning of each frame */
392 .PP
393 num_front_channels, num_side_channels, num_back_channels,
394 num_lfe_channels: each of these values contain the number of channels of
395 a certain type.
396 .PP
397 channel_position[64]: contains the position of each of the channels that
398 is returned by the frame decode function.
399 Can contain any of the following values:
400 .PP
401 #define FRONT_CHANNEL_CENTER (1)
402 .PP
403 #define FRONT_CHANNEL_LEFT \ (2)
404 .PP
405 #define FRONT_CHANNEL_RIGHT \ (3)
406 .PP
407 #define SIDE_CHANNEL_LEFT \ \ (4)
408 .PP
409 #define SIDE_CHANNEL_RIGHT \ (5)
410 .PP
411 #define BACK_CHANNEL_LEFT \ \ (6)
412 .PP
413 #define BACK_CHANNEL_RIGHT \ (7)
414 .PP
415 #define BACK_CHANNEL_CENTER \ (8)
416 .PP
417 #define LFE_CHANNEL \ \ \ \ \ (9)
418 .PP
419 #define UNKNOWN_CHANNEL \ \ \ (0)
420 .PP
421 ps: PS not used (0) or used (1).
422 API usage\
423 .PP
424 The following pseudo\-code describes how and in which order to use the
425 different library functions.
426 .PP
427 \
428 .PP
429 unsigned long cap = NeAACDecGetCapabilities();
430 .PP
431 // Check if decoder has the needed capabilities
432 .PP
433 \
434 .PP
435 // Open the library
436 .PP
437 NeAACDecHandle hAac = NeAACDecOpen();
438 .PP
439 \
440 .PP
441 // Get the current config
442 .PP
443 NeAACDecConfigurationPtr conf = NeAACDecGetCurrentConfiguration(hAac);
444 .PP
445 \
446 .PP
447 //
448 .PP
449 // If needed change some of the values in conf
450 .PP
451 //
452 .PP
453 \
454 .PP
455 // Set the new configuration
456 .PP
457 NeAACDecSetConfiguration(hAac, conf);
458 .PP
459 .PP
460 // Initialise the library using one of the initialization functions
461 .PP
462 char err = NeAACDecInit2(hAac, asc, asc_size, &samplerate, &channels);
463 .PP
464 if (err != 0)
465 .PP
466 {
467 .PP
468 \ //
469 .PP
470 \ // Handle error
471 .PP
472 \ //
473 .PP
474 }
475 .PP
476 \
477 .PP
478 // Loop until decoding finished
479 .PP
480 do {
481 .PP
482 \ //
483 .PP
484 \ // Put next frame in buffer
485 .PP
486 \ //
487 .PP
488 \
489 .PP
490 \ // Decode the frame in buffer
491 .PP
492 \ \ \ \ samplebuffer = NeAACDecDecode(hAac, &hInfo, buffer,
493 .PP
494 buffer_size);
495 .PP
496 \
497 .PP
498 if ((hInfo.error == 0) && (hInfo.samples > 0))
499 .PP
500 {
501 .PP
502 \ //
503 .PP
504 \ // do what you need to do with the decoded samples
505 .PP
506 \ //
507 .PP
508 } else if (hInfo.error != 0) {
509 .PP
510 \ //
511 .PP
512 \ // Some error occurred while decoding this frame
513 .PP
514 \ //
515 .PP
516 }
517 .PP
518 } while (more data available);
519 .PP
520 \
521 .PP
522 NeAACDecClose(hAac);
523 .SH "SEE ALSO"
524 .PP
525 \fBlibfaad_drm\fR(3),
526 \fBlibfaac\fR(3)\&.
527 .SH "AUTHOR"
528 .PP
529 Menno Bakker <mbakker@nero.com>
530 .PP Man Page by Julian Cable <jcable@users.sf.net>