GStreamer Daemon - Interacting with Pipelines
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:
pipeline_create p1 videotestsrc ! autovideosink pipeline_create p2 playbin pipeline_create p3 mpegtsmux name=mux videotestsrc ! x264enc ! mux. audiotestsrc ! avenc_aac ! mux. mux. ! filesink location=test.ts
would create respectively:
- A pipeline named p1 consisting on a simple videotestsrc display
- A pipeline named p2 consisting on a single element (playbin), which is enough to do playback of a file
- 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:
create /pipelines p1 videotestsrc ! autovideosink create /pipelines p2 playbin 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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
pipeline_create_ref pipeline_delete_ref pipeline_play_ref 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
# Two processes pid1 and pid2 share a source pipeline p0 # Both processes create the pipeline only if it doesn't exist pipeline_create p0 ... pipeline_play p0 ... # Use the pipeline ... # Then both processes delete the pipeline if it is running pipeline_stop p0 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
# Two processes pid1 and pid2 share a source pipeline p0 # Both processes call create and play with refcount # The first process will create and play the pipeline (refcount = 1) # The second process will only increase the reference count by 1 (refcount = 2) pipeline_create_ref p0 ... pipeline_play_ref p0 ... # Use the pipeline ... # Both processes call stop and delete with refcount # The first process will not stop or delete the pipeline because the refcount is 2 # It will only decrease the reference count by 1 (refcount = 1) # The second process will stop and delete the pipeline pipeline_stop_ref p0 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. |