The goal of the GstPlay library is to ease the integration of multimedia playback features in applications. Thus, if you need to build a media player from the ground-up, GstPlay provides the features you will most likely need. An example player is available in gst-examples/playback/player/gst-play/. Internally the GstPlay makes use of the `playbin3` element. The legacy `playbin2` can be selected if the `GST_PLAY_USE_PLAYBIN3=0` environment variable has been set. **Important note**: If your application relies on the GstBus to get notifications from GstPlay, you need to add some explicit clean-up code in order to prevent the GstPlay object from leaking. See below for the details. If you use the GstPlaySignalAdapter, no special clean-up is required. When the GstPlaySignalAdapter is not used, the GstBus owned by GstPlay should be set to flushing state before any attempt to drop the last reference of the GstPlay object. An example in C: ```c ... GstBus *bus = gst_play_get_message_bus (player); gst_bus_set_flushing (bus, TRUE); gst_object_unref (bus); gst_object_unref (player); ``` The messages managed by the player contain a reference to itself, and if the bus watch is just removed together with dropping the player then the bus will simply keep them around forever (and the bus never goes away because the player has a strong reference to it, so there's a reference cycle as long as there are messages). Setting the bus to flushing state forces it to get rid of its queued messages, thus breaking any possible reference cycle. Creates a new #GstPlay instance. Video is going to be rendered by @video_renderer, or if %NULL is provided no special video set up will be done and some default handling will be performed. This also initializes GStreamer via `gst_init()` on the first call if this didn't happen before. a new #GstPlay instance GstPlayVideoRenderer to use %TRUE if pipeline dumps are included in #GstPlay error message details. a #GstPlay configuration current position update interval in milliseconds a #GstPlay configuration %TRUE if accurate seeking is enabled a #GstPlay configuration Return the user agent which has been configured using gst_play_config_set_user_agent() if any. the configured agent, or %NULL a #GstPlay configuration When enabled, the error message emitted by #GstPlay will include a pipeline dump (in Graphviz DOT format) in the error details #GstStructure. The field name is `pipeline-dump`. This option is disabled by default. a #GstPlay configuration Include pipeline dumps in error details, or not. Set desired interval in milliseconds between two position-updated messages. Pass 0 to stop updating the position. a #GstPlay configuration interval in ms Enable or disable accurate seeking. When enabled, elements will try harder to seek as accurately as possible to the requested seek position. Generally it will be slower especially for formats that don't have any indexes or timestamp markers in the stream. If accurate seeking is disabled, elements will seek as close as the request position without slowing down seeking too much. Accurate seeking is disabled by default. a #GstPlay configuration accurate seek or not Set the user agent to pass to the server if @play needs to connect to a server during playback. This is typically used when playing HTTP or RTSP streams. a #GstPlay configuration the string to use as user agent A #GList of matching #GstPlayAudioInfo. a #GstPlayMediaInfo A #GList of matching #GstPlaySubtitleInfo. a #GstPlayMediaInfo A #GList of matching #GstPlayVideoInfo. a #GstPlayMediaInfo A #gboolean indicating whether the passed message represents a #GstPlay message or not. A #GstMessage Frees a %NULL terminated array of #GstPlayVisualization. a %NULL terminated array of #GstPlayVisualization to free a %NULL terminated array containing all available visualizations. Use gst_play_visualizations_free() after usage. Retrieve the current value of audio-video-offset property The current value of audio-video-offset in nanoseconds #GstPlay instance Retrieve the current value of the indicated @type. The current value of @type, between [0,1]. In case of error -1 is returned. #GstPlay instance #GstPlayColorBalanceType Get a copy of the current configuration of the play. This configuration can either be modified and used for the gst_play_set_config() call or it must be freed after usage. a copy of the current configuration of @play. Use gst_structure_free() after usage or gst_play_set_config(). #GstPlay instance A Function to get current audio #GstPlayAudioInfo instance. current audio track. The caller should free it with g_object_unref() #GstPlay instance A Function to get current subtitle #GstPlaySubtitleInfo instance. current subtitle track. The caller should free it with g_object_unref() #GstPlay instance A Function to get current video #GstPlayVideoInfo instance. current video track. The caller should free it with g_object_unref() #GstPlay instance Name of the currently enabled visualization. g_free() after usage. #GstPlay instance Retrieves the duration of the media stream that self represents. the duration of the currently-playing media stream, in nanoseconds. #GstPlay instance A Function to get the current media info #GstPlayMediaInfo instance. media info instance. The caller should free it with g_object_unref() #GstPlay instance GstPlay API exposes a #GstBus instance which purpose is to provide data structures representing play-internal events in form of #GstMessage<!-- -->s of type GST_MESSAGE_APPLICATION. Each message carries a "play-message" field of type #GstPlayMessage. Further fields of the message data are specific to each possible value of that enumeration. Applications can consume the messages asynchronously within their own event-loop / UI-thread etc. Note that in case the application does not consume the messages, the bus will accumulate these internally and eventually fill memory. To avoid that, the bus has to be set "flushing". The play message bus instance #GstPlay instance Retrieve the current value of the indicated @type. The current value of @type, Default: 0x00000000 "none #GstPlay instance Retrieve the current value of the indicated @type. The current value of @type, Default: -1 "none" #GstPlay instance %TRUE if the currently-playing stream is muted. #GstPlay instance The internal playbin instance. The caller should free it with g_object_unref() #GstPlay instance the absolute position time, in nanoseconds, of the currently-playing stream. #GstPlay instance current playback rate #GstPlay instance Current subtitle URI URI of the current external subtitle. g_free() after usage. #GstPlay instance Retrieve the current value of subtitle-video-offset property The current value of subtitle-video-offset in nanoseconds #GstPlay instance Gets the URI of the currently-playing stream. a string containing the URI of the currently-playing stream. g_free() after usage. #GstPlay instance Get a snapshot of the currently selected video stream, if any. The format can be selected with @format and optional configuration is possible with @config. Currently supported settings are: - width, height of type G_TYPE_INT - pixel-aspect-ratio of type GST_TYPE_FRACTION Except for GST_PLAY_THUMBNAIL_RAW_NATIVE format, if no config is set, pixel-aspect-ratio would be 1/1 Current video snapshot sample or %NULL on failure #GstPlay instance output format of the video snapshot Additional configuration Returns the current volume level, as a percentage between 0 and 1. the volume as percentage between 0 and 1. #GstPlay instance Checks whether the @play has color balance support available. %TRUE if @play has color balance support. Otherwise, %FALSE. #GstPlay instance Pauses the current stream. #GstPlay instance Request to play the loaded stream. #GstPlay instance Seeks the currently-playing stream to the absolute @position time in nanoseconds. #GstPlay instance position to seek in nanoseconds %TRUE or %FALSE Sets the audio track @stream_index. #GstPlay instance stream index Enable or disable the current audio track. #GstPlay instance TRUE or FALSE Sets audio-video-offset property by value of @offset #GstPlay instance #gint64 in nanoseconds Sets the current value of the indicated channel @type to the passed value. #GstPlay instance #GstPlayColorBalanceType The new value for the @type, ranged [0,1] Set the configuration of the play. If the play is already configured, and the configuration hasn't changed, this function will return %TRUE. If the play is not in the GST_PLAY_STATE_STOPPED, this method will return %FALSE and active configuration will remain. @config is a #GstStructure that contains the configuration parameters for the play. This function takes ownership of @config. %TRUE when the configuration could be set. #GstPlay instance a #GstStructure Sets the current value of the indicated mode @type to the passed value. #GstPlay instance The new value for the @type Sets the current value of the indicated mode @type to the passed value. #GstPlay instance The new value for the @type %TRUE if the currently-playing stream should be muted. #GstPlay instance Mute state the should be set Playback at specified rate #GstPlay instance playback rate %TRUE or %FALSE Sets the subtitle stack @stream_index. #GstPlay instance stream index Enable or disable the current subtitle track. #GstPlay instance TRUE or FALSE Sets the external subtitle URI. This should be combined with a call to gst_play_set_subtitle_track_enabled(@play, TRUE) so the subtitles are actually rendered. #GstPlay instance subtitle URI Sets subtitle-video-offset property by value of @offset #GstPlay instance #gint64 in nanoseconds Sets the next URI to play. #GstPlay instance next URI to play. %TRUE or %FALSE Sets the video track @stream_index. #GstPlay instance stream index Enable or disable the current video track. #GstPlay instance TRUE or FALSE %TRUE if the visualization was set correctly. Otherwise, %FALSE. #GstPlay instance visualization element obtained from #gst_play_visualizations_get() Enable or disable the visualization. #GstPlay instance TRUE or FALSE Sets the volume level of the stream as a percentage between 0 and 1. #GstPlay instance the new volume level, as a percentage between 0 and 1 Stops playing the current stream and resets to the first position in the stream. #GstPlay instance #GstPlayStreamInfo specific to audio streams. the audio bitrate in #GstPlayAudioInfo or -1 if unknown. a #GstPlayAudioInfo the number of audio channels in #GstPlayAudioInfo or 0 if unknown. a #GstPlayAudioInfo the language of the stream, or %NULL if unknown. a #GstPlayAudioInfo the audio maximum bitrate in #GstPlayAudioInfo or -1 if unknown. a #GstPlayAudioInfo the audio sample rate in #GstPlayAudioInfo or 0 if unknown. a #GstPlayAudioInfo hue or color balance. brightness or black level. color saturation or chroma gain. contrast or luma gain. Gets a string representing the given color balance type. a string with the name of the color balance type. a #GstPlayColorBalanceType generic error. Gets a string representing the given error. a string with the given error. a #GstPlayError Structure containing the media information of a URI. A #GList of matching #GstPlayAudioInfo. a #GstPlayMediaInfo the container format or %NULL if unknown. a #GstPlayMediaInfo duration of the media. a #GstPlayMediaInfo Function to get the image (or preview-image) stored in taglist. Application can use `gst_sample_*_()` API's to get caps, buffer etc. GstSample or %NULL. a #GstPlayMediaInfo number of audio streams. a #GstPlayMediaInfo number of total streams. a #GstPlayMediaInfo number of subtitle streams. a #GstPlayMediaInfo number of video streams. a #GstPlayMediaInfo A #GList of matching #GstPlayStreamInfo. a #GstPlayMediaInfo A #GList of matching #GstPlaySubtitleInfo. a #GstPlayMediaInfo the tags contained in media info. a #GstPlayMediaInfo the media title or %NULL if unknown. a #GstPlayMediaInfo the URI associated with #GstPlayMediaInfo. a #GstPlayMediaInfo A #GList of matching #GstPlayVideoInfo. a #GstPlayMediaInfo %TRUE if the media is live. a #GstPlayMediaInfo %TRUE if the media is seekable. a #GstPlayMediaInfo Types of messages that will be posted on the play API bus. See also #gst_play_get_message_bus() Source element was initalized for set URI Sink position changed Duration of stream changed State changed, see #GstPlayState Pipeline is in buffering state, message contains the percentage value of the decoding buffer Sink has received EOS Message contains an error Message contains an error Video sink received format in different dimensions than before A media-info property has changed, message contains current #GstPlayMediaInfo The volume of the audio ouput has changed Audio muting flag has been toggled Any pending seeking operation has been completed a string with the name of the message. a #GstPlayMessage Parse the given buffering-percent @msg and extract the corresponding value A #GstMessage the resulting buffering percent Parse the given duration @msg and extract the corresponding #GstClockTime A #GstMessage the resulting duration Parse the given error @msg and extract the corresponding #GError A #GstMessage the resulting error A #GstStructure containing additional details about the error Parse the given @msg and extract the corresponding media information A #GstMessage the resulting media info Parse the given @msg and extract the corresponding audio muted state A #GstMessage the resulting audio muted state Parse the given position @msg and extract the corresponding #GstClockTime A #GstMessage the resulting position Parse the given state @msg and extract the corresponding #GstPlayState A #GstMessage the resulting play state Parse the given @msg and extract its #GstPlayMessage type. A #GstMessage the resulting message type Parse the given @msg and extract the corresponding video dimensions A #GstMessage the resulting video width the resulting video height Parse the given @msg and extract the corresponding audio volume A #GstMessage the resulting audio volume Parse the given error @msg and extract the corresponding #GError warning A #GstMessage the resulting warning A #GstStructure containing additional details about the warning A bus-watching #GSource will be created and attached to the the thread-default #GMainContext. The attached callback will emit the corresponding signal for the message received. Matching signals for play messages from the bus will be emitted by it on the created adapter object. A new #GstPlaySignalAdapter to connect signal handlers to. #GstPlay instance to emit signals for. Create an adapter that synchronously emits its signals, from the thread in which the messages have been posted. A new #GstPlaySignalAdapter to connect signal handlers to. #GstPlay instance to emit signals for. A bus-watching #GSource will be created and attached to the @context. The attached callback will emit the corresponding signal for the message received. Matching signals for play messages from the bus will be emitted by it on the created adapter object. A new #GstPlaySignalAdapter to connect signal handlers to. #GstPlay instance to emit signals for. A #GMainContext on which the main-loop will process play bus messages on. The #GstPlay owning this signal adapter. #GstPlaySignalAdapter instance Emitted on errors. The error Additional error details Emitted on warnings. The warning Additional warning details raw native format. raw xRGB format. raw BGRx format. jpeg format. png format. the play is stopped. the play is buffering. the play is paused. the play is currently playing a stream. Gets a string representing the given state. a string with the name of the state. a #GstPlayState Base structure for information concerning a media stream. Depending on the stream type, one can find more media-specific information in #GstPlayVideoInfo, #GstPlayAudioInfo, #GstPlaySubtitleInfo. the #GstCaps of the stream or %NULL if unknown. a #GstPlayStreamInfo A string describing codec used in #GstPlayStreamInfo. codec string or %NULL on unknown. a #GstPlayStreamInfo Function to get stream index from #GstPlayStreamInfo instance or -1 if unknown. the stream index of this stream. a #GstPlayStreamInfo Function to return human readable name for the stream type of the given @info (ex: "audio", "video", "subtitle") a human readable name a #GstPlayStreamInfo the tags contained in this stream. a #GstPlayStreamInfo #GstPlayStreamInfo specific to subtitle streams. the language of the stream, or %NULL if unknown. a #GstPlaySubtitleInfo #GstPlayStreamInfo specific to video streams. the current bitrate of video in #GstPlayVideoInfo or -1 if unknown. a #GstPlayVideoInfo a #GstPlayVideoInfo Numerator of frame rate Denominator of frame rate the height of video in #GstPlayVideoInfo or -1 if unknown. a #GstPlayVideoInfo the maximum bitrate of video in #GstPlayVideoInfo or -1 if unknown. a #GstPlayVideoInfo Returns the pixel aspect ratio in @par_n and @par_d a #GstPlayVideoInfo numerator denominator the width of video in #GstPlayVideoInfo or -1 if unknown. a #GstPlayVideoInfo Window handle to use or %NULL Window handle to use or %NULL the custom video_sink element to be set for the video renderer Tell an overlay that it has been exposed. This will redraw the current frame in the drawable even if the pipeline is PAUSED. a #GstPlayVideoOverlayVideoRenderer instance. Return the currently configured render rectangle. See gst_play_video_overlay_video_renderer_set_render_rectangle() for details. a #GstPlayVideoOverlayVideoRenderer instance the horizontal offset of the render area inside the window the vertical offset of the render area inside the window the width of the render area inside the window the height of the render area inside the window The currently set, platform specific window handle #GstPlayVideoRenderer instance Configure a subregion as a video target within the window set by gst_play_video_overlay_video_renderer_set_window_handle(). If this is not used or not supported the video will fill the area of the window set as the overlay to 100%. By specifying the rectangle, the video can be overlaid to a specific region of that window only. After setting the new rectangle one should call gst_play_video_overlay_video_renderer_expose() to force a redraw. To unset the region pass -1 for the @width and @height parameters. This method is needed for non fullscreen video overlay in UI toolkits that do not support subwindows. a #GstPlayVideoOverlayVideoRenderer instance the horizontal offset of the render area inside the window the vertical offset of the render area inside the window the width of the render area inside the window the height of the render area inside the window Sets the platform specific window handle into which the video should be rendered #GstPlayVideoRenderer instance handle referencing to the platform specific window A #GstPlayVisualization descriptor. name of the visualization. description of the visualization. Makes a copy of the #GstPlayVisualization. The result must be freed using gst_play_visualization_free(). an allocated copy of @vis. #GstPlayVisualization instance Frees a #GstPlayVisualization. #GstPlayVisualization instance Gets a string representing the given color balance type. a string with the name of the color balance type. a #GstPlayColorBalanceType Gets a string representing the given error. a string with the given error. a #GstPlayError a string with the name of the message. a #GstPlayMessage Parse the given buffering-percent @msg and extract the corresponding value A #GstMessage the resulting buffering percent Parse the given duration @msg and extract the corresponding #GstClockTime A #GstMessage the resulting duration Parse the given error @msg and extract the corresponding #GError A #GstMessage the resulting error A #GstStructure containing additional details about the error Parse the given @msg and extract the corresponding media information A #GstMessage the resulting media info Parse the given @msg and extract the corresponding audio muted state A #GstMessage the resulting audio muted state Parse the given position @msg and extract the corresponding #GstClockTime A #GstMessage the resulting position Parse the given state @msg and extract the corresponding #GstPlayState A #GstMessage the resulting play state Parse the given @msg and extract its #GstPlayMessage type. A #GstMessage the resulting message type Parse the given @msg and extract the corresponding video dimensions A #GstMessage the resulting video width the resulting video height Parse the given @msg and extract the corresponding audio volume A #GstMessage the resulting audio volume Parse the given error @msg and extract the corresponding #GError warning A #GstMessage the resulting warning A #GstStructure containing additional details about the warning Gets a string representing the given state. a string with the name of the state. a #GstPlayState