gstriff

## gstriff gstriff — Riff fileformat utillity functions. |

## Synopsis

    #include <gst/riff/riff-media.h>

    GstCaps *           gst_riff_create_audio_caps          (guint16 codec_id,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_auds *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);
    GstCaps *           gst_riff_create_audio_template_caps (void);
    GstCaps *           gst_riff_create_iavs_caps           (guint32 codec_fcc,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_iavs *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);
    GstCaps *           gst_riff_create_iavs_template_caps  (void);
    GstCaps *           gst_riff_create_video_caps          (guint32 codec_fcc,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_vids *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);
    GstCaps *           gst_riff_create_video_template_caps (void);
    void                gst_riff_init                       (void);
    gboolean            gst_riff_parse_chunk                (GstElement *element,
                                                             GstBuffer *buf,
                                                             guint *offset,
                                                             guint32 *fourcc,
                                                             GstBuffer **chunk_data);
    gboolean            gst_riff_parse_file_header          (GstElement *element,
                                                             GstBuffer *buf,
                                                             guint32 *doctype);
    void                gst_riff_parse_info                 (GstElement *element,
                                                             GstBuffer *buf,
                                                             GstTagList **taglist);
    gboolean            gst_riff_parse_strf_auds            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_auds **strf,
                                                             GstBuffer **data);
    gboolean            gst_riff_parse_strf_iavs            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_iavs **strf,
                                                             GstBuffer **data);
    gboolean            gst_riff_parse_strf_vids            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_vids **strf,
                                                             GstBuffer **data);
    gboolean            gst_riff_parse_strh                 (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strh **strh);
    GstFlowReturn       gst_riff_read_chunk                 (GstElement *element,
                                                             GstPad *pad,
                                                             guint64 *offset,
                                                             guint32 *tag,
                                                             GstBuffer **chunk_data);

## Description

A collection of functions to handle riff base files, such as avi, wav and asf.

## Details

### gst_riff_create_audio_caps ()

    GstCaps *           gst_riff_create_audio_caps          (guint16 codec_id,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_auds *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);

### gst_riff_create_audio_template_caps ()

    GstCaps *           gst_riff_create_audio_template_caps (void);

### gst_riff_create_iavs_caps ()

    GstCaps *           gst_riff_create_iavs_caps           (guint32 codec_fcc,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_iavs *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);

### gst_riff_create_iavs_template_caps ()

    GstCaps *           gst_riff_create_iavs_template_caps  (void);

### gst_riff_create_video_caps ()

    GstCaps *           gst_riff_create_video_caps          (guint32 codec_fcc,
                                                             gst_riff_strh *strh,
                                                             gst_riff_strf_vids *strf,
                                                             GstBuffer *strf_data,
                                                             GstBuffer *strd_data,
                                                             char **codec_name);

`codec_fcc` : | fourCC codec for this codec.
`strh` : | pointer to the strh stream header structure.
`strf` : | pointer to the strf stream header structure, including any data that is within the range of strf.size, but excluding any additional data withint this chunk but outside strf.size.
`strf_data` : | a GstBuffer containing the additional data in the strf chunk outside reach of strf.size. Ususally a palette.
`strd_data` : | a GstBuffer containing the data in the strd stream header chunk. Usually codec initialization data.
`codec_name` : | if given, will be filled with a human-readable codec name.

### gst_riff_create_video_template_caps ()

    GstCaps *           gst_riff_create_video_template_caps (void);

### gst_riff_init ()

    void                gst_riff_init                       (void);

Initialize riff library.

### gst_riff_parse_chunk ()

    gboolean            gst_riff_parse_chunk                (GstElement *element,
                                                             GstBuffer *buf,
                                                             guint *offset,
                                                             guint32 *fourcc,
                                                             GstBuffer **chunk_data);

Reads a single chunk.

`element` : | caller element (used for debugging).
`buf` : | input buffer.
`offset` : | offset in the buffer in the caller. Is incremented by the read size by this function.
`fourcc` : | fourcc (returned by this function0 of the chunk.
`chunk_data` : | buffer (returned by the function) containing the chunk data, which may be NULL if chunksize == 0
Returns : | FALSE on error, TRUE otherwise

### gst_riff_parse_file_header ()

    gboolean            gst_riff_parse_file_header          (GstElement *element,
                                                             GstBuffer *buf,
                                                             guint32 *doctype);

Reads the first few bytes from the provided buffer, checks if this stream is a RIFF stream, and determines document type. This function takes ownership of `buf` so it should not be used anymore after calling this function.

`element` : | caller element (used for debugging/error).
`buf` : | input buffer from which the file header will be parsed, should be at least 12 bytes long.
`doctype` : | a fourcc (returned by this function) to indicate the type of document (according to the header).
Returns : | FALSE if this is not a RIFF stream (in which case the caller should error out; we already throw an error), or TRUE if it is.

### gst_riff_parse_info ()

    void                gst_riff_parse_info                 (GstElement *element,
                                                             GstBuffer *buf,
                                                             GstTagList **taglist);

Parses stream metadata from input data.

`element` : | caller element (used for debugging/error).
`buf` : | input data to be used for parsing, stripped from header.
`taglist` : | a pointer to a taglist (returned by this function) containing information about this stream. May be NULL if no supported tags were found.

### gst_riff_parse_strf_auds ()

    gboolean            gst_riff_parse_strf_auds            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_auds **strf,
                                                             GstBuffer **data);

Parses an audio stream´s strf structure plus optionally some extradata from input data. This function takes ownership of `buf`. use.

`element` : | caller element (used for debugging/error).
`buf` : | input data to be used for parsing, stripped from header.
`strf` : | a pointer (returned by this function) to a filled-in strf/auds structure. Caller should free it.
`data` : | a pointer (returned by this function) to a buffer containing extradata for this particular stream (e.g. codec initialization data).
Returns : | TRUE if parsing succeeded, otherwise FALSE. The stream should be skipped on error, but it is not fatal.

### gst_riff_parse_strf_iavs ()

    gboolean            gst_riff_parse_strf_iavs            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_iavs **strf,
                                                             GstBuffer **data);

Parses a interleaved (also known as "complex") stream´s strf structure plus optionally some extradata from input data. This function takes ownership of `buf`.

`element` : | caller element (used for debugging/error).
`buf` : | input data to be used for parsing, stripped from header.
`strf` : | a pointer (returned by this function) to a filled-in strf/iavs structure. Caller should free it.
`data` : | a pointer (returned by this function) to a buffer containing extradata for this particular stream (e.g. codec initialization data).
Returns : | TRUE if parsing succeeded, otherwise FALSE.

### gst_riff_parse_strf_vids ()

    gboolean            gst_riff_parse_strf_vids            (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strf_vids **strf,
                                                             GstBuffer **data);

Parses a video stream´s strf structure plus optionally some extradata from input data. This function takes ownership of `buf`.

`element` : | caller element (used for debugging/error).
`buf` : | input data to be used for parsing, stripped from header.
`strf` : | a pointer (returned by this function) to a filled-in strf/vids structure. Caller should free it.
`data` : | a pointer (returned by this function) to a buffer containing extradata for this particular stream (e.g. palette, codec initialization data).
Returns : | TRUE if parsing succeeded, otherwise FALSE. The stream should be skipped on error, but it is not fatal.

### gst_riff_parse_strh ()

    gboolean            gst_riff_parse_strh                 (GstElement *element,
                                                             GstBuffer *buf,
                                                             gst_riff_strh **strh);

Parses a strh structure from input data. Takes ownership of `buf`.

`element` : | caller element (used for debugging/error).
`buf` : | input data to be used for parsing, stripped from header.
`strh` : | a pointer (returned by this function) to a filled-in strh structure. Caller should free it.
Returns : | TRUE if parsing succeeded, otherwise FALSE. The stream should be skipped on error, but it is not fatal.

### gst_riff_read_chunk ()

    GstFlowReturn       gst_riff_read_chunk                 (GstElement *element,
                                                             GstPad *pad,
                                                             guint64 *offset,
                                                             guint32 *tag,
                                                             GstBuffer **chunk_data);

Reads a single chunk of data. Since 0.10.8 'JUNK' chunks are skipped automatically.

`element` : | caller element (used for debugging).
`pad` : | pad to pull data from.
`offset` : | offset to pull from, incremented by this function.
`tag` : | fourcc of the chunk (returned by this function).
`chunk_data` : | buffer (returned by this function).
Returns : | flow status.