## mpegvideoparser

mpegvideoparser — Convenience library for mpeg1 and 2 video bitstream parsing.

## Synopsis

    #include <gst/codecparsers/gstmpegvideoparser.h>

    enum                GstMpegVideoPacketTypeCode;
    enum                GstMpegVideoPacketExtensionCode;
    enum                GstMpegVideoLevel;
    enum                GstMpegVideoProfile;
    enum                GstMpegVideoPictureType;
    enum                GstMpegVideoPictureStructure;
    struct              GstMpegVideoSequenceHdr;
    struct              GstMpegVideoSequenceExt;
    struct              GstMpegVideoPictureHdr;
    struct              GstMpegVideoGop;
    struct              GstMpegVideoPictureExt;
    struct              GstMpegVideoQuantMatrixExt;
    gboolean            gst_mpeg_video_parse                (GstMpegVideoPacket *packet,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_sequence_header
                                                            (GstMpegVideoSequenceHdr *seqhdr,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_picture_header (GstMpegVideoPictureHdr *hdr,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_picture_extension
                                                            (GstMpegVideoPictureExt *ext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_gop            (GstMpegVideoGop *gop,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_sequence_extension
                                                            (GstMpegVideoSequenceExt *seqext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_sequence_display_extension
                                                            (GstMpegVideoSequenceDisplayExt *seqdisplayext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_parse_quant_matrix_extension
                                                            (GstMpegVideoQuantMatrixExt *quant,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);
    gboolean            gst_mpeg_video_finalise_mpeg2_sequence_header
                                                            (GstMpegVideoSequenceHdr *hdr,
                                                             GstMpegVideoSequenceExt *seqext,
                                                             GstMpegVideoSequenceDisplayExt *displayext);
    void                gst_mpeg_video_quant_matrix_get_raster_from_zigzag
                                                            (guint8 out_quant[64],
                                                             const guint8 quant[64]);
    void                gst_mpeg_video_quant_matrix_get_zigzag_from_raster
                                                            (guint8 out_quant[64],
                                                             const guint8 quant[64]);

## Description

Provides useful functions for mpeg videos bitstream parsing.

## Details

### enum GstMpegVideoPacketTypeCode

    typedef enum {
      GST_MPEG_VIDEO_PACKET_PICTURE      = 0x00,
      GST_MPEG_VIDEO_PACKET_SLICE_MIN    = 0x01,
      GST_MPEG_VIDEO_PACKET_SLICE_MAX    = 0xaf,
      GST_MPEG_VIDEO_PACKET_USER_DATA    = 0xb2,
      GST_MPEG_VIDEO_PACKET_SEQUENCE     = 0xb3,
      GST_MPEG_VIDEO_PACKET_EXTENSION    = 0xb5,
      GST_MPEG_VIDEO_PACKET_SEQUENCE_END = 0xb7,
      GST_MPEG_VIDEO_PACKET_GOP          = 0xb8,
      GST_MPEG_VIDEO_PACKET_NONE         = 0xff
    } GstMpegVideoPacketTypeCode;

Indicates the type of MPEG packet

`GST_MPEG_VIDEO_PACKET_PICTURE` | Picture packet starting code
`GST_MPEG_VIDEO_PACKET_SLICE_MIN` | Slice min packet starting code
`GST_MPEG_VIDEO_PACKET_SLICE_MAX` | Slice max packet starting code
`GST_MPEG_VIDEO_PACKET_USER_DATA` | User data packet starting code
`GST_MPEG_VIDEO_PACKET_SEQUENCE` | Sequence packet starting code
`GST_MPEG_VIDEO_PACKET_EXTENSION` | Extension packet starting code
`GST_MPEG_VIDEO_PACKET_SEQUENCE_END` | Sequence end packet code
`GST_MPEG_VIDEO_PACKET_GOP` | Group of Picture packet starting code
`GST_MPEG_VIDEO_PACKET_NONE` | None packet code

### enum GstMpegVideoPacketExtensionCode

    typedef enum {
      GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE          = 0x01,
      GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_DISPLAY  = 0x02,
      GST_MPEG_VIDEO_PACKET_EXT_QUANT_MATRIX      = 0x03,
      GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_SCALABLE = 0x05,
      GST_MPEG_VIDEO_PACKET_EXT_PICTURE           = 0x08
    } GstMpegVideoPacketExtensionCode;

Indicates what type of packets are in this block, some are mutually exclusive though - ie, sequence packs are accumulated separately. GOP & Picture may occur together or separately.

`GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE` | Sequence extension code
`GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_DISPLAY` | Sequence Display extension code
`GST_MPEG_VIDEO_PACKET_EXT_QUANT_MATRIX` | Quantization Matrix extension code
`GST_MPEG_VIDEO_PACKET_EXT_SEQUENCE_SCALABLE` | Sequence Scalable extension code
`GST_MPEG_VIDEO_PACKET_EXT_PICTURE` | Picture coding extension

### enum GstMpegVideoLevel

    typedef enum {
     GST_MPEG_VIDEO_LEVEL_HIGH      = 0x04,
     GST_MPEG_VIDEO_LEVEL_HIGH_1440 = 0x06,
     GST_MPEG_VIDEO_LEVEL_MAIN      = 0x08,
     GST_MPEG_VIDEO_LEVEL_LOW       = 0x0a
    } GstMpegVideoLevel;

Mpeg-2 Levels.

`GST_MPEG_VIDEO_LEVEL_HIGH` | High level (HL)
`GST_MPEG_VIDEO_LEVEL_HIGH_1440` | High 1440 level (H-14)
`GST_MPEG_VIDEO_LEVEL_MAIN` | Main level (ML)
`GST_MPEG_VIDEO_LEVEL_LOW` | Low level (LL)

### enum GstMpegVideoProfile

    typedef enum {
      GST_MPEG_VIDEO_PROFILE_422                 = 0x00,
      GST_MPEG_VIDEO_PROFILE_HIGH                = 0x01,
      GST_MPEG_VIDEO_PROFILE_SPATIALLY_SCALABLE  = 0x02,
      GST_MPEG_VIDEO_PROFILE_SNR_SCALABLE        = 0x03,
      GST_MPEG_VIDEO_PROFILE_MAIN                = 0x04,
      GST_MPEG_VIDEO_PROFILE_SIMPLE              = 0x05
    } GstMpegVideoProfile;

Mpeg-2 Profiles.

`GST_MPEG_VIDEO_PROFILE_422` | 4:2:2 profile (422)
`GST_MPEG_VIDEO_PROFILE_HIGH` | High profile (HP)
`GST_MPEG_VIDEO_PROFILE_SPATIALLY_SCALABLE` | Spatially Scalable profile (Spatial)
`GST_MPEG_VIDEO_PROFILE_SNR_SCALABLE` | SNR Scalable profile (SNR)
`GST_MPEG_VIDEO_PROFILE_MAIN` | Main profile (MP)
`GST_MPEG_VIDEO_PROFILE_SIMPLE` | Simple profile (SP)

### enum GstMpegVideoPictureType

    typedef enum {
      GST_MPEG_VIDEO_PICTURE_TYPE_I = 0x01,
      GST_MPEG_VIDEO_PICTURE_TYPE_P = 0x02,
      GST_MPEG_VIDEO_PICTURE_TYPE_B = 0x03,
      GST_MPEG_VIDEO_PICTURE_TYPE_D = 0x04
    } GstMpegVideoPictureType;

Picture type.

`GST_MPEG_VIDEO_PICTURE_TYPE_I` | Intra-coded (I) frame
`GST_MPEG_VIDEO_PICTURE_TYPE_P` | Predictive-codec (P) frame
`GST_MPEG_VIDEO_PICTURE_TYPE_B` | Bidirectionally predictive-coded (B) frame
`GST_MPEG_VIDEO_PICTURE_TYPE_D` | D frame

### enum GstMpegVideoPictureStructure

    typedef enum {
        GST_MPEG_VIDEO_PICTURE_STRUCTURE_TOP_FIELD    = 0x01,
        GST_MPEG_VIDEO_PICTURE_STRUCTURE_BOTTOM_FIELD = 0x02,
        GST_MPEG_VIDEO_PICTURE_STRUCTURE_FRAME        = 0x03
    } GstMpegVideoPictureStructure;

Picture structure type.

`GST_MPEG_VIDEO_PICTURE_STRUCTURE_TOP_FIELD` | Top field
`GST_MPEG_VIDEO_PICTURE_STRUCTURE_BOTTOM_FIELD` | Bottom field
`GST_MPEG_VIDEO_PICTURE_STRUCTURE_FRAME` | Frame picture

### struct GstMpegVideoSequenceHdr

    struct GstMpegVideoSequenceHdr {
      guint16 width, height;
      guint8  aspect_ratio_info;
      guint8  frame_rate_code;
      guint32 bitrate_value;
      guint16 vbv_buffer_size_value;

      guint8  constrained_parameters_flag;

      guint8  intra_quantizer_matrix[64];
      guint8  non_intra_quantizer_matrix[64];

      /* Calculated values */
      guint   par_w, par_h;
      guint   fps_n, fps_d;
      guint   bitrate;
    };

The Mpeg2 Video Sequence Header structure.

guint16 `width`; | Width of each frame
guint16 `height`; | Height of each frame
guint8 `aspect_ratio_info`; |
guint8 `frame_rate_code`; |
guint32 `bitrate_value`; | Value of the bitrate as is in the stream (400bps unit)
guint16 `vbv_buffer_size_value`; |
guint8 `constrained_parameters_flag`; | `TRUE` if this stream uses contrained parameters.
guint8 `intra_quantizer_matrix`[64]; | intra-quantization table, in zigzag scan order
guint8 `non_intra_quantizer_matrix`[64]; | non-intra quantization table, in zigzag scan order
guint `par_w`; | Calculated Pixel Aspect Ratio width
guint `par_h`; | Calculated Pixel Aspect Ratio height
guint `fps_n`; | Calculated Framrate nominator
guint `fps_d`; | Calculated Framerate denominator
guint `bitrate`; | the real bitrate of the Mpeg video stream in bits per second, 0 if VBR stream

### struct GstMpegVideoSequenceExt

    struct GstMpegVideoSequenceExt {
      /* mpeg2 decoder profile */
      guint8 profile;
      /* mpeg2 decoder level */
      guint8 level;

      guint8 progressive;
      guint8 chroma_format;

      guint8 horiz_size_ext, vert_size_ext;

      guint16 bitrate_ext;
      guint8 vbv_buffer_size_extension;
      guint8 low_delay;
      guint8 fps_n_ext, fps_d_ext;
    };

The Mpeg2 Video Sequence Extension structure.

guint8 `profile`; | mpeg2 decoder profile
guint8 `level`; | mpeg2 decoder level
guint8 `progressive`; | `TRUE` if the frames are progressive `FALSE` otherwise
guint8 `chroma_format`; | indicates the chrominance format
guint8 `horiz_size_ext`; | Horizontal size
guint8 `vert_size_ext`; | Vertical size
guint16 `bitrate_ext`; | The bitrate
guint8 `vbv_buffer_size_extension`; | VBV vuffer size
guint8 `low_delay`; | `TRUE` if the sequence doesn't contain any B-pictures, `FALSE` otherwise
guint8 `fps_n_ext`; | Framerate nominator code
guint8 `fps_d_ext`; | Framerate denominator code

### struct GstMpegVideoPictureHdr

    struct GstMpegVideoPictureHdr {
      guint16 tsn;
      guint8 pic_type;

      guint8 full_pel_forward_vector, full_pel_backward_vector;

      guint8 f_code[2][2];
    };

The Mpeg2 Video Picture Header structure.

guint16 `tsn`; | Temporal Sequence Number
guint8 `pic_type`; | Type of the frame
guint8 `full_pel_forward_vector`; | the full pel forward flag of the frame: 0 or 1.
guint8 `full_pel_backward_vector`; | the full pel backward flag of the frame: 0 or 1.
guint8 `f_code`[2][2]; | F code

### struct GstMpegVideoGop

    struct GstMpegVideoGop {
      guint8 drop_frame_flag;

      guint8 hour, minute, second, frame;

      guint8 closed_gop;
      guint8 broken_link;
    };

The Mpeg Video Group of Picture structure.

guint8 `drop_frame_flag`; | Drop Frame Flag
guint8 `hour`; | Hour (0-23)
guint8 `minute`; | Minute (O-59)
guint8 `second`; | Second (0-59)
guint8 `frame`; | Frame (0-59)
guint8 `closed_gop`; | Closed Gop
guint8 `broken_link`; | Broken link

### struct GstMpegVideoPictureExt

    struct GstMpegVideoPictureExt {
      guint8 f_code[2][2];

      guint8 intra_dc_precision;
      guint8 picture_structure;
      guint8 top_field_first;
      guint8 frame_pred_frame_dct;
      guint8 concealment_motion_vectors;
      guint8 q_scale_type;
      guint8 intra_vlc_format;
      guint8 alternate_scan;
      guint8 repeat_first_field;
      guint8 chroma_420_type;
      guint8 progressive_frame;
      guint8 composite_display;
      guint8 v_axis;
      guint8 field_sequence;
      guint8 sub_carrier;
      guint8 burst_amplitude;
      guint8 sub_carrier_phase;
    };

The Mpeg2 Video Picture Extension structure.

guint8 `f_code`[2][2]; |
guint8 `intra_dc_precision`; | Intra DC precision
guint8 `picture_structure`; | Structure of the picture
guint8 `top_field_first`; | Top field first
guint8 `frame_pred_frame_dct`; | Frame
guint8 `concealment_motion_vectors`; | Concealment Motion Vectors
guint8 `q_scale_type`; | Q Scale Type
guint8 `intra_vlc_format`; | Intra Vlc Format
guint8 `alternate_scan`; | Alternate Scan
guint8 `repeat_first_field`; | Repeat First Field
guint8 `chroma_420_type`; | Chroma 420 Type
guint8 `progressive_frame`; | `TRUE` if the frame is progressive `FALSE` otherwize
guint8 `composite_display`; |
guint8 `v_axis`; |
guint8 `field_sequence`; |
guint8 `sub_carrier`; |
guint8 `burst_amplitude`; |
guint8 `sub_carrier_phase`; |

### struct GstMpegVideoQuantMatrixExt

    struct GstMpegVideoQuantMatrixExt {
     guint8 load_intra_quantiser_matrix;
     guint8 intra_quantiser_matrix[64];
     guint8 load_non_intra_quantiser_matrix;
     guint8 non_intra_quantiser_matrix[64];
     guint8 load_chroma_intra_quantiser_matrix;
     guint8 chroma_intra_quantiser_matrix[64];
     guint8 load_chroma_non_intra_quantiser_matrix;
     guint8 chroma_non_intra_quantiser_matrix[64];
    };

The Quant Matrix Extension structure that exposes quantization matrices in zigzag scan order. i.e. the original encoded scan order.

### gst_mpeg_video_parse ()

    gboolean            gst_mpeg_video_parse                (GstMpegVideoPacket *packet,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

Parses the MPEG 1/2 video bitstream contained in `data`, and returns the offset, and if known also the size, in `packet`. This function will scan the data to find the next packet if needed.

`packet` : | a GstMpegVideoPacket to fill with the data and offset of the next packet found
`data` : | The data to parse
`size` : | The size of `data`
`offset` : | The offset from which to start parsing
Returns : | TRUE if a packet start code was found, otherwise FALSE.

### gst_mpeg_video_parse_sequence_header ()

    gboolean            gst_mpeg_video_parse_sequence_header
                                                            (GstMpegVideoSequenceHdr *seqhdr,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_sequence_header` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_sequence_header()` instead.

Parses the `seqhdr` Mpeg Video Sequence Header structure members from `data`

`seqhdr` : | The GstMpegVideoSequenceHdr structure to fill. [out]
`data` : | The data from which to parse the sequence header
`size` : | The size of `data`
`offset` : | The offset in byte from which to start parsing `data`
Returns : | `TRUE` if the seqhdr could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_parse_picture_header ()

    gboolean            gst_mpeg_video_parse_picture_header (GstMpegVideoPictureHdr *hdr,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_picture_header` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_picture_header()` instead.

Parsers the `hdr` Mpeg Video Picture Header structure members from `data`

`hdr` : | The GstMpegVideoPictureHdr structure to fill. [out]
`data` : | The data from which to parse the picture header
`size` : | The size of `data`
`offset` : | The offset in byte from which to start the parsing
Returns : | `TRUE` if the picture sequence could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_parse_picture_extension ()

    gboolean            gst_mpeg_video_parse_picture_extension
                                                            (GstMpegVideoPictureExt *ext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_picture_extension` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_picture_extension()` instead.

Parse the `ext` Mpeg Video Picture Extension structure members from `data`

`ext` : | The GstMpegVideoPictureExt structure to fill. [out]
`data` : | The data from which to parse the picture extension
`size` : | The size of `data`
`offset` : | The offset in byte from which to start the parsing
Returns : | `TRUE` if the picture extension could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_parse_gop ()

    gboolean            gst_mpeg_video_parse_gop            (GstMpegVideoGop *gop,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_gop` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_gop()` instead.

Parses the `gop` Mpeg Video Group of Picture structure members from `data`

`gop` : | The GstMpegVideoGop structure to fill. [out]
`data` : | The data from which to parse the gop
`size` : | The size of `data`
`offset` : | The offset in byte from which to start the parsing
Returns : | `TRUE` if the gop could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_parse_sequence_extension ()

    gboolean            gst_mpeg_video_parse_sequence_extension
                                                            (GstMpegVideoSequenceExt *seqext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_sequence_extension` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_sequence_extension()` instead.

Parses the `seqext` Mpeg Video Sequence Extension structure members from `data`

`seqext` : | The GstMpegVideoSequenceExt structure to fill. [out]
`data` : | The data from which to parse the sequence extension
`size` : | The size of `data`
`offset` : | The offset in byte from which to start parsing `data`
Returns : | `TRUE` if the seqext could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_parse_sequence_display_extension ()

    gboolean            gst_mpeg_video_parse_sequence_display_extension
                                                            (GstMpegVideoSequenceDisplayExt *seqdisplayext,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_sequence_display_extension` is deprecated and should not be used in newly-written code.

### gst_mpeg_video_parse_quant_matrix_extension ()

    gboolean            gst_mpeg_video_parse_quant_matrix_extension
                                                            (GstMpegVideoQuantMatrixExt *quant,
                                                             const guint8 *data,
                                                             gsize size,
                                                             guint offset);

### Warning

`gst_mpeg_video_parse_quant_matrix_extension` is deprecated and should not be used in newly-written code. Use `gst_mpeg_video_packet_parse_quant_matrix_extension()` instead.

Parses the `quant` Mpeg Video Quant Matrix Extension structure members from `data`

`quant` : | The GstMpegVideoQuantMatrixExt structure to fill. [out]
`data` : | The data from which to parse the Quantization Matrix extension
`size` : | The size of `data`
`offset` : | The offset in byte from which to start the parsing
Returns : | `TRUE` if the quant matrix extension could be parsed correctly, `FALSE` otherwize.

### gst_mpeg_video_finalise_mpeg2_sequence_header ()

    gboolean            gst_mpeg_video_finalise_mpeg2_sequence_header
                                                            (GstMpegVideoSequenceHdr *hdr,
                                                             GstMpegVideoSequenceExt *seqext,
                                                             GstMpegVideoSequenceDisplayExt *displayext);

### gst_mpeg_video_quant_matrix_get_raster_from_zigzag ()

    void                gst_mpeg_video_quant_matrix_get_raster_from_zigzag
                                                            (guint8 out_quant[64],
                                                             const guint8 quant[64]);

Converts quantization matrix `quant` from zigzag scan order to raster scan order and store the resulting factors into `out_quant`.

Note: it is an error to pass the same table in both `quant` and `out_quant` arguments.

`out_quant` : | The resulting quantization matrix. [out]
`quant` : | The source quantization matrix

Since 1.2

### gst_mpeg_video_quant_matrix_get_zigzag_from_raster ()

    void                gst_mpeg_video_quant_matrix_get_zigzag_from_raster
                                                            (guint8 out_quant[64],
                                                             const guint8 quant[64]);

Converts quantization matrix `quant` from raster scan order to zigzag scan order and store the resulting factors into `out_quant`.

Note: it is an error to pass the same table in both `quant` and `out_quant` arguments.

`out_quant` : | The resulting quantization matrix. [out]
`quant` : | The source quantization matrix

Since 1.2