`GStreamer` Application Development Manual
<<< Previous	GstPad	Next >>>

Capabilities of a GstPad

Since the pads play a very important role in how the element is viewed by the outside world, a mechanism is implemented to describe the pad by using capabilities.

We will briefly describe what capabilities are, enough for you to get a basic understanding of the concepts. You will find more information on how to create capabilities in the filter-writer-guide.

What is a capability

A capability is attached to a pad in order to describe what type of media the pad can handle.

A capability is named and consists of a MIME type and a set of properties. Its data structure is:

struct _GstCaps {
  gchar *name;                  /* the name of this caps */

  guint16 id;                   /* type id (major type) */

  GstProps *properties;         /* properties for this capability */
};

Below is a dump of the capabilities of the element mpg123, as shown by gstreamer-inspect. You can see two pads: sink and src. Both pads have capability information attached to them.

The sink pad (input pad) is called 'sink' and takes data of MIME type 'audio/mp3'. It also has three properties: layer, bitrate and framed.

The src pad (output pad) is called 'src' and outputs data of MIME type 'audio/raw'. It also has four properties: format, depth, rate and channels.

Pads:
  SINK: 'sink'
    ....
      Capabilities:
      'mpg123_sink':
       MIME type: 'audio/mp3':
        layer: Integer range: 1 - 3
        bitrate: Integer range: 8 - 320
        framed: Boolean: TRUE

  SRC: 'src'
    ....
    Capabilities:
    'mpg123_src':
     MIME type: 'audio/raw':
      format: Integer: 16
      depth: Integer: 16
      rate: Integer range: 11025 - 48000
      channels: List:
        Integer: 1
        Integer: 2

What are properties

Properties are used to describe extra information for the capabilities. The properties basically exist of a key (a string) and a value. There are different possibile value types that can be used:

An integer value: the property has this exact value.
An integer range value. The property denotes a range of possible values. In the case of the mpg123 element: the src pad has a property rate that can go from 11025 to 48000.
A boolean value.
a fourcc value: this is a value that is commonly used to describe an encoding for video, as used be the AVI specification.
A list value: the property can take any value from a list.

What are the capabilities used for?

Capabilities describe in great detail the type of media that is handled by the pads. They are mostly used for:

Autoplugging: automatically finding plugins for a set of capabilities
Compatibility detection: when two pads are connected, GStreamer can verify if the two pads are talking about the same media types.

Getting the capabilities of a pad

A pad can have a GList of capabilities attached to it. You can get the capabilities list with:

 GList *caps;
    ...
 caps = gst_pad_get_caps_list (pad);

 g_print ("pad name %s\n", gst_pad_get_name (pad));
 
 while (caps) {
   GstCaps *cap = (GstCaps *) caps->data;

   g_print (" Capability name %s, MIME type\n", gst_caps_get_name (cap), 
                                                gst_caps_get_mime (cap));
   
   caps = g_list_next (caps);
 }
    ...