libquicktime: Audio decoding

# Audio decoding
[Audio]

Audio related definitions and functions (reading). More...

## Functions
long | quicktime_audio_length (quicktime_t *file, int track)
| Get the audio length.
long | quicktime_audio_position (quicktime_t *file, int track)
| Get the audio position.
int | quicktime_audio_tracks (quicktime_t *file)
| Get the number of audio tracks.
int | quicktime_has_audio (quicktime_t *file)
| Check if a file has at least one audio track.
long | quicktime_sample_rate (quicktime_t *file, int track)
| Get the samplerate of an audio track.
int | quicktime_audio_bits (quicktime_t *file, int track)
| Get the bits per sample of an audio track.
int | quicktime_track_channels (quicktime_t *file, int track)
| Get the number of channels of an audio track.
char * | quicktime_audio_compressor (quicktime_t *file, int track)
| Get the four character code of an audio track.
int | quicktime_channel_location (quicktime_t *file, int *quicktime_track, int *quicktime_channel, int channel)
int | quicktime_set_audio_position (quicktime_t *file, int64_t sample, int track)
| Seek to a specific audio position.
int | quicktime_supported_audio (quicktime_t *file, int track)
| Check if an audio track is supported by libquicktime.
int | quicktime_decode_audio (quicktime_t *file, int16_t *output_i, float *output_f, long samples, int channel)
| Decode a number of audio samples of a single channel.
int | lqt_decode_audio (quicktime_t *file, int16_t **output_i, float **output_f, long samples)
| Decode all channels from all tracks at once.
int64_t | lqt_last_audio_position (quicktime_t *file, int track)
| Get the position of the last decoded sample.
int | lqt_decode_audio_track (quicktime_t *file, int16_t **output_i, float **output_f, long samples, int track)
| Decode a number of audio samples.
int | lqt_decode_audio_raw (quicktime_t *file, void *output, long samples, int track)
| Decode audio in the native sampleformat of the codec.
int | lqt_get_audio_language (quicktime_t *file, int track, char *language)
| Get the audio language.
int | lqt_total_channels (quicktime_t *file)
| Get the total number of audio channels across all tracks.

## Detailed Description

Audio related definitions and functions (reading).

The audio API changed a lot during the last years (causing lot of confusion), so here is the preferred way: First get the number of audio tracks with quicktime_audio_tracks. Then for each track you want to decode, use quicktime_supported_audio to verify that a codec is available. Then get the audio format with quicktime_track_channels and quicktime_sample_rate . Then use lqt_decode_audio_track to decode noninterleaved channels in either 16bit integer or floating point [-1.0..1.0] format. This method will convert all internally used formats to the datatypes you want, but won't output the full precision for 24/32 bit formats. If you want the samples as raw as possible (bypassing all internal sample format conversions), use lqt_get_sample_format to get the sampleformat natively used by the codec and lqt_decode_audio_raw to decode it.

## Function Documentation

long quicktime_audio_length | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the audio length.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The total number of uncompressed audio samples in the track

long quicktime_audio_position | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the audio position.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The number (starting with 0) of the next sample to be decoded.

int quicktime_audio_tracks | ( | quicktime_t * | file | ) |

Get the number of audio tracks.

Parameters:

  | file | A quicktime handle

Returns:
  The number of audio tracks

int quicktime_has_audio | ( | quicktime_t * | file | ) |

Check if a file has at least one audio track.

Parameters:

  | file | A quicktime handle

Returns:
  1 if the file has audio tracks, 0 else

long quicktime_sample_rate | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the samplerate of an audio track.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The samplerate in Hz

int quicktime_audio_bits | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the bits per sample of an audio track.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The bits per sample (typically 16)

Don't use this function for anything else than for informational purposes. Bits per sample is meaningless for compressed codecs, and sometimes plain wrong even for uncompressed ones.

To get some better informations about the resolution, a codec will deliver, use lqt_get_sample_format

int quicktime_track_channels | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the number of channels of an audio track.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The the number of channels

char* quicktime_audio_compressor | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the four character code of an audio track.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The four character code (fourcc) of the track.

Note, that this function might return nothing meaningful for AVI files, since AVI doesn't use four character codes for audio streams. To get more save information about the codec responsible for the stream, use lqt_audio_codec_from_file .

int quicktime_channel_location | ( | quicktime_t * | file,
|  | int * | quicktime_track,
|  | int * | quicktime_channel,
|  | int | channel |
| ) |  |  |

Parameters:

  | file | A quicktime handle
  | quicktime_track | Returns the index of the quicktime track
  | quicktime_channel | Returns the channel index inside the quicktime track
  | channel | The channel to query

Don't use this function (see lqt_decode_audio )

int quicktime_set_audio_position | ( | quicktime_t * | file,
|  | int64_t | sample,
|  | int | track |
| ) |  |  |

Seek to a specific audio position.

Parameters:

  | file | A quicktime handle
  | sample | The sample position (starting with 0)
  | track | index (starting with 0)

Use this for seeking. During sequential decode calls, the position will be updated automatically

int quicktime_supported_audio | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Check if an audio track is supported by libquicktime.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  1 if a codec for this track is available, 0 else

int quicktime_decode_audio | ( | quicktime_t * | file,
|  | int16_t * | output_i,
|  | float * | output_f,
|  | long | samples,
|  | int | channel |
| ) |  |  |

Decode a number of audio samples of a single channel.

Parameters:

  | file | A quicktime handle
  | output_i | 16 bit integer output buffer (or NULL)
  | output_f | floating point output buffer (or NULL)
  | samples | Number of samples to decode
  | channel | Channel to decode

Never use this function: Decoding only one channel at once causes lots of internal overhead if you need all channels anyway. In this case, lqt_decode_audio_track is the better choice. Furthermore, you won't be able to decode the full resolution for 24 and 32 bit codecs. To decode the maximum resolution, use lqt_decode_audio_raw.

The number of actually decoded samples (and EOF) can be obtained with lqt_last_audio_position

int lqt_decode_audio | ( | quicktime_t * | file,
|  | int16_t ** | output_i,
|  | float ** | output_f,
|  | long | samples |
| ) |  |  |

Decode all channels from all tracks at once.

Parameters:

  | file | A quicktime handle
  | output_i | 16 bit integer output buffer (or NULL)
  | output_f | floating point output buffer (or NULL)
  | samples | How many samples to decode

quicktime4linux hides the concept of multiple audio tracks from the user. The idea was probably to put an arbitrary number of channels into a file regardless of the codec (some codecs don't support more than 2 channels). So in principle, this function does the same as quicktime_decode_audio, but it grabs all channels at once. Or if you want only some channels you can leave the channels you don't want = NULL in the output array. The output arrays must contain at least lqt_total_channels(file) elements.

Libquicktime supports an arbitrary number of audio tracks, which can even have completely different formats and codecs. Therefore you should always use lqt_decode_audio_track or lqt_decode_audio_raw to decode audio from a particular track.

The number of actually decoded samples (and EOF) can be obtained with lqt_last_audio_position

int64_t lqt_last_audio_position | ( | quicktime_t * | file,
|  | int | track |
| ) |  |  |

Get the position of the last decoded sample.

Parameters:

  | file | A quicktime handle
  | track | index (starting with 0)

Returns:
  The position of the last decoded sample.

Returns the position of the last decoded sample. It is updated by the codec in each decode call and resembles the true position of the stream. Therefore, after each decode call, the last position should increment by the number of samples you decoded. If it's smaller, it means, that no more samples are available and that the end of the track is reached.

int lqt_decode_audio_track | ( | quicktime_t * | file,
|  | int16_t ** | output_i,
|  | float ** | output_f,
|  | long | samples,
|  | int | track |
| ) |  |  |

Decode a number of audio samples.

Parameters:

  | file | A quicktime handle
  | output_i | 16 bit integer output buffer (or NULL)
  | output_f | floating point output buffer (or NULL)
  | samples | Number of samples to decode
  | track | index (starting with 0)

Decode a number of samples from an audio track. All channels are decoded at once. output_i and output_f point to noninterleaved arrays for each channel. Depending on what you need, set either output_i or output_f to NULL. If you want the full resolution also for 24/32 bits, use lqt_decode_audio_raw .

The number of actually decoded samples (and EOF) can be obtained with lqt_last_audio_position

int lqt_decode_audio_raw | ( | quicktime_t * | file,
|  | void * | output,
|  | long | samples,
|  | int | track |
| ) |  |  |

Decode audio in the native sampleformat of the codec.

Parameters:

  | file | A quicktime handle
  | output | An array of interleaved samples
  | samples | Number of samples to decode
  | track | Track index (starting with 0)

Returns:
  The number of actually decoded samples. 0 means end of track.

This function bypasses all internal sampleformat conversion and allows full resolution output for up to 32 bit integer and 32 bit float. To check, which dataformat the samples will have, use lqt_get_sample_format .

The number of actually decoded samples (and EOF) can be obtained with lqt_last_audio_position

int lqt_get_audio_language | ( | quicktime_t * | file,
|  | int | track,
|  | char * | language |
| ) |  |  |

Get the audio language.

Parameters:

  | file | A quicktime handle
  | track | Track index (starting with 0)
  | language | Returns ISO-639 Language code

Returns:
  1 on success, 0 on error.

The language code is a 3-character code, English is "eng", Japanese is "jpn".

int lqt_total_channels | ( | quicktime_t * | file | ) |

Get the total number of audio channels across all tracks.

Parameters:

  | file | A quicktime handle

Returns:
  The total channel count

The result of this function is only meaningful in conjunction with lqt_decode_audio . In the general case, you should expect the audio tracks in the file as completely independent. Use quicktime_track_channels instead.