GStreamer Daemon - Interacting with Pipelines

GStreamer Daemon
GStreamer Daemon Basics
Building GStreamer Daemon
Quick Start Guide
Interacting with Pipelines
Modifying Element Properties
Sending Events
Receiving Messages from the Bus
EOS Seek Flush start/Flush stop
Receiving Signals
Enabling the Debug Subsystem
Low-level Implementation for Applications
Response Format
API Reference
C/C++ API Python API JavaScript API HTTP API
Simple Examples
Gapless Playback MP4 Video Recording New Clock Slow Motion Reverse Playback Monitor pipeline errors
Advanced Examples
Gstd and Interpipes CCTV Digital Camera GstD Digital PTZ GstD with ROS
API Examples
Python Video Player Example Javascript Video Player Example
Troubleshooting
Interpipesink
Releases
Licensing
FAQ
Contact Us

This wiki describes the basics of how to interact with GStreamer pipelines. Specifically, how to create new pipelines, change their state, list existing pipelines, and finally destroy them. You'll find that the family of commands used to interact with pipelines are prefixed with pipeline_<action>.

Create Pipelines

In order to create a pipeline use the following command:

 pipeline_create name description
     Creates a new pipeline named after name using the description gst-launch syntax.

For example:
⇒ Gstd Commands:

1 pipeline_create p1 videotestsrc ! autovideosink
2 pipeline_create p2 playbin
3 pipeline_create p3 mpegtsmux name=mux videotestsrc ! x264enc ! mux. audiotestsrc ! avenc_aac ! mux. mux. ! filesink location=test.ts

would create respectively:

1. A pipeline named p1 consisting on a simple videotestsrc display
2. A pipeline named p2 consisting on a single element (playbin), which is enough to do playback of a file
3. A pipeline named p3 consisting on an audio+video transport stream video recording.

The pipeline_create command will typically fail for any of the following:

• No name was given
• No description was given
• A pipeline with that name already exists
• The description has a syntax error (typo, missing element, etc...)

Alternatively, a pipeline can be created using the low level CRUD syntax:
⇒ Gstd Commands:

1 create /pipelines p1 videotestsrc ! autovideosink
2 create /pipelines p2 playbin
3 create /pipelines p3 mpegtsmux name=mux videotestsrc ! x264enc ! mux. audiotestsrc ! avenc_aac ! mux. mux. ! filesink location=test.ts

Play Pipelines

In order to play a pipeline use the following command:

 pipeline_play name
     Puts the pipeline named name in the PLAYING state.

For example:
⇒ Gstd Commands:

1 pipeline_play p1

would put the p1 pipeline into the playing state.

The pipeline_play command will typically fail for any of the following:

• No name was given
• No pipeline with the given name was found
• A pipeline specific error

Alternatively, a pipeline can be played using the low level CRUD syntax:
⇒ Gstd Commands:

1 update /pipelines/p1/state playing

Pause Pipelines

In order to pause a pipeline use the following command:

 pipeline_pause name
     Puts the pipeline named name in the PAUSED state.

For example:
⇒ Gstd Commands:

1 pipeline_pause p1

would put the p1 pipeline into the paused state.

The pipeline_pause command will typically fail for any of the following:

• No name was given
• No pipeline with the given name was found
• A pipeline specific error

Alternatively, a pipeline can be paused using the low level CRUD syntax:
⇒ Gstd Commands:

1 update /pipelines/p1/state paused

Stop Pipelines

In order to stop a pipeline use the following command:

 pipeline_stop name
     Puts the pipeline named name in the NULL state.

For example:
⇒ Gstd Commands:

1 pipeline_stop p1

would put the p1 pipeline into the null state.

The pipeline_stop command will typically fail for any of the following:

• No name was given
• No pipeline with the given name was found
• A pipeline specific error

Alternatively, a pipeline can be stopped using the low level CRUD syntax:
⇒ Gstd Commands:

1 update /pipelines/p1/state null

Delete Pipelines

In order to delete a pipeline use the following command:

 pipeline_delete name
     Deletes the pipeline named name, stopping it first if necessary.

For example:
⇒ Gstd Commands:

1 pipeline_delete p1

would stop the p1 pipeline and delete it afterwards.

The pipeline_delete command will typically fail for any of the following:

• No name was given
• No pipeline with the given name was found
• A pipeline specific error when stopping the pipeline.

Alternatively, a pipeline can be deleted using the low level CRUD syntax:
⇒ Gstd Commands:

1 delete /pipelines p1

List Pipelines

In order to list the existing pipelines use the following command:

 list_pipelines
     List the pipelines in the session.

For example:
⇒ Gstd Commands:

1 list_pipelines

would list the pipelines in the current session, if any.

Alternatively, the list of pipelines can be found by using the low level CRUD syntax:
⇒ Gstd Commands:

1 read /pipelines

Refcount Commands

The GstD refcount commands provide an alternative to interact with pipelines as though they had a reference counter. These commands should not be mixed with the regular versions of the same command as it may cause unexpected behavior. Currently the following commands that use this concept are implemented in GstD:

1 pipeline_create_ref
2 pipeline_delete_ref
3 pipeline_play_ref
4 pipeline_stop_ref

The utility of the refcount commands lays in the ability to ensure thread safety when multiple processes share a single pipeline. For example:

Basic commands

 1 # Two processes pid1 and pid2 share a source pipeline p0
 2 # Both processes create the pipeline only if it doesn't exist
 3 pipeline_create p0 ...
 4 pipeline_play p0
 5 ...
 6 # Use the pipeline
 7 ...
 8 # Then both processes delete the pipeline if it is running
 9 pipeline_stop p0
10 pipeline_delete p0

The previous logic is not thread safe and it can cause a state where the pipeline is created twice, deleted twice, or stopped prematurely for one of the processes. Even with communication between these processes we can't guarantee thread safety with the basic commands.

Refcount commands

 1 # Two processes pid1 and pid2 share a source pipeline p0
 2 # Both processes call create and play with refcount
 3 # The first process will create and play the pipeline (refcount = 1)
 4 # The second process will only increase the reference count by 1  (refcount = 2)
 5 pipeline_create_ref p0 ...
 6 pipeline_play_ref p0
 7 ...
 8 # Use the pipeline
 9 ...
10 # Both processes call stop and delete with refcount
11 # The first process will not stop or delete the pipeline because the refcount is 2
12 # It will only decrease the reference count by 1 (refcount = 1)
13 # The second process will stop and delete the pipeline
14 pipeline_stop_ref p0
15 pipeline_delete_ref p0

There is a different "play" and "create" reference counts.

pipeline_create_ref

and

pipeline_delete_ref

will increase or decrease the "create" refcount while

pipeline_play_ref

and

pipeline_stop_ref

will work with the "play" refcount.

For pipeline_create_ref the description and name must match exactly. For the other 3 commands only the name is necessary.

API Summary

High Level Command	Low Level CRUD	Description
pipeline_create <name> <description>	create /pipelines <name> <description>	Creates a new pipeline named after name using the description gst-launch syntax.
pipeline_play <name>	update /pipelines/<name>/state playing	Puts the pipeline named name in the PLAYING state.
pipeline_pause <name>	update /pipelines/<name>/state paused	Puts the pipeline named name in the PAUSED state.
pipeline_stop <name>	update /pipelines/<name>/state null	Puts the pipeline named name in the NULL state.
pipeline_delete <name>	delete /pipelines/<name>	Deletes the pipeline named name, stopping it first if necessary.
list_pipelines	read /pipelines	List the pipelines in the session.
pipeline_create_ref <name> <description>	-	Creates a new pipeline or increases the create refcount if the pipeline already exists.
pipeline_delete_ref <name>	-	Deletes the pipeline or decreases the create refcount if refcount > 1.
pipeline_play_ref <name>	-	Puts the pipeline in the PLAYING state or increases the play refcount if the pipeline is already playing.
pipeline_stop_ref <name>	-	Puts the pipeline in the NULL state or decreases the play refcount if refcount > 1.