GStreamer Daemon - HTTP API
The GStreamer Daemon HTTP API provides bindings for the main functionalities of the GStreamer Daemon. It performs HTTP requests to communicate with the daemon, but the implementation is abstract enough that the inter-process communication method can be changed with minimal modifications.
Getting Started
GStreamer Daemon has built-in the support to accept HTTP requests. To enable this mode, it can be executed as:
gstd --enable-http-protocol
The address and port to recieve petitions can be customized. By default it will listen at 127.0.0.1:5000.
gstd --enable-http-protocol --http-address=127.0.0.1 --http-port=5000
For the rest of this documentation, the default settings will be used. This means that the following variables are used:
ADDRESS=127.0.0.1 PORT=5000
HTTP Requets API Documentation
These verbs are compatible with the GStreamer Daemon - Low-level Implementation for Applications.
NOTE: It is important to know that GSTD uses the verbs of CRUD Paradigm, the following table shows the equivalent verbs between CRUD and HTTP. |
CRUD | HTTP |
---|---|
CREATE | POST |
READ | GET |
UPDATE | PUT |
DELETE | DELETE |
Each HTTP must start with the address, then the port, and then the verb. For example, the action list_pipelines is performed in the following way:
http://ADDRESS:PORT/pipelines/
GET
List Pipelines
http://ADDRESS:PORT/pipelines
List the pipelines in the session.
Returns
- JSON Response from Gstd.
Get Pipeline Graph
http://ADDRESS:PORT/pipelines/<name>/graph
Get the graph of the pipeline named name the graph is in GraphViz dot format.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
List Elements
http://ADDRESS:PORT/pipelines/<name>/elements/
List the elements in the pipelines in the session.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
List Properties
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/properties
List the properties in the element of the pipeline.
Parameters
- name: name of the pipeline.
- name: name of the element in the pipeline.
Returns
- JSON Response from Gstd.
Element Get
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/properties/<property>
Reads the value of the property of the element in pipeline.
Parameters
- name: name of the pipeline.
- element: name of the element in the pipeline.
- property: property of the element to read.
Returns
- JSON Response from Gstd.
Bus Read
http://ADDRESS:PORT/pipelines/<name>/bus/message
Read the bus messages in the pipeline name.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
List Signals
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/signals
List the signals of an element in a given pipeline.
Parameters
- name: name of the pipeline.
- element: Element Name.
Returns
- JSON Response from Gstd.
Signal Connect
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/signals/<signal>/callback
Connect to the signal.
Parameters
- name: name of the pipeline.
- element: Element Name.
- signal: Signal to connect.
Returns
- JSON Response from Gstd.
Signal Disconnect
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/signals/<signal>/disconnect
Disconnect from the signal.
Parameters
- name: name of the pipeline.
- element: Element Name.
- signal: Signal to disconnect.
Returns
- JSON Response from Gstd.
POST
Create Pipeline
http://ADDRESS:PORT/pipelines?name=<name>&description=<description>
Creates a new pipeline named after name using the description gst-launch syntax.
Parameters
- name: name of the pipeline to create.
- description: pipeline with gst-launch syntax.
Returns
- JSON Response from Gstd.
Event EOS
http://ADDRESS:PORT/pipelines/<name>/event?name=eos
Creates a new EOS event and sends it to pipeline name.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
Event Flush Start
http://ADDRESS:PORT/pipelines/<name>/event?name=flush_start
Creates a new flush start event and sends it to pipeline name.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
Event Flush Stop
http://ADDRESS:PORT/pipelines/<name>/event?name=flush_stop
Creates a new flush stop event and sends it to pipeline name.
Parameters
- name: name of the pipeline.
Returns
- JSON Response from Gstd.
PUT
Play Pipeline
http://ADDRESS:PORT/pipelines/<name>/state?name=playing
Puts the pipeline named name in the PLAYING state.
Parameters
- name: name of the pipeline to play.
Returns
- JSON Response from Gstd.
Element Set
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/properties/<property>?name=<value>
Sets the value of the property of the element in pipeline.
Parameters
- name: name of the pipeline to play.
- element: name of the element in the pipeline.
- property: property of the element to set.
- value: value to set in the property.
Returns
- JSON Response from Gstd.
Pause Pipeline
http://ADDRESS:PORT/pipelines/<name>/state?name=paused
Puts the pipeline named name in the PAUSED state.
Parameters
- name: name of the pipeline to pause.
Returns
- JSON Response from Gstd.
Stop Pipeline
http://ADDRESS:PORT/pipelines/<name>/state?name=null
Puts the pipeline named name in the NULL state.
Parameters
- name: name of the pipeline to stop.
Returns
- JSON Response from Gstd.
Pipeline Verbose
http://ADDRESS:PORT/pipelines/<name>/verbose?name=<value>
Enable/disable the verbose mode of the pipeline named name. Verbose mode is like the -v option on gst-launch.
Parameters
- name: name of the pipeline to play.
- value: true or false, to enable or disable.
Returns
- JSON Response from Gstd.
Debug Enable
http://ADDRESS:PORT/debug/enable?name=<value>
Enable or Disable the debug.
Parameters
- value: value to enable or disable the debug (true/false).
Returns
- JSON Response from Gstd.
Debug Reset
http://ADDRESS:PORT/debug/reset?name=<value>
Clear previously set debug thresholds.
Parameters
- value: value to reset the debug (true/false).
Returns
- JSON Response from Gstd.
Debug Threshold
http://ADDRESS:PORT/debug/threshold?name=<value>
Define the level of the debug.
Parameters
- value: value of the level of debug.
0 | none | No debug information is output |
1 | ERROR | Logs all fatal errors |
2 | WARNING | Logs all warnings |
3 | FIXME | Logs all "fixme" messages |
4 | INFO | Logs all informational messages |
5 | DEBUG | Logs all debug messages |
6 | LOG | Logs all log messages |
7 | TRACE | Logs all trace messages |
9 | MEMDUMP | Logs all memory dump messages |
Returns
- JSON Response from Gstd.
Debug Color
http://ADDRESS:PORT/debug/color?name=<value>
Enable or Disable the color on the debug log.
Parameters
- value: value to enable or disable the color in the debug (true/false).
Returns
- JSON Response from Gstd.
Bus Timeout
http://ADDRESS:PORT/pipelines/<name>/bus/timeout?name=<time_ns>
Sets the timeout of the bus in the pipeline name.
Parameters
- name: name of the pipeline.
- time_ns: time of the timeout in nanoseconds (-1 for infinite timeout).
Returns
- JSON Response from Gstd.
Bus Filter
http://ADDRESS:PORT/pipelines/<name>/bus/types?name=<filter>
Filter the bus messages in the pipeline name.
Parameters
- name: name of the pipeline.
- filter: name of the filter of the bus in the pipeline.
Returns
- JSON Response from Gstd.
Event Seek
http://ADDRESS:PORT/pipelines/<name>/event?name=seek&description=<rate> <format> <flags> <start-type> <start> <end-type> <end>
Creates a new seek event and sends it to pipeline name.
Parameters
- name: name of the pipeline.
- rate: The new playback rate. Default value: 1.0.
- format: The format of the seek values. Default value: 3.
- flags: The optional seek flags. Default value: 1.
- start-type: The type and flags for the new start position. Default value: 1.
- start: The value of the new start position. Default value: 0.
- end-type: The type and flags for the new end position. Default value: 1.
- end: The value of the new end position. Default value: -1.
Returns
- JSON Response from Gstd.
Signal Timeout
http://ADDRESS:PORT/pipelines/<name>/elements/<element>/signals/<signal>/timeout?name=<timeout>
Apply a timeout for the signal waiting.
Parameters
- name: name of the pipeline.
- element: Element Name.
- signal: Signal Name.
- timeout: Signal Timeout to apply.
Returns
- JSON Response from Gstd.
DELETE
Delete Pipeline
http://ADDRESS:PORT/pipelines?name=<name>
Delete the pipeline from its name. Parameters
- name: name of the pipeline to delete.
Returns
- JSON Response from Gstd.
Examples
Frist, execute GstD
gstd --enable-http-protocol --http-address=127.0.0.1 --http-port=5000
Then you can use an API development tool like Postman to send your requests. Some common requests are:
GET: http://127.0.0.1:5000/pipelines/ POST: http://127.0.0.1:5000/pipelines?name=p0&description=videotestsrc%20name=vts%20!%20identity%20name=id%20!%20autovideosink PUT: http://127.0.0.1:5000/pipelines/p0/state?name=playing PUT: http://127.0.0.1:5000/pipelines/p0/state?name=paused GET: http://127.0.0.1:5000/pipelines/p0/graph PUT: http://127.0.0.1:5000/pipelines/p0/state?name=null
A delete request must use the Delete Syntaxis. Development tools insert this syntaxis automatically.
DELETE: http://127.0.0.1:5000/pipelines?name=p0
NOTE: In Postman you need to select the correct HTTP verb(POST, PUT, READ, DELETE) to send the request to the server. |