GstRTSPMedia

## GstRTSPMedia GstRTSPMedia — The media pipeline |

## Synopsis

    struct              GstRTSPMedia;
    struct              GstRTSPMediaClass;
    GstRTSPMedia *      gst_rtsp_media_new                  (GstElement *element);
    GstElement *        gst_rtsp_media_get_element          (GstRTSPMedia *media);
    void                gst_rtsp_media_take_pipeline        (GstRTSPMedia *media,
                                                             GstPipeline *pipeline);
    void                gst_rtsp_media_set_permissions      (GstRTSPMedia *media,
                                                             GstRTSPPermissions *permissions);
    GstRTSPPermissions * gst_rtsp_media_get_permissions     (GstRTSPMedia *media);
    void                gst_rtsp_media_set_shared           (GstRTSPMedia *media,
                                                             gboolean shared);
    gboolean            gst_rtsp_media_is_shared            (GstRTSPMedia *media);
    void                gst_rtsp_media_set_reusable         (GstRTSPMedia *media,
                                                             gboolean reusable);
    gboolean            gst_rtsp_media_is_reusable          (GstRTSPMedia *media);
    void                gst_rtsp_media_set_protocols        (GstRTSPMedia *media,
                                                             GstRTSPLowerTrans protocols);
    GstRTSPLowerTrans   gst_rtsp_media_get_protocols        (GstRTSPMedia *media);
    void                gst_rtsp_media_set_eos_shutdown     (GstRTSPMedia *media,
                                                             gboolean eos_shutdown);
    gboolean            gst_rtsp_media_is_eos_shutdown      (GstRTSPMedia *media);
    void                gst_rtsp_media_set_address_pool     (GstRTSPMedia *media,
                                                             GstRTSPAddressPool *pool);
    GstRTSPAddressPool * gst_rtsp_media_get_address_pool    (GstRTSPMedia *media);
    void                gst_rtsp_media_set_buffer_size      (GstRTSPMedia *media,
                                                             guint size);
    guint               gst_rtsp_media_get_buffer_size      (GstRTSPMedia *media);

    gboolean            gst_rtsp_media_prepare              (GstRTSPMedia *media,
                                                             GstRTSPThread *thread);
    gboolean            gst_rtsp_media_unprepare            (GstRTSPMedia *media);
    enum                GstRTSPMediaStatus;
    GstRTSPMediaStatus  gst_rtsp_media_get_status           (GstRTSPMedia *media);

    void                gst_rtsp_media_collect_streams      (GstRTSPMedia *media);
    GstRTSPStream *     gst_rtsp_media_create_stream        (GstRTSPMedia *media,
                                                             GstElement *payloader,
                                                             GstPad *srcpad);
    guint               gst_rtsp_media_n_streams            (GstRTSPMedia *media);
    GstRTSPStream *     gst_rtsp_media_get_stream           (GstRTSPMedia *media,
                                                             guint idx);
    GstRTSPStream *     gst_rtsp_media_find_stream          (GstRTSPMedia *media,
                                                             const gchar *control);

    gboolean            gst_rtsp_media_seek                 (GstRTSPMedia *media,
                                                             GstRTSPTimeRange *range);
    gchar *             gst_rtsp_media_get_range_string     (GstRTSPMedia *media,
                                                             gboolean play,
                                                             GstRTSPRangeUnit unit);
    gboolean            gst_rtsp_media_set_state            (GstRTSPMedia *media,
                                                             GstState state,
                                                             GPtrArray *transports);
    void                gst_rtsp_media_set_pipeline_state   (GstRTSPMedia *media,
                                                             GstState state);

    GstClock *          gst_rtsp_media_get_clock            (GstRTSPMedia *media);
    GstClockTime        gst_rtsp_media_get_base_time        (GstRTSPMedia *media);
    void                gst_rtsp_media_use_time_provider    (GstRTSPMedia *media,
                                                             gboolean time_provider);
    gboolean            gst_rtsp_media_is_time_provider     (GstRTSPMedia *media);
    GstNetTimeProvider * gst_rtsp_media_get_time_provider   (GstRTSPMedia *media,
                                                             const gchar *address,
                                                             guint16 port);

## Object Hierarchy

      GObject
       +----GstRTSPMedia

## Properties

      "buffer-size"              guint                 : Read / Write
      "element"                  GstElement*           : Read / Write / Construct Only
      "eos-shutdown"             gboolean              : Read / Write
      "profiles"                 GstRTSPProfile        : Read / Write
      "protocols"                GstRTSPLowerTrans     : Read / Write
      "reusable"                 gboolean              : Read / Write
      "shared"                   gboolean              : Read / Write
      "suspend-mode"             GstRTSPSuspendMode    : Read / Write
      "time-provider"            gboolean              : Read / Write

## Signals

      "new-state"                                      : Run Last
      "new-stream"                                     : Run Last
      "prepared"                                       : Run Last
      "removed-stream"                                 : Run Last
      "target-state"                                   : Run Last
      "unprepared"                                     : Run Last

## Description

a GstRTSPMedia contains the complete GStreamer pipeline to manage the streaming to the clients. The actual data transfer is done by the GstRTSPStream objects that are created and exposed by the GstRTSPMedia.

The GstRTSPMedia is usually created from a GstRTSPMediaFactory when the client does a DESCRIBE or SETUP of a resource.

A media is created with `gst_rtsp_media_new()` that takes the element that will provide the streaming elements. For each of the streams, a new GstRTSPStream object needs to be made with the `gst_rtsp_media_create_stream()` which takes the payloader element and the source pad that produces the RTP stream.

The pipeline of the media is set to PAUSED with `gst_rtsp_media_prepare()`. The prepare method will add rtpbin and sinks and sources to send and receive RTP and RTCP packets from the clients. Each stream srcpad is connected to an input into the internal rtpbin.

It is also possible to dynamically create GstRTSPStream objects during the prepare phase. With `gst_rtsp_media_get_status()` you can check the status of the prepare phase.

After the media is prepared, it is ready for streaming. It will usually be managed in a session with `gst_rtsp_session_manage_media()`. See GstRTSPSession and GstRTSPSessionMedia.

The state of the media can be controlled with `gst_rtsp_media_set_state()`. Seeking can be done with `gst_rtsp_media_seek()`.

With `gst_rtsp_media_unprepare()` the pipeline is stopped and shut down. When `gst_rtsp_media_set_eos_shutdown()` an EOS will be sent to the pipeline to cleanly shut down.

With `gst_rtsp_media_set_shared()`, the media can be shared between multiple clients. With `gst_rtsp_media_set_reusable()` you can control if the pipeline can be prepared again after an unprepare.

Last reviewed on 2013-07-11 (1.0.0)

## Details

### struct GstRTSPMedia

    struct GstRTSPMedia;

A class that contains the GStreamer element along with a list of GstRTSPStream objects that can produce data.

This object is usually created from a GstRTSPMediaFactory.

### struct GstRTSPMediaClass

    struct GstRTSPMediaClass {
      GObjectClass  parent_class;

      /* vmethods */
      gboolean        (*handle_message)  (GstRTSPMedia *media, GstMessage *message);
      gboolean        (*unprepare)       (GstRTSPMedia *media);
      gboolean        (*convert_range)   (GstRTSPMedia *media, GstRTSPTimeRange *range,
                                          GstRTSPRangeUnit unit);
      gboolean        (*query_position)  (GstRTSPMedia *media, gint64 *position);
      gboolean        (*query_stop)      (GstRTSPMedia *media, gint64 *stop);
      GstElement *    (*create_rtpbin)   (GstRTSPMedia *media);
      gboolean        (*setup_rtpbin)    (GstRTSPMedia *media, GstElement *rtpbin);
      gboolean        (*setup_sdp)       (GstRTSPMedia *media, GstSDPMessage *sdp, GstSDPInfo *info);

      /* signals */
      void            (*new_stream)      (GstRTSPMedia *media, GstRTSPStream * stream);
      void            (*removed_stream)  (GstRTSPMedia *media, GstRTSPStream * stream);

      void            (*prepared)        (GstRTSPMedia *media);
      void            (*unprepared)      (GstRTSPMedia *media);

      void            (*target_state)    (GstRTSPMedia *media, GstState state);
      void            (*new_state)       (GstRTSPMedia *media, GstState state);
    };

The RTSP media class

GObjectClass `parent_class`; |
`handle_message` () | handle a message
`unprepare` () | the default implementation sets the pipeline's state to GST_STATE_NULL and removes all elements.
`convert_range` () | convert a range to the given unit
`query_position` () | query the current posision in the pipeline
`query_stop` () | query when playback will stop
`create_rtpbin` () |
`setup_rtpbin` () |
`setup_sdp` () |
`new_stream` () |
`removed_stream` () |
`prepared` () |
`unprepared` () |
`target_state` () |
`new_state` () |

### gst_rtsp_media_new ()

    GstRTSPMedia *      gst_rtsp_media_new                  (GstElement *element);

Create a new GstRTSPMedia instance. `element` is the bin element that provides the different streams. The GstRTSPMedia object contains the element to produce RTP data for one or more related (audio/video/..) streams.

Ownership is taken of `element`.

`element` : | a GstElement. [transfer full]
Returns : | a new GstRTSPMedia object.

### gst_rtsp_media_get_element ()

    GstElement *        gst_rtsp_media_get_element          (GstRTSPMedia *media);

Get the element that was used when constructing `media`.

`media` : | a GstRTSPMedia
Returns : | a GstElement. Unref after usage. [transfer full]

### gst_rtsp_media_take_pipeline ()

    void                gst_rtsp_media_take_pipeline        (GstRTSPMedia *media,
                                                             GstPipeline *pipeline);

Set `pipeline` as the GstPipeline for `media`. Ownership is taken of `pipeline`.

`media` : | a GstRTSPMedia
`pipeline` : | a GstPipeline. [transfer full]

### gst_rtsp_media_set_permissions ()

    void                gst_rtsp_media_set_permissions      (GstRTSPMedia *media,
                                                             GstRTSPPermissions *permissions);

Set `permissions` on `media`.

`media` : | a GstRTSPMedia
`permissions` : | a GstRTSPPermissions

### gst_rtsp_media_get_permissions ()

    GstRTSPPermissions * gst_rtsp_media_get_permissions     (GstRTSPMedia *media);

Get the permissions object from `media`.

`media` : | a GstRTSPMedia
Returns : | a GstRTSPPermissions object, unref after usage. [transfer full]

### gst_rtsp_media_set_shared ()

    void                gst_rtsp_media_set_shared           (GstRTSPMedia *media,
                                                             gboolean shared);

Set or unset if the pipeline for `media` can be shared will multiple clients. When `shared` is `TRUE`, client requests for this media will share the media pipeline.

`media` : | a GstRTSPMedia
`shared` : | the new value

### gst_rtsp_media_is_shared ()

    gboolean            gst_rtsp_media_is_shared            (GstRTSPMedia *media);

Check if the pipeline for `media` can be shared between multiple clients.

`media` : | a GstRTSPMedia
Returns : | `TRUE` if the media can be shared between clients.

### gst_rtsp_media_set_reusable ()

    void                gst_rtsp_media_set_reusable         (GstRTSPMedia *media,
                                                             gboolean reusable);

Set or unset if the pipeline for `media` can be reused after the pipeline has been unprepared.

`media` : | a GstRTSPMedia
`reusable` : | the new value

### gst_rtsp_media_is_reusable ()

    gboolean            gst_rtsp_media_is_reusable          (GstRTSPMedia *media);

Check if the pipeline for `media` can be reused after an unprepare.

`media` : | a GstRTSPMedia
Returns : | `TRUE` if the media can be reused

### gst_rtsp_media_set_protocols ()

    void                gst_rtsp_media_set_protocols        (GstRTSPMedia *media,
                                                             GstRTSPLowerTrans protocols);

Configure the allowed lower transport for `media`.

`media` : | a GstRTSPMedia
`protocols` : | the new flags

### gst_rtsp_media_get_protocols ()

    GstRTSPLowerTrans   gst_rtsp_media_get_protocols        (GstRTSPMedia *media);

Get the allowed protocols of `media`.

`media` : | a GstRTSPMedia
Returns : | a GstRTSPLowerTrans

### gst_rtsp_media_set_eos_shutdown ()

    void                gst_rtsp_media_set_eos_shutdown     (GstRTSPMedia *media,
                                                             gboolean eos_shutdown);

Set or unset if an EOS event will be sent to the pipeline for `media` before it is unprepared.

`media` : | a GstRTSPMedia
`eos_shutdown` : | the new value

### gst_rtsp_media_is_eos_shutdown ()

    gboolean            gst_rtsp_media_is_eos_shutdown      (GstRTSPMedia *media);

Check if the pipeline for `media` will send an EOS down the pipeline before unpreparing.

`media` : | a GstRTSPMedia
Returns : | `TRUE` if the media will send EOS before unpreparing.

### gst_rtsp_media_set_address_pool ()

    void                gst_rtsp_media_set_address_pool     (GstRTSPMedia *media,
                                                             GstRTSPAddressPool *pool);

configure `pool` to be used as the address pool of `media`.

`media` : | a GstRTSPMedia
`pool` : | a GstRTSPAddressPool

### gst_rtsp_media_get_address_pool ()

    GstRTSPAddressPool * gst_rtsp_media_get_address_pool    (GstRTSPMedia *media);

Get the GstRTSPAddressPool used as the address pool of `media`.

`media` : | a GstRTSPMedia
Returns : | the GstRTSPAddressPool of `media`. `g_object_unref()` after usage. [transfer full]

### gst_rtsp_media_set_buffer_size ()

    void                gst_rtsp_media_set_buffer_size      (GstRTSPMedia *media,
                                                             guint size);

Set the kernel UDP buffer size.

`media` : | a GstRTSPMedia
`size` : | the new value

### gst_rtsp_media_get_buffer_size ()

    guint               gst_rtsp_media_get_buffer_size      (GstRTSPMedia *media);

Get the kernel UDP buffer size.

`media` : | a GstRTSPMedia
Returns : | the kernel UDP buffer size.

### gst_rtsp_media_prepare ()

    gboolean            gst_rtsp_media_prepare              (GstRTSPMedia *media,
                                                             GstRTSPThread *thread);

Prepare `media` for streaming. This function will create the objects to manage the streaming. A pipeline must have been set on `media` with `gst_rtsp_media_take_pipeline()`.

It will preroll the pipeline and collect vital information about the streams such as the duration.

`media` : | a GstRTSPMedia
`thread` : | a GstRTSPThread to run the bus handler or `NULL`
Returns : | `TRUE` on success.

### gst_rtsp_media_unprepare ()

    gboolean            gst_rtsp_media_unprepare            (GstRTSPMedia *media);

Unprepare `media`. After this call, the media should be prepared again before it can be used again. If the media is set to be non-reusable, a new instance must be created.

`media` : | a GstRTSPMedia
Returns : | `TRUE` on success.

### enum GstRTSPMediaStatus

    typedef enum {
      GST_RTSP_MEDIA_STATUS_UNPREPARED  = 0,
      GST_RTSP_MEDIA_STATUS_UNPREPARING = 1,
      GST_RTSP_MEDIA_STATUS_PREPARING   = 2,
      GST_RTSP_MEDIA_STATUS_PREPARED    = 3,
      GST_RTSP_MEDIA_STATUS_SUSPENDED   = 4,
      GST_RTSP_MEDIA_STATUS_ERROR       = 5
    } GstRTSPMediaStatus;

The state of the media pipeline.

`GST_RTSP_MEDIA_STATUS_UNPREPARED` | media pipeline not prerolled
`GST_RTSP_MEDIA_STATUS_UNPREPARING` | media pipeline is busy doing a clean shutdown.
`GST_RTSP_MEDIA_STATUS_PREPARING` | media pipeline is prerolling
`GST_RTSP_MEDIA_STATUS_PREPARED` | media pipeline is prerolled
`GST_RTSP_MEDIA_STATUS_SUSPENDED` | media is suspended
`GST_RTSP_MEDIA_STATUS_ERROR` | media pipeline is in error

### gst_rtsp_media_get_status ()

    GstRTSPMediaStatus  gst_rtsp_media_get_status           (GstRTSPMedia *media);

Get the status of `media`. When `media` is busy preparing, this function waits until `media` is prepared or in error.

`media` : | a GstRTSPMedia
Returns : | the status of `media`.

### gst_rtsp_media_collect_streams ()

    void                gst_rtsp_media_collect_streams      (GstRTSPMedia *media);

Find all payloader elements, they should be named pay%d in the element of `media`, and create GstRTSPStreams for them.

Collect all dynamic elements, named dynpay%d, and add them to the list of dynamic elements.

`media` : | a GstRTSPMedia

### gst_rtsp_media_create_stream ()

    GstRTSPStream *     gst_rtsp_media_create_stream        (GstRTSPMedia *media,
                                                             GstElement *payloader,
                                                             GstPad *srcpad);

Create a new stream in `media` that provides RTP data on `srcpad`. `srcpad` should be a pad of an element inside `media->element`.

`media` : | a GstRTSPMedia
`payloader` : | a GstElement
`srcpad` : | a source GstPad
Returns : | a new GstRTSPStream that remains valid for as long as `media` exists. [transfer none]

### gst_rtsp_media_n_streams ()

    guint               gst_rtsp_media_n_streams            (GstRTSPMedia *media);

Get the number of streams in this media.

`media` : | a GstRTSPMedia
Returns : | The number of streams.

### gst_rtsp_media_get_stream ()

    GstRTSPStream *     gst_rtsp_media_get_stream           (GstRTSPMedia *media,
                                                             guint idx);

Retrieve the stream with index `idx` from `media`.

`media` : | a GstRTSPMedia
`idx` : | the stream index
Returns : | the GstRTSPStream at index `idx` or `NULL` when a stream with that index did not exist. [transfer none]

### gst_rtsp_media_find_stream ()

    GstRTSPStream *     gst_rtsp_media_find_stream          (GstRTSPMedia *media,
                                                             const gchar *control);

Find a stream in `media` with `control` as the control uri.

`media` : | a GstRTSPMedia
`control` : | the control of the stream
Returns : | the GstRTSPStream with control uri `control` or `NULL` when a stream with that control did not exist. [transfer none]

### gst_rtsp_media_seek ()

    gboolean            gst_rtsp_media_seek                 (GstRTSPMedia *media,
                                                             GstRTSPTimeRange *range);

Seek the pipeline of `media` to `range`. `media` must be prepared with `gst_rtsp_media_prepare()`.

`media` : | a GstRTSPMedia
`range` : | a GstRTSPTimeRange
Returns : | `TRUE` on success.

### gst_rtsp_media_get_range_string ()

    gchar *             gst_rtsp_media_get_range_string     (GstRTSPMedia *media,
                                                             gboolean play,
                                                             GstRTSPRangeUnit unit);

Get the current range as a string. `media` must be prepared with `gst_rtsp_media_prepare()`.

`media` : | a GstRTSPMedia
`play` : | for the PLAY request
`unit` : | the unit to use for the string
Returns : | The range as a string, `g_free()` after usage.

### gst_rtsp_media_set_state ()

    gboolean            gst_rtsp_media_set_state            (GstRTSPMedia *media,
                                                             GstState state,
                                                             GPtrArray *transports);

Set the state of `media` to `state` and for the transports in `transports`.

`media` must be prepared with `gst_rtsp_media_prepare()`;

`media` : | a GstRTSPMedia
`state` : | the target state of the media
`transports` : | a GPtrArray of GstRTSPStreamTransport pointers. [element-type GstRtspServer.RTSPStreamTransport]
Returns : | `TRUE` on success.

### gst_rtsp_media_set_pipeline_state ()

    void                gst_rtsp_media_set_pipeline_state   (GstRTSPMedia *media,
                                                             GstState state);

Set the state of the pipeline managed by `media` to `state`

`media` : | a GstRTSPMedia
`state` : | the target state of the pipeline

### gst_rtsp_media_get_clock ()

    GstClock *          gst_rtsp_media_get_clock            (GstRTSPMedia *media);

Get the clock that is used by the pipeline in `media`.

`media` must be prepared before this method returns a valid clock object.

`media` : | a GstRTSPMedia
Returns : | the GstClock used by `media`. unref after usage. [transfer full]

### gst_rtsp_media_get_base_time ()

    GstClockTime        gst_rtsp_media_get_base_time        (GstRTSPMedia *media);

Get the base_time that is used by the pipeline in `media`.

`media` must be prepared before this method returns a valid base_time.

`media` : | a GstRTSPMedia
Returns : | the base_time used by `media`.

### gst_rtsp_media_use_time_provider ()

    void                gst_rtsp_media_use_time_provider    (GstRTSPMedia *media,
                                                             gboolean time_provider);

Set `media` to provide a GstNetTimeProvider.

`media` : | a GstRTSPMedia
`time_provider` : | if a GstNetTimeProvider should be used

### gst_rtsp_media_is_time_provider ()

    gboolean            gst_rtsp_media_is_time_provider     (GstRTSPMedia *media);

Check if `media` can provide a GstNetTimeProvider for its pipeline clock.

Use `gst_rtsp_media_get_time_provider()` to get the network clock.

`media` : | a GstRTSPMedia
Returns : | `TRUE` if `media` can provide a GstNetTimeProvider.

### gst_rtsp_media_get_time_provider ()

    GstNetTimeProvider * gst_rtsp_media_get_time_provider   (GstRTSPMedia *media,
                                                             const gchar *address,
                                                             guint16 port);

Get the GstNetTimeProvider for the clock used by `media`. The time provider will listen on `address` and `port` for client time requests.

`media` : | a GstRTSPMedia
`address` : | an address or `NULL`
`port` : | a port or 0
Returns : | the GstNetTimeProvider of `media`. [transfer full]

## Property Details

### The `"buffer-size"` property

      "buffer-size"              guint                 : Read / Write

The kernel UDP buffer size to use.

Default value: 524288

### The `"element"` property

      "element"                  GstElement*           : Read / Write / Construct Only

The GstBin to use for streaming the media.

### The `"eos-shutdown"` property

      "eos-shutdown"             gboolean              : Read / Write

Send an EOS event to the pipeline before unpreparing.

Default value: FALSE

### The `"profiles"` property

      "profiles"                 GstRTSPProfile        : Read / Write

Allowed transfer profiles.

Default value: GST_RTSP_PROFILE_AVP

### The `"protocols"` property

      "protocols"                GstRTSPLowerTrans     : Read / Write

Allowed lower transport protocols.

Default value: GST_RTSP_LOWER_TRANS_UDP|GST_RTSP_LOWER_TRANS_UDP_MCAST|GST_RTSP_LOWER_TRANS_TCP

### The `"reusable"` property

      "reusable"                 gboolean              : Read / Write

If this media pipeline can be reused after an unprepare.

Default value: FALSE

### The `"shared"` property

      "shared"                   gboolean              : Read / Write

If this media pipeline can be shared.

Default value: FALSE

### The `"suspend-mode"` property

      "suspend-mode"             GstRTSPSuspendMode    : Read / Write

How to suspend the media in PAUSED.

Default value: GST_RTSP_SUSPEND_MODE_NONE

### The `"time-provider"` property

      "time-provider"            gboolean              : Read / Write

Use a NetTimeProvider for clients.

Default value: FALSE

## Signal Details

### The `"new-state"` signal

    void                user_function                      (GstRTSPMedia *gstrtspmedia,
                                                            gint          arg1,
                                                            gpointer      user_data)         : Run Last

### The `"new-stream"` signal

    void                user_function                      (GstRTSPMedia  *gstrtspmedia,
                                                            GstRTSPStream *arg1,
                                                            gpointer       user_data)         : Run Last

### The `"prepared"` signal

    void                user_function                      (GstRTSPMedia *gstrtspmedia,
                                                            gpointer      user_data)         : Run Last

### The `"removed-stream"` signal

    void                user_function                      (GstRTSPMedia  *gstrtspmedia,
                                                            GstRTSPStream *arg1,
                                                            gpointer       user_data)         : Run Last

### The `"target-state"` signal

    void                user_function                      (GstRTSPMedia *gstrtspmedia,
                                                            gint          arg1,
                                                            gpointer      user_data)         : Run Last

### The `"unprepared"` signal

    void                user_function                      (GstRTSPMedia *gstrtspmedia,
                                                            gpointer      user_data)         : Run Last

## See Also

GstRTSPMediaFactory, GstRTSPStream, GstRTSPSession, GstRTSPSessionMedia