GStreamer Daemon - Python API
The GStreamer Daemon Python Client or pygstc is a Python package that provides bindings for the main functionalities of the GStreamer Daemon. It uses a TCP socket to communicate with the daemon, but the implementation is abstract enough that the inter-process communication method can be changed with minimal modifications. It also includes a logger class, based in the Python logging module, that can be used or extended in other applications.
Getting Started
The pygstc package is installed by default in the current Python 3 environment during GstD installation:
cd <gstd_base> sudo make install
You can also install it without installing the rest of the GstD components by running setup.py or pip3 in libgstc folder (may require sudo depending on your environment configuration):
cd <gstd_base>/libgstc/python ./setup.py install
or
cd <gstd_base>/libgstc/python pip3 install .
Note: We recommend to use the setup.py script to install the package in the correct module path.
The pygstc unit tests are integrated with GstD tests. To run them, use the make check command (this requires having pygstc installed beforehand):
cd <gstd_base> make check
Finally, you can check pygstc installation by running python and importing the package:
$ python Python 3.5.6 |Anaconda, Inc.| (default, Aug 26 2018, 21:41:56) [GCC 7.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import pygstc >>>
Troubleshooting
When installing with pip3 install option the installation path can differ from the modules path. The error looks like:
Traceback (most recent call last):
from pygstc.gstc import GstdClient
ModuleNotFoundError: No module named 'pygstc'
To avoid errors with the installing path use the setup.py script to install.
Package Components
gstc module
The main module of the package. It implements python bindings for the main GstD functionalities. The method names and parameters are based in the command line GstD client (gstd-client). If you have experience with that, using the python bindings will be trivial. Besides the command line methods, it only implements one other public method: ping_gstd, which can be used to check if GstD is running in a given IP and PORT. The client can also be used to control daemons running in other IP address, just make sure that anonymous TCP messages are not blocked by the network policies.
gstcerror module
This is a small module that contains all the exception classes for the package.
logger module
A logger module, based in the Python logging module, that can be used or extended in other applications. It contains two classes: the CustomLogger and the DummyLogger. The idea is that both of these classes present the same interface and the GstdClient class receives any of them as a constructor parameter(it uses the DummyLogger by default).
DummyLogger: Has the same methods asCustomLoggerbut discards all messagesCustomLogger: An extension to logging.logger that adds easier configuration options and colored logs. It has two default log handlers: a console logger (used by default) and a file logger (used if you pass thelogfileparameter to the constructor). You can also pass a custom log handler using theset_handlermethod
tcp module
This module implements a simple TCP socket to communicate with GstD. It is a unidirectional socket that sends messages and then waits for a response.
pygstc Package Documentation
pygstc.gstc module
-
class
pygstc.gstc.GstdClient(ip='localhost', port=5000, logger=None, timeout=0) Bases:
objectClass used as client to comunicate with the GStreamer Daemon over an abstract inter-process communication class.
-
action_emit(pipe_name, element, , action) Emit an action to the element (actions with parameters are not supported yet)
-
bus_filter(pipe_name, filter) Select the types of message to be read from the bus. Separate with a ‘+’, i.e.: eos+warning+error.
-
bus_read(pipe_name) Read the bus and wait.
-
bus_timeout(pipe_name, timeout) Apply a timeout for the bus polling.
-
create(uri, property, value) Create a resource at the given URI.
-
debug_color(colors) Enable/Disable colors in the debug logging.
-
debug_enable(enable) Enable/Disable GStreamer debug.
-
debug_reset(reset) Enable/Disable debug threshold reset.
-
debug_threshold(threshold) The debug filter to apply (as you would use with gst-launch).
- Parameters
threshold (string) – Debug threshold:
0 none No debug information is output. 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. - Raises
-
delete(uri, name) Delete the resource held at the given URI with the given name.
-
element_get(pipe_name, element, prop) Queries a property in an element of a given pipeline.
- Parameters
pipe_name (string) – The name of the pipeline
element (string) – The name of the element
prop (string) – The name of the property
- Raises
- Returns
result – Command response
- Return type
string
-
element_set(pipe_name, element, prop, value) Set a property in an element of a given pipeline.
- Parameters
pipe_name (string) – The name of the pipeline
element (string) – The name of the element
prop (string) – The name of the property
value (string) – The value to set
- Raises
-
event_eos(pipe_name) Send an end-of-stream event.
-
event_flush_start(pipe_name) Put the pipeline in flushing mode.
-
event_flush_stop(pipe_name, reset=True) Take the pipeline out from flushing mode.
-
event_seek(pipe_name, rate=1.0, format=3, flags=1, start_type=1, start=0, end_type=1, end=-1) Perform a seek in the given pipeline
- Parameters
pipe_name (string) – The name of the pipeline
rate (float) – The new playback rate. Default value: 1.0.
format (int) – The format of the seek values. Default value: 3.
flags (int) – The optional seek flags. Default value: 1.
start_type (int) – The type and flags for the new start position. Default value: 1.
start (int) – The value of the new start position. Default value: 0.
end_type (int) – The type and flags for the new end position. Default value: 1.
end (int) – The value of the new end position. Default value: -1.
- Raises
-
list_elements(pipe_name) List the elements in a given pipeline.
-
list_pipelines() List the existing pipelines
-
list_properties(pipe_name, element) List the properties of an element in a given pipeline.
-
list_signals(pipe_name, element) List the signals of an element in a given pipeline.
-
ping_gstd() Test if GSTD responds in the configured address and port
- Returns
result – Whether or not GSTD responds
- Return type
bool
-
pipeline_create(pipe_name, pipe_desc) Create a new pipeline based on the name and description.
- Parameters
pipe_name (string) – The name of the pipeline
pipe_desc (string) – Pipeline description (same as gst-launch-1.0)
-
pipeline_delete(pipe_name) Delete the pipeline with the given name.
-
pipeline_get_graph(pipe_name) Get the graph of the pipeline named name the graph is in GraphViz dot format.
- Returns
result – Pipeline graph in GraphViz dot format
- Return type
string
-
-
pipeline_verbose(pipe_name, value) Enable/disable the verbose mode of the pipeline named name.
Verbose mode is like the -v option on gst-launch.
-
pipeline_pause(pipe_name) Set the pipeline to paused.
-
pipeline_play(pipe_name) Set the pipeline to playing.
-
pipeline_stop(pipe_name) Set the pipeline to null.
-
read(uri) Read the resource held at the given URI with the given name.
-
signal_connect(pipe_name, element, signal) Connect to signal and wait.
- Parameters
pipe_name (string) – The name of the pipeline
element (string) – The name of the element
signal (string) – The name of the signal
- Raises
- Returns
result – Command response
- Return type
string
-
signal_disconnect(pipe_name, element, signal) Disconnect from signal.
-
signal_timeout(pipe_name, element, signal, timeout) Apply a timeout for the signal waiting.
- Parameters
pipe_name (string) – The name of the pipeline
element (string) – The name of the element
signal (string) – The name of the signal
timeout (int) – Timeout in nanosecons. -1: forever, 0: return immediately, n: wait n microseconds.
- Raises
-
update(uri, value) Update the resource at the given URI.
pygstc.gstcerror module
GSTC - GstdError Class
-
exception
pygstc.gstcerror.GstcError Bases:
ExceptionRaised when the Gstd python client fails internally
-
exception
pygstc.gstcerror.GstdError Bases:
ExceptionRaised when Gstd IPC fails
pygstc.logger module
-
pygstc.logger.COLORS= {'CRITICAL': '35m', 'DEBUG': '34m', 'ERROR': '31m', 'INFO': '37m', 'WARNING': '33m'} GSTC - ColorFormatter Class
-
class
pygstc.logger.ColorFormatter(msg) Bases:
logging.FormatterCustom implementation of logging Formater class.
-
format(record) Formats the log and adds colors according to the log level.
- Parameters
record (string) – Message to format
-
-
class
pygstc.logger.CustomLogger(logname, logfile=None, loglevel='ERROR') Bases:
objectCustom implementation of logging Logger class.
-
critical(log) Logs a critical level message.
- Parameters
log (string) – The message to log
-
debug(log) Logs a debug level message.
- Parameters
log (string) – The message to log
-
error(log) Logs an error level message.
- Parameters
log (string) – The message to log
-
info(log) Logs an info level message.
- Parameters
log (string) – The message to log
-
set_handler(handler) Changes the default file or console handler to a custom one passed as a parameter.
- Parameters
handler (object) – The logging handler to use
-
warning(log) Logs a warning level message.
- Parameters
log (string) – The message to log
-
-
class
pygstc.logger.DummyLogger Bases:
objectDummy implementation of the logging Logger that discards all logs.
-
critical(log) Discards the log.
-
debug(log) Discards the log.
-
error(log) Discards the log.
-
info(log) Discards the log.
-
warning(log) Discards the log.
-
pygstc.tcp module
-
class
pygstc.tcp.Ipc(logger, ip, port, maxsize=None, terminator=b'x00') Bases:
objectImplementation of IPC that uses TCP sockets to communicate with GSTD
-
send(line, timeout=0) Create a socket and sends a message through it
- Parameters
line (string) – Message to send through the socket
timeout (int) – Timeout in seconds to wait for a response. 0: infinite
- Returns
data – Decoded JSON string with the response
- Return type
string
-
Examples
It is assumed for all the examples that GstD is already running in localhost port 5000 and 5001:
gstd -p 5000 -n 2
playing a simple pipeline
This examples illustrates how to create and play a simple Gstreamer pipeline
import time
from pygstc.gstc import *
from pygstc.logger import *
pipeline = 'videotestsrc name=v0 ! fakesink'
# Create a custom logger that logs into stdout, named pygstc_example, with debug level DEBUG
gstd_logger = CustomLogger('pygstc_example', loglevel='DEBUG')
# Create the client and pass the logger as a parameter
gstd_client = GstdClient(logger=gstd_logger)
gstd_client.pipeline_create('p0', pipeline)
gstd_client.pipeline_play('p0')
# Wait for the pipeline to change state
time.sleep(0.1)
# This should print 'PLAYING'
print(gstd_client.read('pipelines/p0/state')['value'])
gstd_client.pipeline_stop('p0')
gstd_client.pipeline_delete('p0')
handling signals
This example illustrates how to use threading to connect to and handle signals.
import threading
import time
from pygstc.gstc import *
from pygstc.logger import *
#signal_connect is a blocking call, so we need to do it in a separate thread to avoid blocking the main thread.
def signal_connect_handler():
gstd_logger = CustomLogger('test_libgstc', loglevel='DEBUG')
# Create the client in a different port (5001) to avoid congestion
# You can still use port 5000, signal_connect does not block the port, only the thread
gstd_client = GstdClient(logger=gstd_logger, port=5001)
# You can do this inside a while loop to handle multiple signals
ret_val = gstd_client.signal_connect('p0', 'identity', 'handoff')
print(ret_val)
pipeline = 'videotestsrc ! identity name=identity ! fakesink'
gstd_logger = CustomLogger('pygstc_example', loglevel='DEBUG')
gstd_client = GstdClient(logger=gstd_logger)
gstd_client.pipeline_create('p0', pipeline)
gstd_client.pipeline_play('p0')
# Create the thread
signal_connect_thread = threading.Thread(target=signal_connect_handler)
ret_thr.start()
time.sleep(0.1)
# You can disconnect the signal from this thread to unlock the second thread
self.gstd_client.signal_disconnect('p0', 'identity', 'handoff')
gstd_client.pipeline_stop('p0')
gstd_client.pipeline_delete('p0')
Real Use Cases