Skip to main content
Version: 6

How to use Gstreamer on Torizon OS


Torizon OS platform features Docker runtime. Toradex provides Debian Docker images and deb packages that greatly eases the development process for embedded applications. In this article, we will show how you can run GStreamer in a container with Torizon OS.

The article Video Encoding and Playback (Linux) is not specific for Torizon, but some instructions may be applicable. For example, generic information about Wayland/Weston is provided.

The article How to use Cameras on Torizon aims to help you with instructions about the configuration and usage of cameras in the context of containers, using Gstreamer pipelines and Video4Linux2.

NXP provides GStreamer plugins to access the multimedia libraries using the i.MX SoC's hardware acceleration units. Torizon OS helps to reduce the complexity of the setup with Debian packages providing these HW optimized GStreamer plugins.

Typographic Conventions

Throughout the Toradex documentation, the following typographic conventions are used:

$ (dollar sign) Command in the host computer (e.g. your PC)

$ Command in your PC

$$ (double dollar sign) Command in a container in the host computer (e.g. your PC)

$$ Command inside a container in your PC

# (hashtag) Command in the target device/board (e.g. Linux terminal)

# Command in the target board, e.g. Colibri iMX6

## (double hashtag) Command inside a container in the target device (Torizon)

## Command inside a container in Torizon

> (greater-than sign) Command in the bootloader (e.g. U-Boot console)

> Command in the Bootloader

No symbol: Command output

$ Command waiting for output


  • A Toradex's SoM with Torizon OS installed (To get instructions about how to install Torizon OS, see Quickstart Guide)
  • Basic knowledge of Docker containers. To learn more about Docker, visit the developer's website. To learn the first steps with Docker usage and Torizon OS, check the Quickstart Guide

To take the best from this article and test things in practice, we recommend that you clone the torizon-samples repository to your computer:

$ cd ~
$ git clone --branch bullseye

Wayland + Weston​

This example will run a pipeline that uses waylandsink GStreamer's plugin. This plugin runs on top of Wayland and Weston. It will be necessary to start 2 containers: One with the Weston image, and one with the application image, with Wayland support. Both will communicate through shared folders by bind mounting.

Dockerfile instructions​

The implementation details will be explained in this session. See the Quickstart Guide with the instructions about how to compile the image on a host pc and pull the image onto the board. You can also scp this file to the board and build it locally.

To build​


Make sure you have configured your Build Environment for Torizon Containers

Now it's a good time to use torizon-samples repository:

$ cd ~/torizon-samples/gstreamer/bash/simple-pipeline
docker build --build-arg BASE_NAME=wayland-base-vivante --build-arg IMAGE_ARCH=linux/arm64/v8 -t <your-dockerhub-username>/gst_example .

After the build, push the image to your Dockerhub account:

$ docker push <your-dockerhub-username>/gst_example

Details about the Dockerfile​

In this section, you will go through some important snippets containing information about the Dockerfile.

Toradex Debian image - Wayland​

Toradex provides a basic Wayland image in its Dockerhub page. If you are using an iMX8 (arm64v8 CPU) computer-on-module (COM) add torizon/wayland-base-vivante to your image. Otherwise, add --platform=linux/arm torizon/wayland-base. It contains the repository package. Remember to use a version of the container that is compatible with the version of Torizon OS you are using, from the container tag.

Choose from the tabs:

FROM --platform=linux/arm64/v8 torizon/wayland-base-vivante:3

Install GStreamer application and plugins​

Install the required packages on the image with the following commands:


VPU is not supported with iMX8 Modules using the upstream container.

RUN apt update
RUN apt install -y libgstreamer1.0-0 gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-doc gstreamer1.0-tools gstreamer1.0-x gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 gstreamer1.0-qt5 gstreamer1.0-pulseaudio

Test GStreamer​

We will test GStreamer as entrypoint for our Dockerfile. A test source pattern will be output to a Wayland window. You can modify the pipeline for your needs

ENTRYPOINT gst-launch-1.0 videotestsrc ! videoconvert ! videoscale ! waylandsink sync=false


After building the Dockerfile image above and pushing it to your Dockerhub, you can launch Weston and Wayland with docker-compose.

Select your architecture from the tabs:

Still on the torizon-samples/gstreamer/bash/simple-pipeline directory, edit the docker-compose.arm64.yaml file by filling the Weston image field with your image repository:

- weston
image: <your-username>/<your-image>

After filling it, send it to your module using scp:

$ scp docker-compose.arm64.yaml torizon@<your-ip>:/home/torizon

Now enter your module using SSH:

$ ssh torizon@<your-ip>

For more information about SSH, please refer to SSH on Linux.

Now you can launch by using the command:

# docker-compose -f docker-compose.arm64.yaml up

Send Feedback!