Chapter 14. Caps negotiation

Table of Contents

Caps negotiation basics
Caps negotiation use cases
Fixed negotiation
Transform negotiation
Dynamic negotiation
Upstream caps (re)negotiation
Implementing a CAPS query function
Pull-mode Caps negotiation

Caps negotiation is the act of finding a media format (GstCaps) between elements that they can handle. This process in GStreamer can in most cases find an optimal solution for the complete pipeline. In this section we explain how this works.

Caps negotiation basics

In GStreamer, negotiation of the media format always follows the following simple rules:

  • A downstream element suggest a format on its sinkpad and places the suggestion in the result of the CAPS query performed on the sinkpad. See also Implementing a CAPS query function.

  • An upstream element decides on a format. It sends the selected media format downstream on its source pad with a CAPS event. Downstream elements reconfigure themselves to handle the media type in the CAPS event on the sinkpad.

  • A downstream element can inform upstream that it would like to suggest a new format by sending a RECONFIGURE event upstream. The RECONFIGURE event simply instructs an upstream element to restart the negotiation phase. Because the element that sent out the RECONFIGURE event is now suggesting another format, the format in the pipeline might change.

In addition to the CAPS and RECONFIGURE event and the CAPS query, there is an ACCEPT_CAPS query to quickly check if a certain caps can be accepted by an element.

All negotiation follows these simple rules. Let's take a look at some typical uses cases and how negotiation happens.