## GstVideo Ancillary

GstVideo Ancillary — Utilities for Ancillary data, VBI and Closed Caption

## Functions

#define | GST_VIDEO_ANCILLARY_DID16()
GstVideoVBIParser * | gst_video_vbi_parser_new ()
void | gst_video_vbi_parser_free ()
void | gst_video_vbi_parser_add_line ()
GstVideoVBIParserResult | gst_video_vbi_parser_get_ancillary ()
GstVideoVBIParser * | gst_video_vbi_parser_copy ()
GstVideoVBIEncoder * | gst_video_vbi_encoder_new ()
void | gst_video_vbi_encoder_free ()
gboolean | gst_video_vbi_encoder_add_ancillary ()
void | gst_video_vbi_encoder_write_line ()
GstVideoVBIEncoder * | gst_video_vbi_encoder_copy ()
#define | gst_buffer_get_video_caption_meta()
GstVideoCaptionMeta * | gst_buffer_add_video_caption_meta ()
GstVideoCaptionType | gst_video_caption_type_from_caps ()
GstCaps * | gst_video_caption_type_to_caps ()

## Types and Values

struct | GstVideoAncillary
enum | GstVideoAncillaryDID
enum | GstVideoAncillaryDID16
| GstVideoVBIParser
enum | GstVideoVBIParserResult
| GstVideoVBIEncoder
enum | GstVideoCaptionType
| GstVideoCaptionMeta

## Includes

    #include <gst/video/video.h>

## Description

A collection of objects and methods to assist with handling Ancillary Data present in Vertical Blanking Interval as well as Closed Caption.

## Functions

### GST_VIDEO_ANCILLARY_DID16()

    #define GST_VIDEO_ANCILLARY_DID16(anc) ((guint16)((anc)->DID) << 8 | (guint16)((anc)->SDID_block_number))

Returns the GstVideoAncillaryDID16 of the ancillary data.

#### Parameters

anc | a GstVideoAncillary |

#### Returns

a GstVideoAncillaryDID16 identifier

Since: 1.16

### gst_video_vbi_parser_new ()

    GstVideoVBIParser *
    gst_video_vbi_parser_new (GstVideoFormat format,
                              guint32 pixel_width);

Create a new GstVideoVBIParser for the specified `format` and `pixel_width` .

#### Parameters

format | a GstVideoFormat |
pixel_width | The width in pixel to use |

#### Returns

The new GstVideoVBIParser or `NULL` if the `format` and/or `pixel_width` is not supported.

Since: 1.16

### gst_video_vbi_parser_free ()

    void
    gst_video_vbi_parser_free (GstVideoVBIParser *parser);

Frees the `parser` .

#### Parameters

parser | a GstVideoVBIParser |

Since: 1.16

### gst_video_vbi_parser_add_line ()

    void
    gst_video_vbi_parser_add_line (GstVideoVBIParser *parser,
                                   const guint8 *data);

Provide a new line of data to the `parser` . Call `gst_video_vbi_parser_get_ancillary()` to get the Ancillary data that might be present on that line.

#### Parameters

parser | a GstVideoVBIParser |
data | The line of data to parse. | [array][transfer none]

Since: 1.16

### gst_video_vbi_parser_get_ancillary ()

    GstVideoVBIParserResult
    gst_video_vbi_parser_get_ancillary (GstVideoVBIParser *parser,
                                        GstVideoAncillary *anc);

Parse the line provided previously by `gst_video_vbi_parser_add_line()`.

#### Parameters

parser | a GstVideoVBIParser |
anc | a GstVideoAncillary to start the eventual ancillary data. | [out caller-allocates]

#### Returns

`GST_VIDEO_VBI_PARSER_RESULT_OK` if ancillary data was found and `anc` was filled. `GST_VIDEO_VBI_PARSER_RESULT_DONE` if there wasn't any data.

Since: 1.16

### gst_video_vbi_parser_copy ()

    GstVideoVBIParser *
    gst_video_vbi_parser_copy (const GstVideoVBIParser *parser);

### gst_video_vbi_encoder_new ()

    GstVideoVBIEncoder *
    gst_video_vbi_encoder_new (GstVideoFormat format,
                               guint32 pixel_width);

Create a new GstVideoVBIEncoder for the specified `format` and `pixel_width` .

#### Parameters

format | a GstVideoFormat |
pixel_width | The width in pixel to use |

#### Returns

The new GstVideoVBIEncoder or `NULL` if the `format` and/or `pixel_width` is not supported.

Since: 1.16

### gst_video_vbi_encoder_free ()

    void
    gst_video_vbi_encoder_free (GstVideoVBIEncoder *encoder);

Frees the `encoder` .

#### Parameters

encoder | a GstVideoVBIEncoder |

Since: 1.16

### gst_video_vbi_encoder_add_ancillary ()

    gboolean
    gst_video_vbi_encoder_add_ancillary (GstVideoVBIEncoder *encoder,
                                         gboolean composite,
                                         guint8 DID,
                                         guint8 SDID_block_number,
                                         const guint8 *data,
                                         guint data_count);

Stores Video Ancillary data, according to SMPTE-291M specification.

Note that the contents of the data are always read as 8bit data (i.e. do not contain the parity check bits).

#### Parameters

encoder | a GstVideoVBIEncoder |
composite | `TRUE` if composite ADF should be created, component otherwise |
DID | The Data Identifier |
SDID_block_number | The Secondary Data Identifier (if type 2) or the Data Block Number (if type 1) |
data_count | The amount of data (in bytes) in `data` (max 255 bytes) |
data | The user data content of the Ancillary packet. Does not contain the ADF, DID, SDID nor CS. | [array length=data_count]

#### Returns

`TRUE` if enough space was left in the current line, `FALSE` otherwise.

Since: 1.16

### gst_video_vbi_encoder_write_line ()

    void
    gst_video_vbi_encoder_write_line (GstVideoVBIEncoder *encoder,
                                      guint8 *data);

### gst_video_vbi_encoder_copy ()

    GstVideoVBIEncoder *
    gst_video_vbi_encoder_copy (const GstVideoVBIEncoder *encoder);

### gst_buffer_get_video_caption_meta()

    #define             gst_buffer_get_video_caption_meta(b)

Gets the GstVideoCaptionMeta that might be present on `b` .

#### Parameters

b | A GstBuffer |

#### Returns

The first GstVideoCaptionMeta present on `b` , or `NULL` if no GstVideoCaptionMeta are present

Since: 1.16

### gst_buffer_add_video_caption_meta ()

    GstVideoCaptionMeta *
    gst_buffer_add_video_caption_meta (GstBuffer *buffer,
                                       GstVideoCaptionType caption_type,
                                       const guint8 *data,
                                       gsize size);

Attaches GstVideoCaptionMeta metadata to `buffer` with the given parameters.

#### Parameters

buffer | a GstBuffer |
caption_type | The type of Closed Caption to add |
data | The Closed Caption data. | [array length=size][transfer none]
size | The size of `data` in bytes |

#### Returns

the GstVideoCaptionMeta on `buffer` .

[transfer none]

Since: 1.16

### gst_video_caption_type_from_caps ()

    GstVideoCaptionType
    gst_video_caption_type_from_caps (const GstCaps *caps);

Parses fixed Closed Caption GstCaps and returns the corresponding caption type, or `GST_VIDEO_CAPTION_TYPE_UNKNOWN`.

#### Parameters

caps | Fixed GstCaps to parse |

#### Returns

GstVideoCaptionType.

Since: 1.16

### gst_video_caption_type_to_caps ()

    GstCaps *
    gst_video_caption_type_to_caps (GstVideoCaptionType type);

Creates new caps corresponding to `type` .

#### Parameters

type | GstVideoCaptionType |

#### Returns

new GstCaps.

[transfer full]

Since: 1.16

## Types and Values

### struct GstVideoAncillary

    struct GstVideoAncillary {
      guint8 DID;
      guint8 SDID_block_number;
      guint8 data_count;
      guint8 data[256];
    };

Video Ancillary data, according to SMPTE-291M specification.

Note that the contents of the data are always stored as 8bit data (i.e. do not contain the parity check bits).

#### Members

guint8 `DID`; | The Data Identifier |
guint8 `SDID_block_number`; | The Secondary Data Identifier (if type 2) or the Data Block Number (if type 1) |
guint8 `data_count`; | The amount of data (in bytes) in `data` (max 255 bytes) |
guint8 `data`[256]; | The user data content of the Ancillary packet. Does not contain the ADF, DID, SDID nor CS. | [array length=data_count]

Since: 1.16

### enum GstVideoAncillaryDID

#### Members

GST_VIDEO_ANCILLARY_DID_UNDEFINED |  |
GST_VIDEO_ANCILLARY_DID_DELETION |  |
GST_VIDEO_ANCILLARY_DID_HANC_3G_AUDIO_DATA_FIRST |  |
GST_VIDEO_ANCILLARY_DID_HANC_3G_AUDIO_DATA_LAST |  |
GST_VIDEO_ANCILLARY_DID_HANC_HDTV_AUDIO_DATA_FIRST |  |
GST_VIDEO_ANCILLARY_DID_HANC_HDTV_AUDIO_DATA_LAST |  |
GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_1_FIRST |  |
GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_1_LAST |  |
GST_VIDEO_ANCILLARY_DID_CAMERA_POSITION |  |
GST_VIDEO_ANCILLARY_DID_HANC_ERROR_DETECTION |  |
GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_2_FIRST |  |
GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_2_LAST |  |

Since: 1.16

### enum GstVideoAncillaryDID16

Some know types of Ancillary Data identifiers.

#### Members

GST_VIDEO_ANCILLARY_DID16_S334_EIA_708 | CEA 708 Ancillary data according to SMPTE 334 |
GST_VIDEO_ANCILLARY_DID16_S334_EIA_608 | CEA 608 Ancillary data according to SMPTE 334 |
GST_VIDEO_ANCILLARY_DID16_S2016_3_AFD_BAR | AFD/Bar Ancillary data according to SMPTE 2016-3 (Since: 1.18) |

Since: 1.16

### GstVideoVBIParser

    typedef struct _GstVideoVBIParser GstVideoVBIParser;

A parser for detecting and extracting `GstVideoAncillary` data from Vertical Blanking Interval lines of component signals.

Since: 1.16

### enum GstVideoVBIParserResult

Return values for GstVideoVBIParser

#### Members

GST_VIDEO_VBI_PARSER_RESULT_DONE | No line were provided, or no more Ancillary data was found. |
GST_VIDEO_VBI_PARSER_RESULT_OK | A GstVideoAncillary was found. |
GST_VIDEO_VBI_PARSER_RESULT_ERROR | An error occured |

Since: 1.16

### GstVideoVBIEncoder

    typedef struct _GstVideoVBIEncoder GstVideoVBIEncoder;

An encoder for writing ancillary data to the Vertical Blanking Interval lines of component signals.

Since: 1.16

### enum GstVideoCaptionType

The various known types of Closed Caption (CC).

#### Members

GST_VIDEO_CAPTION_TYPE_UNKNOWN | Unknown type of CC |

GST_VIDEO_CAPTION_TYPE_CEA608_RAW

CEA-608 as byte pairs. Note that this format is not recommended since is does not specify to which field the caption comes from and therefore assumes it comes from the first field (and that there is no information on the second field). Use `GST_VIDEO_CAPTION_TYPE_CEA708_RAW` if you wish to store CEA-608 from two fields and prefix each byte pair with 0xFC for the first field and 0xFD for the second field.

GST_VIDEO_CAPTION_TYPE_CEA608_S334_1A

CEA-608 as byte triplets as defined in SMPTE S334-1 Annex A. The second and third byte of the byte triplet is the raw CEA608 data, the first byte is a bitfield: The top/7th bit is 0 for the second field, 1 for the first field, bit 6 and 5 are 0 and bits 4 to 0 are a 5 bit unsigned integer that represents the line offset relative to the base-line of the original image format (line 9 for 525-line field 1, line 272 for 525-line field 2, line 5 for 625-line field 1 and line 318 for 625-line field 2).

GST_VIDEO_CAPTION_TYPE_CEA708_RAW | CEA-708 as cc_data byte triplets. They can also contain 608-in-708 and the first byte of each triplet has to be inspected for detecting the type. |
GST_VIDEO_CAPTION_TYPE_CEA708_CDP | CEA-708 (and optionally CEA-608) in a CDP (Caption Distribution Packet) defined by SMPTE S-334-2. Contains the whole CDP (starting with 0x9669). |

Since: 1.16

### GstVideoCaptionMeta

    typedef struct {
      GstMeta meta;

      GstVideoCaptionType caption_type;
      guint8 *data;
      gsize size;
    } GstVideoCaptionMeta;

Extra buffer metadata providing Closed Caption.

#### Members

GstMeta `meta`; | parent GstMeta |
GstVideoCaptionType `caption_type`; | The type of Closed Caption contained in the meta. |
guint8 *`data`; | The Closed Caption data. | [array length=size]
gsize `size`; | The size in bytes of `data` |

Since: 1.16