Codebase list faad2 / upstream/2.8.0_cvs20150510 docs / libfaad.3
upstream/2.8.0_cvs20150510

Tree @upstream/2.8.0_cvs20150510 (Download .tar.gz)

libfaad.3 @upstream/2.8.0_cvs20150510raw · history · blame

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
.TH man 3 "15 Nov 2014" "The Debian Project" "libfaad Documentation"
.SH "NAME"
libfaad \- C library for AAC Decoding
.SH "SYNOPSIS"
.sp
.ft B
.nf

#include <neaacec\&.h>

.HP
.BI "char NEAACDECAPI *NeAACDecGetErrorMessage(" "" "unsigned char " errcode );

.HP
.B "unsigned long NEAACDECAPI NeAACDecGetCapabilities(void);"

.HP
.B "NeAACDecHandle NEAACDECAPI NeAACDecOpen(void);"

.HP
.B "NeAACDecConfigurationPtr NEAACDECAPI NeAACDecGetCurrentConfiguration("
.BI "NeAACDecHandle " hDecoder ");"

.HP
.B "unsigned char NEAACDECAPI NeAACDecSetConfiguration("
.BI "NeAACDecHandle " "hDecoder" ", NeAACDecConfigurationPtr " config ");"

.HP
/* Init the library based on info from the AAC file (ADTS/ADIF) */
.B "long NEAACDECAPI NeAACDecInit("
.BI "NeAACDecHandle " hDecoder ", unsigned char *" buffer ", unsigned long " "buffer_size" ","
.BI "unsigned long *" "samplerate" ", unsigned char *" "channels" ");"
.HP
/* Init the library using a DecoderSpecificInfo */
.B "char NEAACDECAPI NeAACDecInit2("
.BI "NeAACDecHandle " "hDecoder" ", unsigned char *" "pBuffer" ","
.BI "unsigned long " "SizeOfDecoderSpecificInfo" ","
.BI "unsigned long *" "samplerate" ", unsigned char *"channels" ");"
.HP
/* Init the library for DRM */
.B "char NEAACDECAPI NeAACDecInitDRM("
.BI "NeAACDecHandle *" "hDecoder" ", unsigned long " "samplerate" ", unsigned char " "channels" ");"
.HP
.B "void NEAACDECAPI NeAACDecPostSeekReset("
.BI "NeAACDecHandle " "hDecoder" ", long "frame" ");"
.HP
.BI "void NEAACDECAPI NeAACDecClose(NeAACDecHandle " "hDecoder" ");"
.HP
.B "void NEAACDECAPI *NeAACDecDecode("
.BI "NeAACDecHandle " "hDecoder" ", NeAACDecFrameInfo *" "hInfo" ","
.BI "unsigned char *" "buffer" ","
.BI "unsigned long " "buffer_size" ");"
.HP
.B "void NEAACDECAPI *NeAACDecDecode2("
.BI "NeAACDecHandle " "hDecoder" ", NeAACDecFrameInfo *" "hInfo" ","
.BI "unsigned char *" "buffer" ", unsigned long " "buffer_size" ","
.BI "void **" "sample_buffer" ", unsigned long " "sample_buffer_size" ");"
.HP
.B "char NEAACDECAPI NeAACDecAudioSpecificConfig("
.BI "unsigned char *" "pBuffer" ", unsigned long " "buffer_size" ","
.BI "mp4AudioSpecificConfig *" "mp4ASC" ");"
.PP
For normal use link it with the linker option \-lfaad\&.
.PP
For Digital Radio Mondiale link it with the linker option \-lfaad_drm\&.
.sp
.SH "DESCRIPTION"
.PP
.B NeAACDecGetErrorMessage
.PP
.B char NEAACDECAPI *NeAACDecGetErrorMessage(unsigned char errcode);
.PP
Convert an error code to text.
.PP
.B NeAACDecGetCapabilities
.PP
unsigned long NEAACAPI NeAACDecGetCapabilities(void);
.PP
 
.PP
This function returns the capabilities of the decoder in a 32 bit
unsigned integer.
The bits that are set in the 32 bit unsigned integer define with which
capabilities the library has been compiled.
.PP
The following capabilities are defined:
.PP
\ 
.PP
#define LC_DEC_CAP \  \  \  \  \  (1<<0) /* Can decode LC */
.PP
#define MAIN_DEC_CAP \  \  \  \  (1<<1) /* Can decode MAIN */
.PP
#define LTP_DEC_CAP \  \  \  \  \ (1<<2) /* Can decode LTP */
.PP
#define LD_DEC_CAP \  \  \  \  \  (1<<3) /* Can decode LD */
.PP
#define ERROR_RESILIENCE_CAP (1<<4) /* Can decode ER */
.PP
#define FIXED_POINT_CAP \  \  \ (1<<5) /* Fixed point */
.PP
.PP
This function can be called anytime.
.PP
.B NeAACDecOpen 
.PP NeAACDecHandle NEAACAPI NeAACDecOpen(void);
.PP
Returns a handle to a decoder context.
.PP
.B NeAACDecClose
.PP void NEAACAPI NeAACDecClose(NeAACDecHandle hDecoder);
.PP
Closes a decoder context that has been opened by NeAACDecOpen.
.PP
.B NeAACDecGetCurrentConfiguration
.PP
NeAACDecConfigurationPtr NEAACAPI
NeAACDecGetCurrentConfiguration(NeAACDecHandle hDecoder);
.PP
Returns the current decoder library configuration.
.PP
.B NeAACDecSetConfiguration
.PP unsigned char NEAACAPI NeAACDecSetConfiguration(NeAACDecHandle hDecoder, NeAACDecConfigurationPtr config);
.PP
.PP
Sets a new configuration structure for the decoder library.
.PP
\ 
.PP
Return values:
.PP 0 \[en] Error, invalid configuration.
.PP 1 \[en] OK
.PP
.B NeAACDecInit
.PP
long NEAACAPI NeAACDecInit(NeAACDecHandle hDecoder, unsigned char
*buffer, unsigned long buffer_size, unsigned long *samplerate, unsigned
char *channels);
.PP
.PP
.PP
Initialises the decoder library using information from the AAC file.
The buffer parameter should hold a small part of the AAC file, so that
the initialization can be done based on the ADTS or ADIF header.
Buffer can also be NULL, but then default initialization parameters will
be used.
.PP
Return values:
.PP
< 0 \[en] Error
.PP
>= 0 \[en] Number of bytes read.
This amount of bytes should be skipped by the program using the decoder
library.
.PP
This function fills the samplerate and channels parameters with the
detected values.
.PP
.B NeAACDecInit2
.PP
char NEAACAPI NeAACDecInit2(NeAACDecHandle hDecoder, unsigned char
*pBuffer, unsigned long SizeOfDecoderSpecificInfo, unsigned long
*samplerate, unsigned char *channels);
.PP
Initialises the decoder library based on an AudioSpecificConfig as found
inside a MP4 file.
.PP
Return values:
.PP
< 0 \[en] Error
.PP
0 \- OK
.PP
This function fills the samplerate and channels parameters with the
detected values.
.PP
.B NeAACDecInitDRM
.PP
char NEAACDECAPI NeAACDecInitDRM(NeAACDecHandle *hDecoder, unsigned long samplerate, unsigned char channels);
.PP
Initialises the decoder library for Digital Radio Mondiale using the specified sample rate
and a DRM specific channel configuration.
.PP
Return values:
.PP
< 0 \[en] Error
.PP
0 \- OK
.PP
Values for the channel configuration:
.PP
#define DRMCH_MONO          1
.PP
#define DRMCH_STEREO        2
.PP
#define DRMCH_SBR_MONO      3
.PP
#define DRMCH_SBR_STEREO    4
.PP
#define DRMCH_SBR_PS_STEREO 5
.PP
.B NeAACDecDecode
.PP
void* NEAACAPI NeAACDecDecode(NeAACDecHandle hDecoder, NeAACDecFrameInfo
*hInfo, unsigned char *buffer, unsigned long buffer_size);
.PP
.PP
Decodes the AAC data passed in buffer.
.PP
Returns a pointer to a sample buffer or NULL.
Info about the decoded frame is filled in in the NeAACDecFrameInfo
structure.
This structure holds information about errors during decoding, number of
sample, number of channels and samplerate.
The returned buffer contains the channel interleaved samples of the
frame.
.PP
.B NeAACDecDecode2
.PP
void NEAACDECAPI *NeAACDecDecode2(NeAACDecHandle hDecoder,
                                  NeAACDecFrameInfo *hInfo,
                                  unsigned char *buffer,
                                  unsigned long buffer_size,
                                  void **sample_buffer,
                                  unsigned long sample_buffer_size);



.PP
.B NeAACDecAudioSpecificConfig
.PP
char NEAACDECAPI NeAACDecAudioSpecificConfig(unsigned char *pBuffer,
                                             unsigned long buffer_size,
                                             mp4AudioSpecificConfig *mp4ASC);
.PP
.B Structures
.RS 4
.PP NeAACDecConfiguration
.RE
.PP
typedef struct NeAACDecConfiguration
.PP
{
.PP
\  \  unsigned char defObjectType;
.PP
\  \  unsigned long defSampleRate;
.PP
\  \  unsigned char outputFormat;
.PP
\  \  unsigned char downMatrix;
.PP
\  \  unsigned char useOldADTSFormat;
.PP
} NeAACDecConfiguration, *NeAACDecConfigurationPtr;
.PP

.PP
Members:
.PP
defObjectType: determines the default object type assumed when the
library is initialized without any data from the AAC file (eg: when NULL
is passed as buffer in NeAACDecInit()).
Can be any of the following values:
.PP
#define MAIN \  \  \  1 /* MAIN */
.PP
#define LC \  \  \  \  2 /* Low Complexity (default) */
.PP
#define SSR \  \  \  \ 3 /* Scalable SampleRate */
.PP
#define LTP \  \  \  \ 4 /* Long Term Predition */
.PP
#define HE_AAC \  \  5 /* High Efficiency (SBR) */
.PP
#define ER_LC \  \  17 /* Error Resilient Low Complexity */
.PP
#define ER_LTP \  \ 19 /* Error Resilient Long Term Prediction */
.PP
#define LD \  \  \  \ 23 /* Low Delay */
.PP
#define DRM_ER_LC 27 /* special object type for DRM only if linking with \-lfaad_drm */
.PP
defSampleRate: determines the default samplerate assumed when the
library is initialized.
Default value is 44100.
.PP
outputFormat: determines the output format returned by the decoder
library.
Can be any of the following values:
.PP
#define FAAD_FMT_16BIT \ 1 /* 16 bit integers */
.PP
#define FAAD_FMT_24BIT \ 2 /* 24 bit values packed in 32 bit integers */
.PP
#define FAAD_FMT_32BIT \ 3 /* 32 bit integers */
.PP
#define FAAD_FMT_FLOAT \ 4 /* single precision floating point */
.PP
#define FAAD_FMT_DOUBLE 5 /* double precision floating point */
.PP
downMatrix: determines whether a 5.1 channel AAC file should be
downmatrixed to 2 channel output (value: 1) or whether the output should
stay as 5.1 channels (value: 0).
.PP
useOldADTSFormat: determines whether the decoder should assume the
currently defined 56 bit ADTS header (value: 0) or the 58 bit ADTS
header (value: 1) defined in previous versions of the AAC standard.
This value should normally always stay at the value 0, it only exists to
provide playback capabilities for people that have AAC files with the
old header format.
All current encoders should output the new ADTS format.
NeAACDecFrameInfo\ 
.PP
This structure is returned after decoding a frame and provides info
about the decoded frame.
.PP
typedef struct NeAACDecFrameInfo
.PP
{
.PP
\  \  unsigned long bytesconsumed;
.PP
\  \  unsigned long samples;
.PP
\  \  unsigned char channels;
.PP
\  \  unsigned char error;
.PP
\  \  unsigned long samplerate;
.PP
\  \  unsigned char sbr;
.PP
\  \  unsigned char object_type;
.PP
\  \  unsigned char header_type;
.PP
\  \  unsigned char num_front_channels;
.PP
\  \  unsigned char num_side_channels;
.PP
\  \  unsigned char num_back_channels;
.PP
\  \  unsigned char num_lfe_channels;
.PP
\  \  unsigned char channel_position[64];
.PP
\  \  unsigned char ps;
.PP
} NeAACDecFrameInfo;
.PP
\ 
.PP
Members:
.PP
bytesconsumed: the number of bytes consumed for decoding this frame.
.PP
samples: the number of audio samples in this frame.
Each channel is counted separately.
So when a single channel has 1024 samples and the file has 2 channels,
this value will be 2*1024 = 2048.
.PP
channels: number of audio channels in this frame
.PP
error: contains an error value if an error occurred, 0 otherwise.
.PP
samplerate: the samplerate of the frame.
.PP
sbr: tells wether sbr is used in this file or not.
Can contain any of the following values:
.PP
#define NO_SBR \  \  \  \  \  0 /* no SBR used in this file */
.PP
#define SBR_UPSAMPLED \  \ 1 /* upsampled SBR used */
.PP
#define SBR_DOWNSAMPLED \ 2 /* downsampled SBR used */
.PP
#define NO_SBR_UPSAMPLED 3 /* no SBR used, but file is upsampled by a
factor 2 anyway */
.PP
object_type: contains the object type of the AAC file.
Can be any of the values as defined in 1.9.1.
.PP
header_type: contains the header type of the file that is being decoded.
Can contain any of the following values:
.PP
#define RAW \  \  \  \ 0 /* No header */
.PP
#define ADIF \  \  \  1 /* single ADIF header at the beginning of the
file */
.PP
#define ADTS \  \  \  2 /* ADTS header at the beginning of each frame */
.PP
num_front_channels, num_side_channels, num_back_channels,
num_lfe_channels: each of these values contain the number of channels of
a certain type.
.PP
channel_position[64]: contains the position of each of the channels that
is returned by the frame decode function.
Can contain any of the following values:
.PP
#define FRONT_CHANNEL_CENTER (1)
.PP
#define FRONT_CHANNEL_LEFT \  (2)
.PP
#define FRONT_CHANNEL_RIGHT \ (3)
.PP
#define SIDE_CHANNEL_LEFT \  \ (4)
.PP
#define SIDE_CHANNEL_RIGHT \  (5)
.PP
#define BACK_CHANNEL_LEFT \  \ (6)
.PP
#define BACK_CHANNEL_RIGHT \  (7)
.PP
#define BACK_CHANNEL_CENTER \ (8)
.PP
#define LFE_CHANNEL \  \  \  \  \ (9)
.PP
#define UNKNOWN_CHANNEL \  \  \ (0)
.PP
ps: PS not used (0) or used (1).
API usage\ 
.PP
The following pseudo\-code describes how and in which order to use the
different library functions.
.PP
\ 
.PP
unsigned long cap = NeAACDecGetCapabilities();
.PP
// Check if decoder has the needed capabilities
.PP
\ 
.PP
// Open the library
.PP
NeAACDecHandle hAac = NeAACDecOpen();
.PP
\ 
.PP
// Get the current config
.PP
NeAACDecConfigurationPtr conf = NeAACDecGetCurrentConfiguration(hAac);
.PP
\ 
.PP
//
.PP
// If needed change some of the values in conf
.PP
//
.PP
\ 
.PP
// Set the new configuration
.PP
NeAACDecSetConfiguration(hAac, conf);
.PP
.PP
// Initialise the library using one of the initialization functions
.PP
char err = NeAACDecInit2(hAac, asc, asc_size, &samplerate, &channels);
.PP
if (err != 0)
.PP
{
.PP
\ //
.PP
\ // Handle error
.PP
\ //
.PP
}
.PP
\ 
.PP
// Loop until decoding finished
.PP
do {
.PP
\ //
.PP
\ // Put next frame in buffer
.PP
\ //
.PP
\ 
.PP
\ // Decode the frame in buffer
.PP
\  \  \  \  samplebuffer = NeAACDecDecode(hAac, &hInfo, buffer,
.PP
buffer_size);
.PP
\ 
.PP
if ((hInfo.error == 0) && (hInfo.samples > 0))
.PP
{
.PP
\ //
.PP
\ // do what you need to do with the decoded samples
.PP
\ //
.PP
} else if (hInfo.error != 0) {
.PP
\ //
.PP
\ // Some error occurred while decoding this frame
.PP
\ //
.PP
}
.PP
} while (more data available);
.PP
\ 
.PP
NeAACDecClose(hAac);
.SH "SEE ALSO"
.PP
\fBlibfaad_drm\fR(3),
\fBlibfaac\fR(3)\&.
.SH "AUTHOR"
.PP
Menno Bakker <mbakker@nero.com>
.PP Man Page by Julian Cable <jcable@users.sf.net>