LinuxCommandLibrary

gst-launch-1.0

Run GStreamer pipelines from command line

TLDR

Play test video in a window

$ gst-launch-1.0 videotestsrc ! xvimagesink
copy

Play a media file in a window
$ gst-launch-1.0 playbin uri=[protocol]://[host]/[path/to/file]
copy

Re-encode a media file
$ gst-launch-1.0 filesrc location=[path/to/file] ! [file_type]demux ! [codec_type]dec ! [codec_type]enc ! [file_type]mux ! filesink location=[path/to/file]
copy

Stream a file to an RTSP server
$ gst-launch-1.0 filesrc location=[path/to/file] ! rtspclientsink location=rtsp://[host_IP]/[path/to/file]
copy

SYNOPSIS

gst-launch-1.0 [OPTION...] pipeline-description

PARAMETERS

--help
    Show help options.

--version
    Show version number.

--gst-debug-level=LEVEL
    Set the debug level. (0-9, default: 2)

--gst-debug=MASK
    Set the debug mask.

Ex: GST_TRACER:GST_ELEMENT_*:3,sdp*:5

--gst-debug-no-color
    Disable colored debugging output.

--gst-debug-color-mode=MODE
    Changes the mode that is used to colorize the debugging output. Possible values: off, on, unix.

--gst-disable-seccomp
    Disable sandboxing via seccomp.

--gst-plugin-spew
    Output plugin loading details.

--gst-plugin-scanner=PROGRAM
    Run PROGRAM to scan plugins.

--gst-fatal-warnings
    Make all warnings fatal.

--gst-force-asserts
    Exit on asserts.

--gst-force-sync-signals
    Emit sync signals as events.

--duration=SECS
    Run pipeline for SECS seconds.

--dry-run
    Don't run the pipeline, just check syntax.

--verbose
    Output more debugging information.

--no-signals
    Don't catch signals.

--print-dot
    Print pipeline graph as dot file.

--print-dot-detail
    Print pipeline graph as dot file with verbose detail.

DESCRIPTION

The `gst-launch-1.0` command is a powerful tool for building and running GStreamer pipelines directly from the command line. It allows users to quickly prototype and test different media processing setups without writing any code.

It takes a pipeline description as an argument, specifying the elements, their properties, and how they are connected. GStreamer elements perform specific tasks, such as encoding, decoding, filtering, or outputting media. The `gst-launch-1.0` command parses this description, instantiates the required elements, links them together, and starts the pipeline. It provides a convenient way to experiment with GStreamer's capabilities and debug media processing issues.

This tool is commonly used for tasks like playing media files, capturing audio or video from devices, transcoding media formats, and streaming content over the network. Understanding `gst-launch-1.0` is essential for anyone working with GStreamer and building media applications on Linux systems. It offers a rapid prototyping environment, allowing developers to iterate quickly and refine their pipelines before embedding them in larger applications.

CAVEATS

The pipeline description syntax can be complex and require familiarity with GStreamer elements and their properties. Errors in the pipeline description can lead to unexpected behavior or crashes. It's important to understand the capabilities of each element and how they interact with each other.

PIPELINE DESCRIPTION

The pipeline description is a string that specifies the GStreamer elements and how they are connected. It consists of elements separated by exclamation marks (`!`).

Example: `gst-launch-1.0 videotestsrc ! autovideosink`

This pipeline creates a test video source (`videotestsrc`) and displays it in a window (`autovideosink`).

ELEMENT PROPERTIES

Elements have properties that can be set to configure their behavior. Properties are set using the format `element.property=value`.

Example: `gst-launch-1.0 videotestsrc pattern=ball ! autovideosink`

This pipeline sets the `pattern` property of the `videotestsrc` element to `ball`, which changes the test video pattern.

UNDERSTANDING CAPS

Caps (capabilities) define the media formats that elements can handle. GStreamer uses caps negotiation to determine compatible formats between elements. If caps are not compatible, the pipeline will fail.

You can explicitly define caps using the `capsfilter` element to force a specific format. For instance, `video/x-raw,width=640,height=480,framerate=30/1` enforces 640x480 resolution at 30fps. This can be helpful when dealing with elements that don't properly negotiate caps.

HISTORY

GStreamer was initially developed as part of the freedesktop.org project. `gst-launch` and later `gst-launch-1.0` emerged as a tool for quickly testing GStreamer pipelines from the command line.

The `1.0` in `gst-launch-1.0` refers to the GStreamer API version. The tool's usage has evolved from a simple testing utility to a valuable tool for development, debugging, and even simple deployment scenarios. Over time, improvements in syntax and error reporting have been made, but its core function remains the same: to execute GStreamer pipelines described in a text format.

SEE ALSO

Copied to clipboard