OpenShot Library | libopenshot  0.2.6
~ubuntu18.04.1_doc_HW-ACCEL Hardware Acceleration

OpenShot now has experimental support for hardware acceleration, which uses 1 (or more) graphics cards to offload some of the work for both decoding and encoding. This is very new and experimental (as of May 2019), but we look forward to "accelerating" our support for this in the future!

The following table summarizes our current level of support:

Linux Decode Linux Encode Mac Decode Mac Encode Windows Decode Windows Encode Notes
VA-API ✔️   ✔️   - - - - Linux Only
VDPAU ✔️ 1 2 - - - - Linux Only
CUDA (NVDEC/NVENC) 3 ✔️   - - - ✔️   Cross Platform
VideoToolBox - - ✔️   4 - - Mac Only
DXVA2 - - - - 3 - Windows Only
D3D11VA - - - - 3 - Windows Only
QSV 3 ❌   ❌   ❌   ❌   ❌   Cross Platform

Notes

  1. VDPAU for some reason needs a card number one higher than it really is
  2. VDPAU is a decoder only
  3. Green frames (pixel data not correctly tranferred back to system memory)
  4. Crashes and burns

Supported FFmpeg Versions

Notice: The FFmpeg versions of Ubuntu and PPAs for Ubuntu show the same behaviour. FFmpeg 3 has working nVidia hardware acceleration while FFmpeg 4+ has no support for nVidia hardware acceleration included.

OpenShot Settings

The following settings are use by libopenshot to enable, disable, and control the various hardware acceleration features.

/// Use video codec for faster video decoding (if supported)
int HARDWARE_DECODER = 0;
/* 0 - No acceleration
1 - Linux VA-API
2 - nVidia NVDEC
3 - Windows D3D9
4 - Windows D3D11
5 - MacOS / VideoToolBox
6 - Linux VDPAU
7 - Intel QSV */
/// Number of threads of OpenMP
int OMP_THREADS = 12;
/// Number of threads that FFmpeg uses
int FF_THREADS = 8;
/// Maximum rows that hardware decode can handle
int DE_LIMIT_HEIGHT_MAX = 1100;
/// Maximum columns that hardware decode can handle
int DE_LIMIT_WIDTH_MAX = 1950;
/// Which GPU to use to decode (0 is the first, LINUX ONLY)
int HW_DE_DEVICE_SET = 0;
/// Which GPU to use to encode (0 is the first, LINUX ONLY)
int HW_EN_DEVICE_SET = 0;

Libva / VA-API (Video Acceleration API)

The correct version of libva is needed (libva in Ubuntu 16.04 or libva2 in Ubuntu 18.04) for the AppImage to work with hardware acceleration. An AppImage that works on both systems (supporting libva and libva2), might be possible when no libva is included in the AppImage.

AMD Graphics Cards (RadeonOpenCompute/ROCm)

Decoding and encoding on the (AMD) GPU is possible with the default drivers. On systems where ROCm is installed and run a future use for GPU acceleration of effects could be implemented (contributions welcome).

Multiple Graphics Cards

If the computer has multiple graphics cards installed, you can choose which should be used by libopenshot. Also, you can optionally use one card for decoding and the other for encoding (if both cards support acceleration). This is currently only supported on Linux, due to the device name FFmpeg expects (i.e. **/dev/dri/render128**). Contributions welcome if anyone can determine what string format to pass for Windows and Mac.

Help Us Improve Hardware Support

This information might be wrong, and we would love to continue improving our support for hardware acceleration in OpenShot. Please help us update this document if you find an error or discover new and/or useful information.

FFmpeg 4 + nVidia The manual at: https://www.tal.org/tutorials/ffmpeg_nvidia_encode works pretty well. We could compile and install a version of FFmpeg 4.1.3 on Mint 19.1 that supports the GPU on nVidia cards. A version of openshot with hardware support using these libraries could use the nVidia GPU.

BUG: Hardware supported decoding still has some bugs (as you can see from the chart above). Also, the speed gains with decoding are not as great as with encoding. Currently, if hardware decoding fails, there is no fallback (you either get green frames or an "invalid file" error in OpenShot). This needs to be improved to successfully fall-back to software decoding.

Needed:

Further improvement: Right now the frame can be decoded on the GPU, but the frame is then copied to CPU memory for modifications. It is then copied back to GPU memory for encoding. Using the GPU for both decoding and modifications will make it possible to do away with these two copies. A possible solution would be to use Vulkan compute which would be available on Linux and Windows natively and on MacOS via MoltenVK.

Credit

A big thanks to Peter M (https://github.com/eisneinechse) for all his work on integrating hardware acceleration into libopenshot! The community thanks you for this major contribution!

Getting Started

The best way to get started with libopenshot, is to learn about our build system, obtain all the source code, install a development IDE and tools, and better understand our dependencies. So, please read through the following sections, and follow the instructions. And keep in mind, that your computer is likely different than the one used when writing these instructions. Your file paths and versions of applications might be slightly different, so keep an eye out for subtle file path differences in the commands you type.

Build Tools

CMake is the backbone of our build system. It is a cross-platform build system, which checks for dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where all temporary build files, such as makefiles, object files, and even the final binaries, are created outside of the source code folder, inside a /build/ sub-folder. This prevents the build process from cluttering up the source code. These instructions have only been tested with the GNU compiler (including MSYS2/MinGW for Windows).

Dependencies

The following libraries are required to build libopenshot. Instructions on how to install these dependencies vary for each operating system. Libraries and Executables have been labeled in the list below to help distinguish between them.

FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)

ImageMagick++ (libMagick++, libMagickWand, libMagickCore)

OpenShot Audio Library (libopenshot-audio)

Qt 5 (libqt5)

CMake (cmake)

SWIG (swig)

Python 3 (libpython)

Doxygen (doxygen)

UnitTest++ (libunittest++)

ZeroMQ (libzmq)

OpenMP (-fopenmp)

CMake Flags (Optional)

There are many different build flags that can be passed to cmake to adjust how libopenshot is compiled. Some of these flags might be required when compiling on certain OSes, just depending on how your build environment is setup. To add a build flag, follow this general syntax: cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../

Obtaining Source Code

The first step in installing libopenshot is to obtain the most recent source code. The source code is available on GitHub. Use the following command to obtain the latest libopenshot source code.

git clone https://github.com/OpenShot/libopenshot.git
git clone https://github.com/OpenShot/libopenshot-audio.git

Folder Structure (libopenshot)

The source code is divided up into the following folders.

build/

cmake/

doc/

include/

src/

tests/

thirdparty/

Install Dependencies

In order to actually compile libopenshot, we need to install some dependencies on your system. The easiest way to accomplish this is with our Daily PPA. A PPA is an unofficial Ubuntu repository, which has our software packages available to download and install.

sudo add-apt-repository ppa:openshot.developers/libopenshot-daily
sudo apt-get update
sudo apt-get install openshot-qt \
cmake \
libx11-dev \
libasound2-dev \
libavcodec-dev \
libavdevice-dev \
libavfilter-dev \
libavformat-dev \
libavresample-dev \
libavutil-dev \
libfdk-aac-dev \
libfreetype6-dev \
libjsoncpp-dev \
libmagick++-dev \
libopenshot-audio-dev \
libswscale-dev \
libunittest++-dev \
libxcursor-dev \
libxinerama-dev \
libxrandr-dev \
libzmq3-dev \
pkg-config \
python3-dev \
qtbase5-dev \
qtmultimedia5-dev \
swig

Linux Build Instructions (libopenshot-audio)

To compile libopenshot-audio, we need to go through a few additional steps to manually build and install it. Launch a terminal and enter:

cd [libopenshot-audio repo folder]
mkdir build
cd build
cmake ../
make
make install
./src/openshot-audio-test-sound (This should play a test sound)

Linux Build Instructions (libopenshot)

Run the following commands to compile libopenshot:

cd [libopenshot repo directory]
mkdir -p build
cd build
cmake ../
make

If you are missing any dependencies for libopenshot, you might receive error messages at this point. Just install the missing packages (usually with a -dev suffix), and run the above commands again. Repeat until no error messages are displayed, and the build process completes. Also, if you manually install Qt 5, you might need to specify the location for cmake:

cmake -DCMAKE_PREFIX_PATH=/qt5_path/qt5/5.2.0/ ../

To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:

make test

To auto-generate documentation for libopenshot, launch a terminal, and enter:

make doc

This will use doxygen to generate a folder of HTML files, with all classes and methods documented. The folder is located at build/doc/html/. Once libopenshot has been successfully built, we need to install it (i.e. copy it to the correct folder, so other libraries can find it).

make install

This will copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/openshot/... This is where other projects will look for the libopenshot files when building. Python 3 bindings are also installed at this point. let's verify the python bindings work:

python3
>>> import openshot

If no errors are displayed, you have successfully compiled and installed libopenshot on your system. Congratulations and be sure to read our wiki on Becoming an OpenShot Developer! Welcome to the OpenShot developer community! We look forward to meeting you!

Getting Started

The best way to get started with libopenshot, is to learn about our build system, obtain all the source code, install a development IDE and tools, and better understand our dependencies. So, please read through the following sections, and follow the instructions. And keep in mind, that your computer is likely different than the one used when writing these instructions. Your file paths and versions of applications might be slightly different, so keep an eye out for subtle file path differences in the commands you type.

Build Tools

CMake is the backbone of our build system. It is a cross-platform build system, which checks for dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where all temporary build files, such as makefiles, object files, and even the final binaries, are created outside of the source code folder, inside a /build/ sub-folder. This prevents the build process from cluttering up the source code. These instructions have only been tested with the GNU compiler (including MSYS2/MinGW for Windows).

Dependencies

The following libraries are required to build libopenshot. Instructions on how to install these dependencies vary for each operating system. Libraries and Executables have been labeled in the list below to help distinguish between them.

FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)

ImageMagick++ (libMagick++, libMagickWand, libMagickCore)

OpenShot Audio Library (libopenshot-audio)

Qt 5 (libqt5)

CMake (cmake)

SWIG (swig)

Python 3 (libpython)

Doxygen (doxygen)

UnitTest++ (libunittest++)

ZeroMQ (libzmq)

OpenMP (-fopenmp)

CMake Flags (Optional)

There are many different build flags that can be passed to cmake to adjust how libopenshot is compiled. Some of these flags might be required when compiling on certain OSes, just depending on how your build environment is setup. To add a build flag, follow this general syntax: cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../

Obtaining Source Code

The first step in installing libopenshot is to obtain the most recent source code. The source code is available on GitHub. Use the following command to obtain the latest libopenshot source code.

git clone https://github.com/OpenShot/libopenshot.git
git clone https://github.com/OpenShot/libopenshot-audio.git

Folder Structure (libopenshot)

The source code is divided up into the following folders.

build/

cmake/

doc/

include/

src/

tests/

thirdparty/

Install Dependencies

In order to actually compile libopenshot and libopenshot-audio, we need to install some dependencies on your system. Most packages needed by libopenshot can be installed easily with Homebrew. However, first install Xcode with the following options ("UNIX Development", "System Tools", "Command Line Tools", or "Command Line Support"). Be sure to refresh your list of Homebrew packages with the “brew update” command.

NOTE: Homebrew seems to work much better for most users (compared to MacPorts), so I am going to focus on brew for this guide.

Install the following packages using the Homebrew package installer (http://brew.sh/). Pay close attention to any warnings or errors during these brew installs. NOTE: You might have some conflicting libraries in your /usr/local/ folders, so follow the directions from brew if these are detected.

brew install gcc48 --enable-all-languages
brew install ffmpeg
brew install librsvg
brew install swig
brew install doxygen
brew install unittest-cpp --cc=gcc-4.8. You must specify the c++ compiler with the --cc flag to be 4.7 or 4.8.
brew install qt5
brew install cmake
brew install zeromq

Mac Build Instructions (libopenshot-audio)

Since libopenshot-audio is not available in a Homebrew or MacPorts package, we need to go through a few additional steps to manually build and install it. Launch a terminal and enter:

cd [libopenshot-audio repo folder]
mkdir build
cd build
cmake -d -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang ../ (CLang must be used due to GNU incompatible Objective-C code in some of the Apple frameworks)
make
make install
./src/openshot-audio-test-sound (This should play a test sound)

Mac Build Instructions (libopenshot)

Run the following commands to build libopenshot:

$ cd [libopenshot repo folder]
$ mkdir build
$ cd build
$ cmake -G "Unix Makefiles" -DCMAKE_CXX_COMPILER=/usr/local/opt/gcc48/bin/g++-4.8 -DCMAKE_C_COMPILER=/usr/local/opt/gcc48/bin/gcc-4.8 -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.4.2/ -DPYTHON_INCLUDE_DIR=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/Versions/3.3/include/python3.3m/ -DPYTHON_LIBRARY=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/Versions/3.3/lib/libpython3.3.dylib -DPython_FRAMEWORKS=/usr/local/Cellar/python3/3.3.2/Frameworks/Python.framework/ ../ -D"CMAKE_BUILD_TYPE:STRING=Debug"

The extra arguments on the cmake command make sure the compiler will be gcc4.8 and that cmake knows where to look for the Qt header files and Python library. Double check these file paths, as yours will likely be different.

make

If you are missing any dependencies for libopenshot, you will receive error messages at this point. Just install the missing dependencies, and run the above commands again. Repeat until no error messages are displayed and the build process completes.

Also, if you are having trouble building, please see the CMake Flags section above, as it might provide a solution for finding a missing folder path, missing Python 3 library, etc...

To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:

make test

To auto-generate the documentation for libopenshot, launch a terminal, and enter:

make doc

This will use doxygen to generate a folder of HTML files, with all classes and methods documented. The folder is located at build/doc/html/. Once libopenshot has been successfully built, we need to install it (i.e. copy it to the correct folder, so other libraries can find it).

make install

This should copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/openshot/... This is where other projects will look for the libopenshot files when building. Python 3 bindings are also installed at this point. let's verify the python bindings work:

python3 (or python)
>>> import openshot

If no errors are displayed, you have successfully compiled and installed libopenshot on your system. Congratulations and be sure to read our wiki on Becoming an OpenShot Developer! Welcome to the OpenShot developer community! We look forward to meeting you!

Getting Started

The best way to get started with libopenshot, is to learn about our build system, obtain all the source code, install a development IDE and tools, and better understand our dependencies. So, please read through the following sections, and follow the instructions. And keep in mind, that your computer is likely different than the one used when writing these instructions. Your file paths and versions of applications might be slightly different, so keep an eye out for subtle file path differences in the commands you type.

Build Tools

CMake is the backbone of our build system. It is a cross-platform build system, which checks for dependencies, locates header files and libraries, generates makefiles, and supports the cross-platform compiling of libopenshot and libopenshot-audio. CMake uses an out-of-source build concept, where all temporary build files, such as makefiles, object files, and even the final binaries, are created outside of the source code folder, inside a /build/ sub-folder. This prevents the build process from cluttering up the source code. These instructions have only been tested with the GNU compiler (including MSYS2/MinGW for Windows).

Dependencies

The following libraries are required to build libopenshot. Instructions on how to install these dependencies vary for each operating system. Libraries and Executables have been labeled in the list below to help distinguish between them.

FFmpeg (libavformat, libavcodec, libavutil, libavdevice, libavresample, libswscale)

ImageMagick++ (libMagick++, libMagickWand, libMagickCore)

OpenShot Audio Library (libopenshot-audio)

Qt 5 (libqt5)

CMake (cmake)

SWIG (swig)

Python 3 (libpython)

Doxygen (doxygen)

UnitTest++ (libunittest++)

ZeroMQ (libzmq)

OpenMP (-fopenmp)

CMake Flags (Optional)

There are many different build flags that can be passed to cmake to adjust how libopenshot is compiled. Some of these flags might be required when compiling on certain OSes, just depending on how your build environment is setup. To add a build flag, follow this general syntax: cmake -DMAGICKCORE_HDRI_ENABLE=1 -DENABLE_TESTS=1 ../

Environment Variables

Many environment variables will need to be set during this Windows installation guide. The command line will need to be closed and re-launched after any changes to your environment variables. Also, dependency libraries will not be found during linking or execution without being found in the PATH environment variable. So, if you get errors related to missing commands or libraries, double check the PATH variable.

The following environment variables need to be added to your “System Variables”. Be sure to check each folder path for accuracy, as your paths will likely be different than this list.

Example Variables

Obtaining Source Code

The first step in installing libopenshot is to obtain the most recent source code. The source code is available on GitHub. Use the following command to obtain the latest libopenshot source code.

git clone https://github.com/OpenShot/libopenshot.git
git clone https://github.com/OpenShot/libopenshot-audio.git

Folder Structure (libopenshot)

The source code is divided up into the following folders.

build/

cmake/

doc/

include/

src/

tests/

thirdparty/

Install MSYS2 Dependencies

Most Windows dependencies needed for libopenshot-audio, libopenshot, and openshot-qt can be installed easily with MSYS2 and the pacman package manager. Follow these directions to setup a Windows build environment for OpenShot.

1) Install MSYS2: http://www.msys2.org/

2) Run MSYS2 command prompt (for example: C:\msys64\msys2_shell.cmd)

3) Append PATH (so MSYS2 can find executables and libraries):

PATH=$PATH:/c/msys64/mingw64/bin:/c/msys64/mingw64/lib (64-bit PATH)
or
PATH=$PATH:/c/msys32/mingw32/bin:/c/msys32/mingw32/lib (32-bit PATH)

4) Update and upgrade all packages

pacman -Syu

5a) Install the following packages (64-Bit)

pacman -S --needed base-devel mingw-w64-x86_64-toolchain
pacman -S mingw64/mingw-w64-x86_64-ffmpeg
pacman -S mingw64/mingw-w64-x86_64-python3-pyqt5
pacman -S mingw64/mingw-w64-x86_64-swig
pacman -S mingw64/mingw-w64-x86_64-cmake
pacman -S mingw64/mingw-w64-x86_64-doxygen
pacman -S mingw64/mingw-w64-x86_64-python3-pip
pacman -S mingw32/mingw-w64-i686-zeromq
pacman -S mingw64/mingw-w64-x86_64-python3-pyzmq
pacman -S mingw64/mingw-w64-x86_64-python3-cx_Freeze
pacman -S git
# Install ImageMagick if needed (OPTIONAL and NOT NEEDED)
pacman -S mingw64/mingw-w64-x86_64-imagemagick

5b) Or Install the following packages (32-Bit)

pacman -S --needed base-devel mingw32/mingw-w64-i686-toolchain
pacman -S mingw32/mingw-w64-i686-ffmpeg
pacman -S mingw32/mingw-w64-i686-python3-pyqt5
pacman -S mingw32/mingw-w64-i686-swig
pacman -S mingw32/mingw-w64-i686-cmake
pacman -S mingw32/mingw-w64-i686-doxygen
pacman -S mingw32/mingw-w64-i686-python3-pip
pacman -S mingw32/mingw-w64-i686-zeromq
pacman -S mingw32/mingw-w64-i686-python3-pyzmq
pacman -S mingw32/mingw-w64-i686-python3-cx_Freeze
pacman -S git
# Install ImageMagick if needed (OPTIONAL and NOT NEEDED)
pacman -S mingw32/mingw-w32-x86_32-imagemagick

6) Install Python PIP Dependencies

pip3 install httplib2
pip3 install slacker
pip3 install tinys3
pip3 install github3.py
pip3 install requests

7) Download Unittest++ (https://github.com/unittest-cpp/unittest-cpp) into /MSYS2/[USER]/unittest-cpp-master/

cmake -G "MSYS Makefiles" ../ -DCMAKE_MAKE_PROGRAM=mingw32-make -DCMAKE_INSTALL_PREFIX:PATH=/usr
mingw32-make install

8) ZMQ++ Header (This might not be needed anymore) NOTE: Download and copy zmq.hpp into the /c/msys64/mingw64/include/ folder

Manual Dependencies

DLfcn

DirectX SDK / Windows SDK

libSndFile

libzmq

Windows Build Instructions (libopenshot-audio)

In order to compile libopenshot-audio, launch a command prompt and enter the following commands. This does not require the MSYS2 prompt, but it should work in both the Windows command prompt and the MSYS2 prompt.

cd [libopenshot-audio repo folder]
mkdir build
cd build
cmake -G “MinGW Makefiles” ../
mingw32-make
mingw32-make install
openshot-audio-test-sound (This should play a test sound)

Windows Build Instructions (libopenshot)

Run the following commands to build libopenshot:

cd [libopenshot repo folder]
mkdir build
cd build
cmake -G "MinGW Makefiles" -DPYTHON_INCLUDE_DIR="C:/Python34/include/" -DPYTHON_LIBRARY="C:/Python34/libs/libpython34.a" ../
mingw32-make

If you are missing any dependencies for libopenshot, you will receive error messages at this point. Just install the missing dependencies, and run the above commands again. Repeat until no error messages are displayed and the build process completes.

Also, if you are having trouble building, please see the CMake Flags section above, as it might provide a solution for finding a missing folder path, missing Python 3 library, etc...

To run all unit tests (and verify everything is working correctly), launch a terminal, and enter:

mingw32-make test

To auto-generate the documentation for libopenshot, launch a terminal, and enter:

mingw32-make doc

This will use doxygen to generate a folder of HTML files, with all classes and methods documented. The folder is located at build/doc/html/. Once libopenshot has been successfully built, we need to install it (i.e. copy it to the correct folder, so other libraries can find it).

mingw32-make install

This should copy the binary files to C:\Program Files\openshot\lib\, and the header files to C:\Program Files\openshot\include\... This is where other projects will look for the libopenshot files when building.. Python 3 bindings are also installed at this point. let's verify the python bindings work:

python3
>>> import openshot

If no errors are displayed, you have successfully compiled and installed libopenshot on your system. Congratulations and be sure to read our wiki on Becoming an OpenShot Developer! Welcome to the OpenShot developer community! We look forward to meeting you!