AVbin: avbin.h File Reference

- Main Page
- Data Structures
- Files

- File List
- Globals

# avbin.h File Reference

## Detailed Description

AVbin functions and structures.

## Data Structures
struct | _AVbinFileInfo
| File details. More...
struct | _AVbinStreamInfo
| Stream details. More...
struct | _AVbinPacket
| A single packet of stream data. More...
## Typedefs
typedef enum _AVbinResult | AVbinResult
| Error-checked function result.
typedef enum _AVbinStreamType | AVbinStreamType
| Type of a stream; currently only video and audio streams are supported.
typedef enum _AVbinSampleFormat | AVbinSampleFormat
| The sample format for audio data.
typedef enum _AVbinLogLevel | AVbinLogLevel
| Threshold of logging verbosity.
typedef _AVbinFile | AVbinFile
| Opaque open file handle.
typedef _AVbinStream | AVbinStream
| Opaque open stream handle.
typedef int64_t | AVbinTimestamp
| Point in time, or a time range; given in microseconds.
typedef _AVbinFileInfo | AVbinFileInfo
| File details.
typedef _AVbinStreamInfo | AVbinStreamInfo
| Stream details.
typedef _AVbinPacket | AVbinPacket
| A single packet of stream data.
typedef void(*) | AVbinLogCallback (const char *module, AVbinLogLevel level, const char *message)
| Callback for log information.
## Enumerations
enum | _AVbinResult { AVBIN_RESULT_ERROR = -1, AVBIN_RESULT_OK = 0 }
| Error-checked function result. More...
enum | _AVbinStreamType { AVBIN_STREAM_TYPE_UNKNOWN = 0, AVBIN_STREAM_TYPE_VIDEO = 1, AVBIN_STREAM_TYPE_AUDIO = 2 }
| Type of a stream; currently only video and audio streams are supported. More...
enum | _AVbinSampleFormat { AVBIN_SAMPLE_FORMAT_U8 = 0, AVBIN_SAMPLE_FORMAT_S16 = 1, AVBIN_SAMPLE_FORMAT_S24 = 2, AVBIN_SAMPLE_FORMAT_S32 = 3, AVBIN_SAMPLE_FORMAT_FLOAT = 4 }
| The sample format for audio data. More...
enum | _AVbinLogLevel { AVBIN_LOG_QUIET = -8, AVBIN_LOG_PANIC = 0, AVBIN_LOG_FATAL = 8, AVBIN_LOG_ERROR = 16, AVBIN_LOG_WARNING = 24, AVBIN_LOG_INFO = 32, AVBIN_LOG_VERBOSE = 40, AVBIN_LOG_DEBUG = 48 }
| Threshold of logging verbosity. More...
## Functions
Information about AVbin
int | avbin_get_version ()
| Get the linked version of AVbin.
int | avbin_get_ffmpeg_revision ()
| Get the SVN revision of FFmpeg.
size_t | avbin_get_audio_buffer_size ()
| Get the minimum audio buffer size, in bytes.
int | avbin_have_feature (const char *feature)
| Determine if AVbin includes a requested feature.
Global AVbin functions
AVbinResult | avbin_init ()
| Initialise AVbin.
AVbinResult | avbin_set_log_level (AVbinLogLevel level)
| Set the log level verbosity.
AVbinResult | avbin_set_log_callback (AVbinLogCallback callback)
| Set a custom log callback.
File handling functions
AVbinFile * | avbin_open_filename (const char *filename)
| Open a media file given its filename.
void | avbin_close_file (AVbinFile *file)
| Close a media file.
AVbinResult | avbin_seek_file (AVbinFile *file, AVbinTimestamp timestamp)
| Seek to a timestamp within a file.
AVbinResult | avbin_file_info (AVbinFile *file, AVbinFileInfo *info)
| Get information about the opened file.
Stream functions
AVbinResult | avbin_stream_info (AVbinFile *file, int stream_index, AVbinStreamInfo *info)
| Get information about a stream within the file.
AVbinStream * | avbin_open_stream (AVbinFile *file, int stream_index)
| Open a stream for decoding.
void | avbin_close_stream (AVbinStream *stream)
| Close a file stream.
Reading and decoding functions
AVbinResult | avbin_read (AVbinFile *file, AVbinPacket *packet)
| Read a packet from the file.
int | avbin_decode_audio (AVbinStream *stream, uint8_t *data_in, size_t size_in, uint8_t *data_out, int *size_out)
| Decode some audio data.
int | avbin_decode_video (AVbinStream *stream, uint8_t *data_in, size_t size_in, uint8_t *data_out)
| Decode a video frame image.

## Typedef Documentation

typedef struct _AVbinFile AVbinFile

Opaque open file handle.

typedef struct _AVbinFileInfo AVbinFileInfo

File details.

The info struct is filled in by avbin_get_file_info.

typedef void(*) AVbinLogCallback(const char *module, AVbinLogLevel level, const char *message)

Callback for log information.

Parameters:

  | module | The name of the module where this message originated
  | level | The log verbosity level of this message
  | message | The formatted message. The message may or may not contain newline characters.

typedef enum _AVbinLogLevel AVbinLogLevel

Threshold of logging verbosity.

typedef struct _AVbinPacket AVbinPacket

A single packet of stream data.

The structure size must be initialised before passing to avbin_read. The data will point to a block of memory allocated by AVbin -- you must not free it. The data will be valid until the next time you call avbin_read, or until the file is closed.

typedef enum _AVbinResult AVbinResult

Error-checked function result.

typedef enum _AVbinSampleFormat AVbinSampleFormat

The sample format for audio data.

typedef struct _AVbinStream AVbinStream

Opaque open stream handle.

typedef struct _AVbinStreamInfo AVbinStreamInfo

Stream details.

A stream is a single audio track or video. Most audio files contain one audio stream. Most video files contain one audio stream and one video stream. More than one audio stream may indicate the presence of multiple languages which can be selected (however at this time AVbin does not provide language information).

typedef enum _AVbinStreamType AVbinStreamType

Type of a stream; currently only video and audio streams are supported.

typedef int64_t AVbinTimestamp

Point in time, or a time range; given in microseconds.

## Enumeration Type Documentation

enum _AVbinLogLevel

Threshold of logging verbosity.

Enumerator:

  AVBIN_LOG_QUIET |
  AVBIN_LOG_PANIC |
  AVBIN_LOG_FATAL |
  AVBIN_LOG_ERROR |
  AVBIN_LOG_WARNING |
  AVBIN_LOG_INFO |
  AVBIN_LOG_VERBOSE |
  AVBIN_LOG_DEBUG |

enum _AVbinResult

Error-checked function result.

Enumerator:

  AVBIN_RESULT_ERROR |
  AVBIN_RESULT_OK |

enum _AVbinSampleFormat

The sample format for audio data.

Enumerator:

  AVBIN_SAMPLE_FORMAT_U8 | Unsigned byte.
  AVBIN_SAMPLE_FORMAT_S16 | Signed 16-bit integer.
  AVBIN_SAMPLE_FORMAT_S24 | Signed 24-bit integer.
  AVBIN_SAMPLE_FORMAT_S32 | Signed 32-bit integer.
  AVBIN_SAMPLE_FORMAT_FLOAT | 32-bit IEEE floating-point

enum _AVbinStreamType

Type of a stream; currently only video and audio streams are supported.

Enumerator:

  AVBIN_STREAM_TYPE_UNKNOWN |
  AVBIN_STREAM_TYPE_VIDEO |
  AVBIN_STREAM_TYPE_AUDIO |

## Function Documentation

void avbin_close_file | ( | AVbinFile * | file | ) |

Close a media file.

void avbin_close_stream | ( | AVbinStream * | stream | ) |

Close a file stream.

int avbin_decode_audio | ( | AVbinStream * | stream,
|  | uint8_t * | data_in,
|  | size_t | size_in,
|  | uint8_t * | data_out,
|  | int * | size_out |
| ) |  |  |

Decode some audio data.

You must ensure that data_out is at least as big as the minimum audio buffer size (see avbin_get_audio_buffer_size()).

Parameters:

  `[in]` | stream | The stream to decode.
  `[in]` | data_in | Incoming data, as read from a packet
  `[in]` | size_in | Size of data_in, in bytes
  `[out]` | data_out | Decoded audio data buffer, provided by application
  `[out]` | size_out | Number of bytes of data_out used.

Returns:
  the number of bytes of data_in actually used. You should call this function repeatedly as long as the return value is greater than 0.

Return values:

  | -1 | if there was an error

int avbin_decode_video | ( | AVbinStream * | stream,
|  | uint8_t * | data_in,
|  | size_t | size_in,
|  | uint8_t * | data_out |
| ) |  |  |

Decode a video frame image.

The size of data_out must be large enough to hold the entire image. This is width * height * 3 (images are always in 8-bit RGB format).

Parameters:

  `[in]` | stream | The stream to decode.
  `[in]` | data_in | Incoming data, as read from a packet
  `[in]` | size_in | Size of data_in, in bytes
  `[out]` | data_out | Decoded image data.

Returns:
  the number of bytes of data_in actually used. Any remaining bytes can be discarded.

Return values:

  | -1 | if there was an error

AVbinResult avbin_file_info | ( | AVbinFile * | file,
|  | AVbinFileInfo * | info |
| ) |  |  |

Get information about the opened file.

The info struct must be allocated by the application and have its structure_size member filled in correctly. On return, the structure will be filled with file details.

size_t avbin_get_audio_buffer_size | ( |  | ) |

Get the minimum audio buffer size, in bytes.

int avbin_get_ffmpeg_revision | ( |  | ) |

Get the SVN revision of FFmpeg.

This is built into AVbin as it is built.

int avbin_get_version | ( |  | ) |

Get the linked version of AVbin.

Version numbers are always integer, there are no "minor" or "patch" revisions. All AVbin versions are backward and forward compatible, modulo the required feature set.

int avbin_have_feature | ( | const char * | feature | ) |

Determine if AVbin includes a requested feature.

When future versions of AVbin include more functionality, that functionality can be tested for by calling this function. Currently there are no features to test for.

Return values:

  | 1 | The feature is present
  | 0 | The feature is not present

AVbinResult avbin_init | ( |  | ) |

Initialise AVbin.

This must be called before opening a file. Check the return value for success before continuing.

AVbinFile* avbin_open_filename | ( | const char * | filename | ) |

Open a media file given its filename.

Return values:

  | NULL | if the file could not be opened, or is not of a recognised file format.

AVbinStream* avbin_open_stream | ( | AVbinFile * | file,
|  | int | stream_index |
| ) |  |  |

Open a stream for decoding.

If you intend to decode audio or video from a file, you must open the stream first. The returned opaque handle should be passed to the relevant decode function when a packet for that stream is read.

AVbinResult avbin_read | ( | AVbinFile * | file,
|  | AVbinPacket * | packet |
| ) |  |  |

Read a packet from the file.

The packet struct must be allocated by the application and have its structure_size member filled in correctly. On return, the structure will be filled with a packet of data. The actual data pointer within the packet must not be freed, and is valid until the next call to avbin_read.

Applications should examine the packet's stream index to match it with an appropriate open stream handle, or discard it if none match. The packet data can then be passed to the relevant decode function.

AVbinResult avbin_seek_file | ( | AVbinFile * | file,
|  | AVbinTimestamp | timestamp |
| ) |  |  |

Seek to a timestamp within a file.

For video files, the first keyframe before the requested timestamp will be seeked to. For audio files, the first audio packet before the requested timestamp is used.

AVbinResult avbin_set_log_callback | ( | AVbinLogCallback | callback | ) |

Set a custom log callback.

By default, log messages are printed to standard error. Providing a NULL callback restores this default handler.

AVbinResult avbin_set_log_level | ( | AVbinLogLevel | level | ) |

Set the log level verbosity.

AVbinResult avbin_stream_info | ( | AVbinFile * | file,
|  | int | stream_index,
|  | AVbinStreamInfo * | info |
| ) |  |  |

Get information about a stream within the file.

The info struct must be allocated by the application and have its structure_size member filled in correctly. On return, the structure will be filled with stream details.

Ensure that stream_index is less than n_streams given in the file info.

Parameters:

  `[in]` | file | The file to examine
  `[in]` | stream_index | The number of the stream within the file
  `[out]` | info | Returned stream information