The GstTagReader interface may be implemented by elements that extract metadata to allow the fine-tuning of the tag-reading process. The interface is not required by all elements that extract tags - it is perfectly acceptable to post tag messages on the bus and not implement this interface. The interface merely serves to indicate that an element supports one or more special tag reading modes which when set might result in more efficient tag processing in certain cases.

Use cases

There are currently two main use cases for this interface:

How to use GstTagReader in applications

Application writers who want to avoid the (usually very small) overhead of tag extraction when playing back media can put uridecodebin or decodebin2 (or the elements in their pipeline directly, if they implement the interface) into tag reading mode GST_TAG_READING_MODE_SKIP_TAGS using gst_tag_reader_set_tag_reading_mode() before starting the pipeline.

Application writers who want to extract tags and other metadata as fast and efficiently as possible should use the 'tagreadbin' element, which will handle everything for them, and which will then use the GstTagReader interface internally.

How to implement the GstTagReader in elements

GstTagReader is a 'dummy interface' similar to GstTagSetter, meaning that there are no interface methods to implement. All that needs to be done is to add the interface to an element's GType in the element's _get_type() function or GST_BOILERPLATE_FULL macro. This can be done using the convenience function gst_tag_reader_add_interface_to_type().

Elements implementing the interface should then query the configured tag reading mode when starting up (ie. in the start function or in the state change function in the NULL to READY transition), using gst_tag_reader_get_tag_reading_mode().

In GST_TAG_READING_MODE_SKIP_TAGS mode elements should skip metadata processing wherever this is possible without affecting functionality otherwise. Element should not post TAG messages on the bus in this mode.

In GST_TAG_READING_MODE_DEFAULT mode elements should behave like they normally would. For most elements this means tag extraction and normal stream handling.

In GST_TAG_READING_MODE_TAGS_ONLY mode elements are requested to skip any non-essential data processing. Demuxers, for example, may choose not to parse a seek index or build a seek table, but should still parse file headers and add pads and push newsegment events and data as they usually would (however, they are not required to reproduce output in the way they would for normal playback, e.g. they may push only key frames, which is all that is required for thumbnailing purposes).

Elements in GST_TAG_READING_MODE_TAGS_ONLY are required to properly aggregate or pass upstream flow returns. If they are driving the pipeline they will also need to EOS on GST_FLOW_UNEXPECTED flow returns from downstream. This is how the tagreadbin element will stop streaming once it has collected all information.

Tag-handling guidelines for all demuxers and parsers

Below some general guidelines on how demuxers, parsers and decoders should handle tags.

Demuxers should push tag events for 'global' tag before pushing tags with per-stream information. This global tag list should contain a GST_TAG_CONTAINER_FORMAT tag. They also should push global tags and per-stream tags separately.

Parsers and decoders should ensure that they cache tag events received from upstream and push them on their source pad before any tags of their own are pushed, maintaining the order of the tag events as they came in.

Since 0.10.24

GstTagReader

typedef struct _GstTagReader GstTagReader;

Opaque GstTagReader structure (dummy typedef to denote object instances which implement the GstTagReader interface).

Since 0.10.24

enum GstTagReadingMode

typedef enum {
  GST_TAG_READING_MODE_DEFAULT = 0,
  GST_TAG_READING_MODE_TAGS_ONLY,
  GST_TAG_READING_MODE_SKIP_TAGS
} GstTagReadingMode;

Available tag reading modes.

Since 0.10.24

gst_tag_reader_add_interface_to_type ()

void                gst_tag_reader_add_interface_to_type
                                                        (GType type);

Convenience function to add the GstTagReader interface to an element. Use from within the element's _get_type() function or in connection with GST_BOILERPLATE_FULL.

Since 0.10.24

gst_tag_reader_set_tag_reading_mode ()

void                gst_tag_reader_set_tag_reading_mode (GstTagReader *reader,
                                                         GstTagReadingMode mode);

This will set the tag reader's mode of operation. You should use this method to tell a tag reader capable element in which GstTagReadingMode the reader should operate in.

This function will take the object lock and must not be called with the object lock already held.

Since 0.10.24

gst_tag_reader_get_tag_reading_mode ()

GstTagReadingMode   gst_tag_reader_get_tag_reading_mode (GstTagReader *reader);

Query the currently configured GstTagReadingMode.

This function will take the object lock and must not be called with the object lock already held.

Since 0.10.24