Linux Build Instructions

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.

OpenShot Audio Library (libopenshot-audio)

• https://github.com/OpenShot/libopenshot-audio/ (Library)
• This library is used to mix, resample, host plug-ins, and play audio. It is based on the JUCE project, which is an outstanding audio library used by many different applications

CMake (cmake)

• http://www.cmake.org/ (Executable)
• This executable is used to automate the generation of Makefiles, check for dependencies, and is the backbone of libopenshot’s cross-platform build process.

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

• http://www.ffmpeg.org/ (Library)
• This library is used to decode and encode video, audio, and image files. It is also used to obtain information about media files, such as frame rate, sample rate, aspect ratio, and other common attributes.

Qt 5 (libqt5)

• http://www.qt.io/qt5/ (Library)
• Qt5 is used to display video, store image data, composite images, apply image effects, and many other utility functions, such as file system manipulation, high resolution timers, etc...

ZeroMQ (libzmq)

• http://zeromq.org/ (Library)
• This library is used to communicate between libopenshot and other applications (publisher / subscriber). Primarily used to send debug data from libopenshot.

OpenMP (-fopenmp)

• http://openmp.org/wp/ (Compiler Flag)
• If your compiler supports this flag (GCC, Clang, and most other compilers), it provides libopenshot with easy methods of using parallel programming techniques to improve performance and take advantage of multi-core processors.

SWIG (swig)

• http://www.swig.org/ (Executable)
• This executable is used to generate the Python and Ruby bindings for libopenshot. It is a simple and powerful wrapper for C++ libraries, and supports many languages.

Python 3 (libpython)

• http://www.python.org/ (Executable and Library)
• This library is used by swig to create the Python (version 3+) bindings for libopenshot. This is also the official language used by OpenShot Video Editor (a graphical interface to libopenshot).

Doxygen (doxygen)

• http://www.stack.nl/~dimitri/doxygen/ (Executable)
• This executable is used to auto-generate the documentation used by libopenshot.

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

• http://www.imagemagick.org/script/magick++.php (Library)
• This library is optional, and used to decode and encode images.

UnitTest++ (libunittest++)

• https://github.com/unittest-cpp/ (Library)
• This library is used to execute unit tests for libopenshot. It contains many macros used to keep our unit testing code very clean and simple.

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

If you want to change what dependencies are used in the build:

• ENABLE_TESTS=0 (default 1)
• ENABLE_PYTHON=0 (default: autodetect)
• ENABLE_RUBY=0 (default: autodetect)

If you want to change how CMake builds libopenshot:

• CMAKE_CXX_COMPILER (example: /msys64/mingw64/usr/bin/g++)
• CMAKE_C_COMPILER (example: /msys64/mingw64/usr/bin/gcc)
• CMAKE_PREFIX_PATH (example: /opt/ffmpeg/)
• PYTHON_INCLUDE_DIR (example: /usr/local/include/python3.8/)
• PYTHON_LIBRARY (example: /usr/local/lib64/libpython3.8.so)
• PYTHON_FRAMEWORKS (example: /usr/local/Cellar/python3/3.8.5/Frameworks/Python.framework/)

If you're using an ImageMagick build with HDRI enabled, or a quantum depth other than 16:

• MAGICKCORE_HDRI_ENABLE (default: 0)
• MAGICKCORE_QUANTUM_DEPTH (default: 16)

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/

• This folder needs to be manually created, and is used by cmake to store the temporary build files, such as makefiles, as well as the final binaries (library and test executables).

cmake/

• This folder contains custom modules not included by default in cmake, used to find dependency libraries and headers and determine if these libraries are installed.

doc/

• This folder contains documentation and related files, such as logos and images required by the doxygen auto-generated documentation.

include/

• This folder contains all headers (*.h) used by libopenshot.

src/

• This folder contains all source code (*.cpp) used by libopenshot.

tests/

• This folder contains all unit test code. Each class has it’s own test file (*.cpp), and uses UnitTest++ macros to keep the test code simple and manageable.

thirdparty/

• This folder contains code not written by the OpenShot team. For example, jsoncpp, an open-source JSON parser.

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 \
cmake \
pkg-config \
libopenshot-audio-dev \
libx11-dev \
libfreetype6-dev \
libasound2-dev \
libavcodec-dev \
libavdevice-dev \
libavfilter-dev \
libavformat-dev \
libavutil-dev \
libswresample-dev \
libswscale-dev \
libpostproc-dev \
libfdk-aac-dev \
libjsoncpp-dev \
libzmq3-dev \
qtbase5-dev \
qtmultimedia5-dev \
libqt5svg5-dev \
libunittest++-dev \
python3-dev \
swig \
libmagick++-dev

The last item, libmagick++-dev, is completely optional. Libopenshot will build fine without it. The two items before that, swig and python3-dev, are only required if you need to build libopenshot's Python bindings. If not, you can skip them and add -DENABLE_PYTHON=0 to the CMake command line.

If you're building the library for use with OpenShot then you will need both SWIG and the Python development package. There are also a few more things you should install — but none of these are required if you're only building libopenshot itself, for use from your own C++ or Python code.

sudo apt-get install \
openshot-qt \
python3-zmq \
python3-pyqt5.qtwebengine

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 to run the build commands. If you're using a recent CMake (3.13+), you can run all of the build steps through it. This tends to be easier, as it will automatically select the correct make and other tools.

Except for the initial cd command, feel free to copy/paste these commands to a terminal window. The shell will ignore the comment lines.

cd /path/to/cloned/libopenshot-audio

# Tell CMake to examine the source tree in the current directory (./)
# and write a configuration for it in a build subdirectory (build/)
cmake -B build -S .

# This has cmake compile all of the default build targets in build/
cmake --build build

# This should play a test sound
./build/src/openshot-audio-demo

# This tells CMake to install everything that was compiled in build/
cmake --install build

The last command will install the library, headers, and other files to /usr/local/ by default, and libopenshot will find them there during its own build. If you install to some other location, you'll need to tell the next steps where to find your library. For example

# Install to an /opt subdirectory
cmake --install build -DCMAKE_INSTALL_PREFIX=/opt/libopenshot-audio

# When configuring libopenshot in the next section, give it that location:
cmake -B build -S . -DOpenShotAudio_ROOT=/opt/libopenshot-audio

Linux Build Instructions (libopenshot)

If you manually install Qt 5, you might need to specify that location as well, for CMake to find it. (Make sure you point it to the directory containing bin, lib, etc. directories. One level higher or lower, and it won't detect your Qt install. Then either libopenshot will be linked with your system /usr/lib/.../qt5, or the build will fail.)

cmake -B build -S . -DCMAKE_PREFIX_PATH=$HOME/Qt/5.15.0/gcc_64/ 

Run the following commands to compile libopenshot:

cd /path/to/cloned/libopenshot

# Just like before, configure...
cmake -B build -S .

# Build...
cmake --build build

# Test...
cmake --build build --target test

If you are missing any dependencies for libopenshot, either cmake command might result in an error message, which hopefully will give an indication of what's missing. Just install the packages that provide the missing components. (In particular, make sure you have the necessary -dev or -devel package, which contains the build components necessary to compile other software with the library or tool. libavcodec58 will let you run software that uses FFmpeg, but you need libavcodec-dev to compile software that uses it.)

When you have the problem corrected, run the build commands again. Repeat until no error messages are displayed, and the build process completes.

API documentation

To produce documentation for libopenshot (requires Doxygen and graphviz installed), after building and testing you can generate the API documentation

cmake --build build --target 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/.

Before installing everything, if you built the Python bindings you can verify that they work correctly right from the build dir. The build tree shared library components are linked directly with each other, so it's easy to run tests there. Once they've been installed, if any of the dependencies you built with was in a non-default location you'll need to make sure that the installed libopenshot can still find everything.

For now, run the following command with your system's default Python 3 interpreter:

PYTHONPATH=/path/to/your/libopenshot/build/src/bindings/python python3
>>> import openshot
>>> print(openshot.Version)
0.2.5

If the output matches the version of libopenshot you just built and no errors are displayed, you're ready to install the libopenshot components.

cmake --install build

By default this will copy the binary files to /usr/local/lib/, and the header files to /usr/local/include/libopenshot/. This is where other projects will look for the libopenshot files when building. If you need to use a different install path, you can set it with CMake, for example:

cmake --install build --prefix /opt/libopenshot

If everything goes as planned, you will now 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!