Rust API

From RidgeRun Developer Wiki

Follow Us On Twitter LinkedIn Email Share this page


Previous: Python API Index Next: JavaScript 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 Rust Client, gstc_rust, is a Rust crate that provides a typed client for the main GstD operations over TCP. It can be used from standalone Cargo projects or built as part of the GstD repository. The API is designed around a single client object, Client, which exposes helpers for pipeline lifecycle, element properties, events, bus waiting, and signal handling.

Getting Started

Requirements

  • A running GstD instance. By default, the examples connect to 127.0.0.1:5000.
  • Rust and Cargo if you want to use the crate directly in a Rust project.
  • The gstc_rust crate sources from this repository.

Building inside the GstD repository

The Rust client is integrated in the repository build. From the repository root: 

meson setup build
meson compile -C build

Rust examples are built under: 

build/examples/libgstc/rust/

Using the crate with Cargo

The Rust client also includes a Cargo.toml, so it can be used in normal Cargo workflows.

From another Rust project, add it as a path dependency: 

[dependencies]
gstc_rust = { path = "/path/to/gstd-1.x/libgstc/rust/gstc" }

Then build or run as usual: 

cargo build
cargo run

Development checks

From the repository root: 

cargo fmt --manifest-path libgstc/rust/gstc/Cargo.toml --all -- --check
cargo clippy --manifest-path libgstc/rust/gstc/Cargo.toml --all-targets -- -D warnings

Package Components

gstc_rust::Client

The main entry point for controlling GstD. A Client is created with: 

let client = Client::new("127.0.0.1", 5000, -1, true)?;

Constructor parameters:

  • address: IP address or host where GstD is listening.
  • port: TCP port used by GstD.
  • wait_time_ms: default timeout in milliseconds for synchronous operations. Use -1 for no read timeout.
  • keep_connection_open: when true, the client keeps the TCP connection open between commands.

gstc_rust::Status

The Rust API returns Result<T, Status> for fallible operations. Status contains GstD-compatible error codes such as:

  • Status::Ok
  • Status::NullArgument
  • Status::Unreachable
  • Status::Timeout
  • Status::Oom
  • Status::TypeError
  • Status::Malformed
  • Status::NotFound
  • Status::SendError
  • Status::RecvError
  • Status::SocketError
  • Status::ThreadError
  • Status::SocketTimeout
  • Status::BusTimeout
  • Status::LongResponse
  • Status::Unknown(code)

gstc_rust::BusMessage

Bus wait operations return a BusMessage: 

pub struct BusMessage {
    pub status: Status,
    pub raw_response: String,
}

This is useful when waiting for EOS or other messages from the pipeline bus.

Main Client Operations

The Rust client exposes methods for the most common GstD workflows:

Connection and debugging

  • ping()
  • debug(threshold, colors, reset)

Pipeline lifecycle

  • pipeline_create(pipeline_name, pipeline_desc)
  • pipeline_create_ref(pipeline_name, pipeline_desc)
  • pipeline_delete(pipeline_name)
  • pipeline_delete_ref(pipeline_name)
  • pipeline_play(pipeline_name)
  • pipeline_play_ref(pipeline_name)
  • pipeline_pause(pipeline_name)
  • pipeline_stop(pipeline_name)
  • pipeline_stop_ref(pipeline_name)
  • pipeline_get_state(pipeline_name)
  • pipeline_get_graph(pipeline_name)
  • pipeline_verbose(pipeline_name, value)
  • pipeline_list()
  • pipeline_list_elements(pipeline_name)

Element property operations

  • element_get(pipeline_name, element, property)
  • element_set(pipeline_name, element, property, value)
  • element_properties_list(pipeline_name, element)

Events

  • pipeline_flush_start(pipeline_name)
  • pipeline_flush_stop(pipeline_name, reset)
  • pipeline_inject_eos(pipeline_name)
  • pipeline_seek(pipeline_name, rate, format, flags, start_type, start, stop_type, stop)

Bus operations

  • pipeline_bus_wait(pipeline_name, message_name, timeout_ns)
  • pipeline_bus_wait_async(pipeline_name, message_name, timeout_ns, callback)

Signals and actions

  • pipeline_list_signals(pipeline_name, element)
  • pipeline_signal_connect(pipeline_name, element, signal, timeout)
  • pipeline_signal_disconnect(pipeline_name, element, signal)
  • pipeline_emit_action(pipeline_name, element, action)

API Reference

Client::new(address, port, wait_time_ms, keep_connection_open)

Creates a new Rust client connected to GstD.

Parameters:

  • address: server IP address or hostname, for example 127.0.0.1.
  • port: TCP port used by GstD, usually 5000.
  • wait_time_ms: default timeout in milliseconds for synchronous commands. Use -1 to disable the read timeout.
  • keep_connection_open: if true, the client keeps the TCP socket open between operations. If false, a new connection is used per request.

Returns:

  • Result<Client, Status>. On success, returns a ready-to-use client instance.

ping()

Checks whether GstD is reachable and responding.

Parameters:

  • This function takes no parameters.

Returns:

  • Result<(), Status>. Returns Ok(()) when GstD responds successfully.

debug(threshold, colors, reset)

Configures the GstD debug subsystem.

Parameters:

  • threshold: debug threshold string such as ERROR, WARNING, INFO, or DEBUG.
  • colors: when true, enables colored debug output.
  • reset: when true, requests resetting the debug configuration.

Returns:

  • Result<(), Status>. Returns Ok(()) when all debug updates succeed.

pipeline_create(pipeline_name, pipeline_desc)

Creates a new pipeline in GstD.

Parameters:

  • pipeline_name: logical name to assign to the pipeline.
  • pipeline_desc: GStreamer pipeline description string, for example videotestsrc ! autovideosink.

Returns:

  • Result<(), Status>. Returns Ok(()) when the pipeline is created successfully.

pipeline_delete(pipeline_name)

Deletes a pipeline from GstD.

Parameters:

  • pipeline_name: name of the pipeline to delete.

Returns:

  • Result<(), Status>. Returns Ok(()) when the pipeline is deleted.

pipeline_create_ref(pipeline_name, pipeline_desc)

Creates a pipeline through the daemon reference command interface.

Parameters:

  • pipeline_name: logical name to assign to the pipeline.
  • pipeline_desc: GStreamer pipeline description string.

Returns:

  • Result<(), Status>. Returns Ok(()) when the command succeeds.

pipeline_delete_ref(pipeline_name)

Deletes a pipeline through the daemon reference command interface.

Parameters:

  • pipeline_name: name of the pipeline to delete.

Returns:

  • Result<(), Status>. Returns Ok(()) when the command succeeds.

pipeline_play(pipeline_name)

Sets a pipeline to the PLAYING state.

Parameters:

  • pipeline_name: pipeline to start.

Returns:

  • Result<(), Status>. Returns Ok(()) when the pipeline enters the requested state.

pipeline_pause(pipeline_name)

Sets a pipeline to the PAUSED state.

Parameters:

  • pipeline_name: pipeline to pause.

Returns:

  • Result<(), Status>. Returns Ok(()) when the pipeline is paused.

pipeline_play_ref(pipeline_name)

Sets a pipeline to PLAYING through the daemon reference command interface.

Parameters:

  • pipeline_name: pipeline to start.

Returns:

  • Result<(), Status>. Returns Ok(()) when the command succeeds.

pipeline_stop(pipeline_name)

Sets a pipeline to the NULL state.

Parameters:

  • pipeline_name: pipeline to stop.

Returns:

  • Result<(), Status>. Returns Ok(()) when the pipeline is moved to NULL.

pipeline_stop_ref(pipeline_name)

Sets a pipeline to NULL through the daemon reference command interface.

Parameters:

  • pipeline_name: pipeline to stop.

Returns:

  • Result<(), Status>. Returns Ok(()) when the command succeeds.

pipeline_get_graph(pipeline_name)

Returns the graph description for a pipeline.

Parameters:

  • pipeline_name: pipeline whose graph should be queried.

Returns:

  • Result<String, Status>. On success, returns the graph representation reported by GstD.

pipeline_get_state(pipeline_name)

Reads the current pipeline state from GstD.

Parameters:

  • pipeline_name: pipeline whose state should be queried.

Returns:

  • Result<String, Status>. On success, returns the state string such as PLAYING, PAUSED, or NULL.

pipeline_verbose(pipeline_name, value)

Enables or disables verbose mode for a pipeline.

Parameters:

  • pipeline_name: target pipeline.
  • value: true to enable verbose mode, false to disable it.

Returns:

  • Result<(), Status>. Returns Ok(()) when verbose mode is updated successfully.

element_get(pipeline_name, element, property)

Reads a property value from an element in a pipeline.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: element name inside the pipeline.
  • property: property name to read.

Returns:

  • Result<String, Status>. On success, returns the property value as a string.

element_set(pipeline_name, element, property, value)

Writes a property value on an element in a pipeline.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: element name inside the pipeline.
  • property: property name to update.
  • value: new property value encoded as text.

Returns:

  • Result<(), Status>. The current implementation always returns Ok(()) after sending the update request.

element_properties_list(pipeline_name, element)

Lists the properties available on an element.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: element whose properties should be listed.

Returns:

  • Result<Vec<String>, Status>. On success, returns the list of property names.

pipeline_flush_start(pipeline_name)

Sends a flush_start event to a pipeline.

Parameters:

  • pipeline_name: target pipeline.

Returns:

  • Result<(), Status>. Returns Ok(()) when the event is sent successfully.

pipeline_flush_stop(pipeline_name, reset)

Sends a flush_stop event to a pipeline.

Parameters:

  • pipeline_name: target pipeline.
  • reset: when true, requests a reset as part of the flush stop event.

Returns:

  • Result<(), Status>. Returns Ok(()) when the event is sent successfully.

pipeline_inject_eos(pipeline_name)

Injects an EOS event into the pipeline.

Parameters:

  • pipeline_name: target pipeline.

Returns:

  • Result<(), Status>. Returns Ok(()) when the EOS event is injected successfully.

pipeline_seek(pipeline_name, rate, format, flags, start_type, start, stop_type, stop)

Sends a seek event using the values expected by GstD.

Parameters:

  • pipeline_name: pipeline that will receive the seek event.
  • rate: playback rate, for example 1.0 for normal speed.
  • format: GStreamer seek format as an integer, commonly 3 for time.
  • flags: seek flags encoded as an integer.
  • start_type: seek start type encoded as an integer.
  • start: seek start position.
  • stop_type: seek stop type encoded as an integer.
  • stop: seek stop position.

Returns:

  • Result<(), Status>. Returns Ok(()) when the seek event is sent successfully.

pipeline_list_elements(pipeline_name)

Lists the elements contained in a pipeline.

Parameters:

  • pipeline_name: pipeline to inspect.

Returns:

  • Result<Vec<String>, Status>. On success, returns the list of element names.

pipeline_list()

Lists all current pipelines in GstD.

Parameters:

  • This function takes no parameters.

Returns:

  • Result<Vec<String>, Status>. On success, returns the list of pipeline names.

pipeline_bus_wait(pipeline_name, message_name, timeout_ns)

Waits synchronously for a bus message and returns a BusMessage.

Parameters:

  • pipeline_name: pipeline whose bus should be monitored.
  • message_name: name of the bus message to wait for, for example eos.
  • timeout_ns: timeout in nanoseconds. Use -1 to wait indefinitely.

Returns:

  • Result<BusMessage, Status>. On success, returns a BusMessage containing both the derived status and the raw response.

pipeline_bus_wait_async(pipeline_name, message_name, timeout_ns, callback)

Starts a background thread that waits for a bus message and then invokes a callback.

Parameters:

  • pipeline_name: pipeline whose bus should be monitored. This API takes an owned String.
  • message_name: bus message name to wait for. This API takes an owned String.
  • timeout_ns: timeout in nanoseconds. Use -1 to wait indefinitely.
  • callback: closure invoked with a BusMessage once the wait finishes.

Returns:

  • Result<JoinHandle<Status>, Status>. On success, returns a thread handle that can be joined to obtain the final Status.

pipeline_emit_action(pipeline_name, element, action)

Emits an element action through GstD.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: target element name.
  • action: action name to emit.

Returns:

  • Result<(), Status>. Returns Ok(()) when the action is emitted successfully.

pipeline_list_signals(pipeline_name, element)

Lists the signals exposed by an element.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: element whose signals should be listed.

Returns:

  • Result<Vec<String>, Status>. On success, returns the list of signal names.

pipeline_signal_connect(pipeline_name, element, signal, timeout)

Connects to an element signal and returns the raw callback response from GstD.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: target element name.
  • signal: signal name to connect.
  • timeout: timeout value configured for the signal callback operation.

Returns:

  • Result<String, Status>. On success, returns the raw JSON response string from GstD.

pipeline_signal_disconnect(pipeline_name, element, signal)

Disconnects a previously connected element signal.

Parameters:

  • pipeline_name: pipeline containing the element.
  • element: target element name.
  • signal: signal name to disconnect.

Returns:

  • Result<(), Status>. Returns Ok(()) when the disconnect command succeeds.

Using the Rust API in a Project

Minimal example

This example connects to GstD, creates a pipeline, starts it, and then deletes it. 

use gstc_rust::{Client, Status};

fn main() -> Result<(), Status> {
    let client = Client::new("127.0.0.1", 5000, -1, true)?;

    client.ping()?;
    client.pipeline_create("pipe", "videotestsrc ! autovideosink")?;
    client.pipeline_play("pipe")?;

    client.pipeline_stop("pipe")?;
    client.pipeline_delete("pipe")?;

    Ok(())
}

Cargo project layout

One possible project structure is: 

my-gstd-app/
├── Cargo.toml
└── src/
    └── main.rs

Example Cargo.toml: 

[package]
name = "my-gstd-app"
version = "0.1.0"
edition = "2021"

[dependencies]
gstc_rust = { path = "/path/to/gstd-1.x/libgstc/rust/gstc" }

Examples

Playing a simple pipeline

This is the simplest workflow and is based on the repository example: 

use gstc_rust::{Client, Status};

fn main() -> Result<(), Status> {
    let client = Client::new("127.0.0.1", 5000, -1, true)?;

    client.pipeline_create("pipe", "videotestsrc ! autovideosink")?;
    client.pipeline_play("pipe")?;

    println!("Pipeline is running. Press Ctrl+C to stop.");
    std::thread::sleep(std::time::Duration::from_secs(5));

    client.pipeline_stop("pipe")?;
    client.pipeline_delete("pipe")?;

    Ok(())
}

Reading and changing an element property

You can inspect and update element properties through GstD: 

use gstc_rust::{Client, Status};

fn main() -> Result<(), Status> {
    let client = Client::new("127.0.0.1", 5000, -1, true)?;

    client.pipeline_create("pipe", "videotestsrc name=vts ! autovideosink")?;
    client.pipeline_play("pipe")?;

    let current = client.element_get("pipe", "vts", "pattern")?;
    println!("Current pattern: {}", current);

    client.element_set("pipe", "vts", "pattern", "1")?;
    println!("Pattern updated");

    client.pipeline_stop("pipe")?;
    client.pipeline_delete("pipe")?;

    Ok(())
}

Waiting for EOS on the bus

This pattern is useful for finite pipelines: 

use gstc_rust::{Client, Status};

fn main() -> Result<(), Status> {
    let client = Client::new("127.0.0.1", 5000, 5000, false)?;

    client.pipeline_create(
        "video",
        "videotestsrc num-buffers=300 ! videoconvert ! autovideosink",
    )?;
    client.pipeline_play("video")?;

    let bus_message = client.pipeline_bus_wait("video", "eos", -1)?;
    if bus_message.status == Status::Ok {
        println!("EOS received");
    } else {
        eprintln!("Bus wait failed: {}", bus_message.status);
    }

    client.pipeline_stop("video")?;
    client.pipeline_delete("video")?;

    Ok(())
}

Waiting for a pipeline to reach a state

Some applications need to poll until a state transition is completed: 

use gstc_rust::{Client, Status};
use std::thread;
use std::time::{Duration, Instant};

fn wait_for_state(
    client: &Client,
    pipeline_name: &str,
    expected: &str,
    timeout: Duration,
) -> Result<String, Status> {
    let start = Instant::now();
    loop {
        let state = client.pipeline_get_state(pipeline_name)?;
        if state == expected {
            return Ok(state);
        }

        if start.elapsed() >= timeout {
            return Err(Status::Timeout);
        }

        thread::sleep(Duration::from_millis(100));
    }
}

Asynchronous bus wait

The Rust client also supports waiting for bus messages in a background thread: 

use gstc_rust::{Client, Status};

fn main() -> Result<(), Status> {
    let client = Client::new("127.0.0.1", 5000, -1, true)?;

    client.pipeline_create("pipe", "videotestsrc num-buffers=5 ! fakesink")?;
    client.pipeline_play("pipe")?;

    let handle = client.pipeline_bus_wait_async(
        "pipe".to_string(),
        "eos".to_string(),
        -1,
        |message| {
            println!("Bus callback status: {}", message.status);
            println!("Raw response: {}", message.raw_response);
        },
    )?;

    let final_status = handle.join().map_err(|_| Status::ThreadError)?;
    println!("Thread finished with status {}", final_status);

    client.pipeline_stop("pipe")?;
    client.pipeline_delete("pipe")?;

    Ok(())
}

Repository Example Programs

The repository currently includes these Rust examples:

  • examples/libgstc/rust/simple_pipeline_rust.rs
  • examples/libgstc/rust/pipeline_lifecycle_rust.rs
  • examples/libgstc/rust/wait_on_bus_rust.rs
  • examples/libgstc/rust/dynamic_property_change_rust.rs
  • examples/libgstc/rust/gapless_playback_rust.rs
  • examples/libgstc/rust/mp4_recording_rust.rs

They can be built with Cargo using the crate manifest: 

cargo build --manifest-path libgstc/rust/gstc/Cargo.toml --examples

Or run individually: 

cargo run --manifest-path libgstc/rust/gstc/Cargo.toml --example simple_pipeline

Notes

  • The Rust client communicates with GstD over TCP.
  • Most client methods return Result<..., Status>, so normal Rust error propagation with ? works naturally.
  • For synchronous control-heavy applications, keep_connection_open=true can reduce reconnect overhead.
  • For finite playback or recording scenarios, pipeline_bus_wait() is useful to wait for EOS.



Previous: Python API Index Next: JavaScript API


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