Search by Tags

How to use Gstreamer on TorizonCore

 

Article updated at 25 Sep 2020
Compare with Revision




Subscribe for this article updates

Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.

Torizon 5.0.0

Introduction

TorizonCore 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 TorizonCore.

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.

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

Typographic Conventions

Prerequisites

  • A Toradex's SoM with TorizonCore installed (To get instructions about how to install TorizonCore, 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 TorizonCore, 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 https://github.com/toradex/torizon-samples.git

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 in the board. You can also scp this file to the board and build it locally.

To build

Attention: 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 -f Dockerfile -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 TorizonCore you are using, from the container tag.

Choose from the tabs:

FROM torizon/wayland-base-vivante:2
FROM --platform=linux/arm torizon/wayland-base:2

Install GStreamer application and plugins

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

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

Warning: the sample Dockerfile does not account for the instructions described in this section. You must modify it manually to apply the instructions.

# Toradex unstable feed that provides NXP's downstream Gstreamer(v1.16) packages
RUN echo "deb https://feeds.toradex.com/debian/snapshots/20211007T072229Z unstable main non-free" >> /etc/apt/sources.list

# Debian snapshot that contains gstreamer1.0-plugins-ugly and gstreamer1.0-libav v1.16
RUN echo "deb [check-valid-until=no] http://snapshot.debian.org/archive/debian/20200818T025233Z/ bullseye main" >> /etc/apt/sources.list

# Pin v1.16 for gstreamer1.0-plugins-ugly and gstreamer1.0-libav
RUN printf 'Package: gstreamer1.0-plugins-ugly\n\
Pin: version 1.16.2-2.1+b1\n\
Pin-Priority: 969\n\
\n\
Package: gstreamer1.0-libav\n\
Pin: version 1.16.2-2\n\
Pin-Priority: 969\n' > /etc/apt/preferences.d/version-pinned-packages

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

NXP provides downstream fork for some Gstreamer packages. These include gstreamer1.0, gst-plugins-base1.0, gst-plugins-good1.0 and gst-plugins-bad1.0. TorizonCore 5.0.0 is synced to an NXP BSP that contains v1.16 of these packages. TorizonCore 5.0.0 uses the main Debian Bullseye feed which provides v1.18 of these packages.

To be able to use v1.16 NXP Gstreamer packages we use the Toradex unstable feed.

There are other Gstreamer packages that do not have a donwstream NXP fork, such as gstreamer1.0-plugins-ugly and gstreamer1.0-libav. By default v1.18 of these packages would be downloaded from Debian Bullseye feed. gstreamer1.0-plugins-ugly and gstreamer1.0-libav v1.18 depend on libgstreamer-plugins-base1.0-0 (>= 1.18.0) and libgstreamer1.0-0 (>= 1.18.0) and this will cause a conflict with the v1.16 downstream packages. To avoid this we download the older v1.16 packages by adding an older Debian snapshot feed and version pinning these packages.

To find which Debian snapshot has a particular version of a package we can use buildd.debian.org and metasnap.d.n. For example in case of gstreamer1.0-plugins-ugly, in the buildd log we see that the latest 1.16 version ever available in Debian was 1.16.2-2.1+b1. Next, we use metasnap search to find the Debian snapshot where this version was available, in this case 20200818T025233Z. Finally we add this snapshot to the list of feeds in /etc/apt/sources.list and pin the version in /etc/apt/preferences.d/version-pinned-packages. We can use the same workaround for any other packages that have a versioned dependency on the Gstreamer packages.

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-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

Docker-compose

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:


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

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>

Note: 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

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


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

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

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

Now enter your module using SSH:

$ ssh torizon@<your-ip>

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

Now you can launch by using the command:

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

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


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

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

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

Now enter your module using SSH:

$ ssh torizon@<your-ip>

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

Now you can launch by using the command:

# docker-compose -f docker-compose.colibri-imx7.yaml up

Torizon 4.0.0

Introduction

TorizonCore 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 TorizonCore.

Warning: Currently only plugins from the Gstreamer project repository are available. A Debian package with VPU accelerated Gstreamer plugins for i.MX will be available soon. Please contact your Toradex representative if you need more information about this plugin.

Typographic Conventions

Prerequisites

  • A Toradex's SoM with TorizonCore installed (To get instructions about how to install TorizonCore, 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 TorizonCore, 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 https://github.com/toradex/torizon-samples.git
$ cd torizon-samples/gstreamer

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 in the board. You can also scp this file to the board and build it locally.

To build

Select your architecture from the boxes below:

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

$ cd ~/torizon-samples/gstreamer/bash/simple-pipeline
$ docker build -f Dockerfile.arm64 -t <your-dockerhub-username>/gst_example .

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

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

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

$ cd ~/torizon-samples/gstreamer/bash/simple-pipeline
$ docker build -f Dockerfile.armhf -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/arm64v8-debian-wayland-base-vivante to your image. Otherwise, add torizon/arm32v7-debian-wayland-base. It contains the repository package.

Choose from the tabs:

FROM torizon/arm64v8-debian-wayland-base-vivante
FROM torizon/arm32v7-debian-wayland-base

Install Gstreamer application and plugins

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

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

Docker-compose

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:

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

$ cd ~/torizon-samples/gstreamer/bash/simple-pipeline

Then fill the Weston image field with your image repository:

docker-compose
  depends_on: 
      - weston
    image: <your-username>/<your-image>
    volumes:

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

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

Now enter your module using SSH:

$ ssh torizon@<your-ip>

Note: 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

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

$ cd ~/torizon-samples/gstreamer/bash/simple-pipeline

Then fill the Weston image field with your image repository:

docker-compose
  depends_on: 
      - weston
    image: <your-username>/<your-image>
    volumes:

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

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

Now enter your module using SSH:

$ ssh torizon@<your-ip>

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

Now you can launch by using the command:

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