GStreamer Daemon - JavaScript API

From RidgeRun Developer Wiki


Previous: Python API Index Next: HTTP API


GStreamer Daemon
GStreamer Daemon
GStreamer Daemon Basics
Building GStreamer Daemon
Quick Start Guide
Interacting with Pipelines
Modifying Element Properties
Sending Events
Receiving Messages from the Bus
Receiving Signals
Enabling the Debug Subsystem
Low-level Implementation for Applications
Response Format
API Reference
Simple Examples
Advanced Examples
API Examples
Troubleshooting
Releases
Licensing
FAQ
Contact Us



The GStreamer Daemon JavaScript Client is a package that 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

The JavaScript Binding is stored in our public repository (libgstc.js). It can be directly integrated from this source to your project.

A web page can integrate this source by adding: 

<script src="https://rawcdn.githack.com/RidgeRun/gstd-1.x/feature/http-server-script/libgstc/javascript/libgstc.js"></script>

Package Components

GstdClient Class

The main module of the package. It implements JavaScript 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 javascript 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.

Async HTTP Request (fetch)

This class uses Fetch API to create an HTTP request. This is an asynchronous call at JavaScript. It returns a promise. The user can handle this promise in two ways:

  • .then();
  • await

The second approach is the most simple of all. A usage example is: 

var res = await gstc.list_pipelines();
console.log(res);

Exceptions

The GstdError & GstcError are small classes that contain all the exception classes for the package.

  • GstdError: Triggered when Gstd fails to process a request.
  • GstcError: Triggered when GstClient fails.

JavaScript Package Documentation

GstdClient

GstdClient(ip='http://localhost', port=5000)

Constructor Class used as a client to communicate with the GStreamer Daemon over HTTP requests.

  • Parameters
    • ip (String): Gstd IP to connect.
    • port (String): Gstd Port to connect.

create(uri, name, description)

Create a resource at the given URI.

  • Parameters
    • uri (String): Resource URI.
    • name (String): Resource Name.
    • description (String): Resource Description. Can be null.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

read(uri)

Read the resource held at the given URI with the given name.

  • Parameters
    • uri (String): Resource URI.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

update(uri, description)

Update the resource at the given URI.

  • Parameters
    • uri (String): Resource URI.
    • description (String): Resource Description.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

delete(uri, name)

Delete the resource held at the given URI with the given name.

  • Parameters
    • uri (String): Resource URI.
    • name (String): Resource Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

list_pipelines()

List Pipelines.

  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_create(pipe_name, pipe_desc)

Pipeline Create.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • pipe_desc (String): Pipeline Description (same as gst-launch-1.0).
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_play(pipe_name)

Pipeline Play.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

element_set(pipe_name, element, prop, value)

Element Set.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
    • prop (String): Property Name.
    • value (String): Property value.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_pause(pipe_name)

Pipeline Pause.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_stop(pipe_name)

Pipeline Stop.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_delete(pipe_name)

Pipeline Delete.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

bus_filter(pipe_name, filter)

Select the types of messages to be read from the bus. Separate with a ‘+’, i.e.: eos+warning+error.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • filter (String): Bus Filter.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

bus_read(pipe_name)

Bus Read.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

bus_timeout(pipe_name, timeout)

Apply a timeout for the bus polling.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • timeout (Integer): Timeout in nanoseconds. -1: forever, 0: return immediately, n: waits for n nanoseconds.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

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): Pipeline Name.
    • rate (Float): The new playback rate. Default value: 1.0.
    • format (Integer): The format of the seek values. Default value: 3.
    • flags (Integer): The optional seek flags. Default value: 1.
    • start_type (Integer): The type and flags for the new start position. Default value: 1.
    • start (Integer): The value of the new start position. Default value: 0.
    • end_type (Integer): The type and flags for the new end position. Default value: 1.
    • end (Integer): The value of the new end position. Default value: -1.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

debug_color (enable)

Enable/Disable colors in the debug logging.

  • Parameters
    • enable (Boolean): Enable color in the debug.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

debug_enable(enable)

Enable/Disable GStreamer's debug.

  • Parameters
    • enable (Boolean): Enable GStreamer's debug.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

debug_reset(enable)

Enable/Disable debug threshold reset.

  • Parameters
    • enable (Boolean): Reset the debug threshold.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

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
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
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

element_get(pipe_name, element, prop)

Queries a property in an element of a given pipeline.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
    • prop (String): Property to query.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

list_elements(pipe_name)

List the elements in a given pipeline.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

list_properties(pipe_name, element)

List the properties of an element in a given pipeline.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

list_signals(pipe_name, element)

List the signals of an element in a given pipeline.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

signal_connect(pipe_name, element, signal)

Connect to an element signal and wait.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
    • signal (String): Signal Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

signal_disconnect(pipe_name, element, signal)

Disconnect from the signal.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
    • signal (String): Signal Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

signal_timeout(pipe_name, element, signal, timeout)

Apply a timeout for the signal waiting.

  • Parameters
    • pipe_name (String): Pipeline Name.
    • element (String): Element Name.
    • signal (String): Signal Name.
    • timeout (Integer): Timeout in microseconds. -1: forever, 0: return immediately, n: wait n microseconds.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

event_eos(pipe_name)

Send an end-of-stream event.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

event_flush_start(pipe_name)

Put the pipeline in flushing mode.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

event_flush_stop(pipe_name)

Take the pipeline out from flushing mode.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_get_graph(pipe_name)

Get the graph of the pipeline named name the graph is in GraphViz dot format.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

pipeline_verbose(pipe_name, enable)

Enable/disable the verbose mode of the pipeline named name. Verbose mode is like the -v option on gst-launch. Only supported on GST Version >= 1.10.

  • Parameters
    • pipe_name (String): Pipeline Name.
  • Throws
    • GstdError: Triggered when Gstd fails to process a request.
    • GstcError: Triggered when GstClient fails.
  • Return
    • object: Response from Gstd.

GstdError & GstcError Exceptions

The GstdClient Class handlers internally the exceptions. This class raises two types of exceptions.

GstcError

Triggered when GstClient fails internally.

GSTC_OK 0
GSTC_NULL_ARGUMENT -1
GSTC_UNREACHABLE -2
GSTC_TIMEOUT -3
GSTC_OOM -4
GSTC_TYPE_ERROR -5
GSTC_MALFORMED -6
GSTC_NOT_FOUND -7
GSTC_SEND_ERROR -8
GSTC_RECV_ERROR -9
GSTC_SOCKET_ERROR -10
GSTC_THREAD_ERROR -11
GSTC_BUS_TIMEOUT -12
GSTC_SOCKET_TIMEOUT -13

GstdError

Triggered when Gstd fails to process a request. It contains:

  • code: Gstd Error Code.
  • description: Gstd Error Description.

Examples

It is assumed for all the examples that GstD is already running in localhost port 5000: 

sudo gstd --enable-http-protocol --http-port=5000

playing a simple pipeline

This example illustrates how to create and play a simple Gstreamer pipeline 

<!doctype html>

<html lang="en">
<head>
  <meta charset="utf-8" name="description" content="JavaScript Client Herald">
  <title>HTTP Frontend</title>
</head>

<body>
  <h1>Front End</h1>
  <script src="https://rawcdn.githack.com/RidgeRun/gstd-1.x/feature/http-server-script/libgstc/javascript/libgstc.js"></script>

  <button class="buttonListPipes" onclick="listPipesClicked()">List Pipelines</button>
  <button class="buttonCreatePipes" onclick="createPipelineClicked()">Create
  Pipeline</button>
  <button class="buttonPlay" onclick="playClicked()">Play
  Pipeline</button>
  <button class="buttonStop" onclick="stopClicked()">Stop
  Pipeline</button>
  <button class="buttonDelete" onclick="deletePipelineClicked()">Delete
  Pipeline</button>
  <script>
    var gstc = new GstdClient();
    async function listPipesClicked() {
      var res = await gstc.list_pipelines();
      console.log(res);
    }
    async function createPipelineClicked() {
      var res = await gstc.pipeline_create("p0",
      "videotestsrc name=videotestsrc0 ! identity name=identity0 ! autovideosink");
      console.log(res);
    }
    async function playClicked() {
      var res = await gstc.pipeline_play("p0");
      console.log(res);
    }
    async function stopClicked() {
      var res = await gstc.pipeline_stop("p0");
      console.log(res);
    }
    async function deletePipelineClicked() {
      var res = await gstc.pipeline_delete("p0");
      console.log(res);
    }
  </script>
</body>
</html>


Previous: Python API Index Next: HTTP API


Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=GStreamer_Daemon_-_JavaScript_API&oldid=32421"