Files

T

Mike-Solar 18ff60f147 feat(engine): clip move, clip effect_input, mandatory static FFmpeg

- oakengine_sequence_move_clip implemented for real (oaktimeline
  TrackMoveBlockCommand; fixes the graph-ownership/gap-anchor/ripple
  trim bugs the stub was hiding); same-track via the frozen C ABI,
  cross-track supported by the module command
- oaknode clip blocks now declare a tex_in texture input and set
  effect_input to it, so timeline clips can host effect chains; facade
  test covers effect insert/remove on a real clip
- oakffmpeg-link: FFMPEG_DIR is now mandatory with a clear panic (a
  Homebrew upgrade left the system ffmpeg .pc pointing at a deleted
  dav1d Cellar path, breaking links); reads a git-ignored workspace
  .env for IDEs that cannot inject env vars (RustRover); links the C++
  stdlib for C++ codec libs (svt-av1)
- oakengine re-exports oaknode so tests share one crate instance;
  it_node uses the direct instance's value type where it calls the
  module FFI (the --workspace dev-dependency feature split builds
  oaknode twice)

2026-08-11 23:04:48 +08:00

11 KiB

Raw Blame History

Build Guide

This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.

Note (2026): Oak is now a Rust workspace; cargo build at the repository root produces the app, the CLI, the worker and liboakengine. The CMake instructions below are kept for historical reference only. Rust dependencies are pulled from crates.io; the only native libraries still needed are FFmpeg (see the next section), OpenColorIO (optional; ocio-sys builds a stub without it) and a C/C++ toolchain for the FFI shims.

FFmpeg for the Rust build

ffmpeg-next 9.x pairs with FFmpeg 8.x headers, which most distros do not ship yet. Build a project-owned FFmpeg — GPL parts enabled, every free-license external codec library that is installed, per-OS hardware acceleration, static+PIC — with the project scripts:
tooling/install-deps.sh           # Homebrew / MSYS2 UCRT64 / Debian / Fedora / Arch
tooling/ffmpeg/build-ffmpeg.sh    # clones release/8.0, installs into .cache/ffmpeg
export FFMPEG_DIR="$(pwd)/.cache/ffmpeg"
cargo build
External libraries are probed with pkg-config and silently skipped when missing. FFMPEG_DIR is mandatory (the oakffmpeg-link build script panics without it): silently binding a system FFmpeg risks stale .pc paths after package upgrades. IDEs that cannot inject environment variables into cargo (RustRover) can instead put FFMPEG_DIR=... (and PKG_CONFIG_PATH=... where needed) into a .env file at the workspace root — it is git-ignored. ffmpeg-next's build cargo feature is deliberately not used: it clones release/, and every such pairing is broken upstream (9.0.0 → FFmpeg 9.0 removed AVCodec fields; 8.1.0 → FFmpeg 8.1 added enum variants; 8.0.0 → FFmpeg 8.0 renamed FF_PROFILE_*).

Prerequisites

CMake 3.20+
Ninja (recommended)
Qt 6 (with private headers)
FFmpeg 6.0+ development libraries
OpenTimelineIO (0.16+, built from source below — no distro package on most platforms)
OpenImageIO
OpenColorIO (2.x)
OpenEXR
Expat
PortAudio
OpenGL headers
Vulkan SDK (optional, required for the Vulkan render backend)
XKB common (Linux)

Windows (MSYS2)

This guide uses MSYS2 with the UCRT64 toolchain.

1. Install MSYS2

Download and install MSYS2 from https://www.msys2.org/. Then open the MSYS2 UCRT64 terminal.

2. Install Dependencies

pacman -Syu
pacman -S --needed \
  mingw-w64-ucrt-x86_64-cmake \
  mingw-w64-ucrt-x86_64-ninja \
  mingw-w64-ucrt-x86_64-qt6-base \
  mingw-w64-ucrt-x86_64-qt6-tools \
  mingw-w64-ucrt-x86_64-ffmpeg \
  mingw-w64-ucrt-x86_64-openimageio \
  mingw-w64-ucrt-x86_64-opencolorio \
  mingw-w64-ucrt-x86_64-openexr \
  mingw-w64-ucrt-x86_64-fmt \
  mingw-w64-ucrt-x86_64-expat \
  mingw-w64-ucrt-x86_64-portaudio \
  mingw-w64-ucrt-x86_64-vulkan-headers \
  mingw-w64-ucrt-x86_64-vulkan-loader \
  mingw-w64-ucrt-x86_64-gcc

Note: Qt 6 private headers may require additional packages depending on the MSYS2 repository state. If CMake reports missing private headers, install mingw-w64-ucrt-x86_64-qt6-base-private if available.

3. Build OpenTimelineIO (required)

There is no MSYS2 package for OpenTimelineIO, so build it from source:

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

4. Clone and Build

# Clone the repository
git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
cd oak

# Configure
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DOTIO_LOCATION="/path/to/otio-install" \
  -DBUILD_QT6=ON

# Build
cmake --build build --config Release

5. Run Tests (Optional)

ctest --test-dir build --output-on-failure -C Release

Linux

Debian / Ubuntu

Install dependencies (Ubuntu 24.04+ ships FFmpeg 6.1, which satisfies the 6.0 minimum; on older releases build FFmpeg from source as described in Troubleshooting):

sudo apt-get update
sudo apt-get install -y \
  cmake ninja-build pkg-config \
  qt6-base-dev qt6-base-dev-tools qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools \
  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev \
  libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
  portaudio19-dev libgl1-mesa-dev libvulkan-dev libxkbcommon-dev

Build OpenTimelineIO (required, no distro package):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

cmake -S . -B build -G Ninja \
  -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="$PWD/otio-install"
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

Fedora

Install dependencies:

sudo dnf install -y \
  cmake ninja-build pkgconf-pkg-config \
  qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
  ffmpeg-free-devel \
  OpenImageIO-devel \
  OpenColorIO-devel \
  openexr-devel \
  expat-devel \
  portaudio-devel \
  mesa-libGL-devel \
  vulkan-headers \
  vulkan-loader-devel \
  libxkbcommon-devel \
  gcc-c++ \
  bzip2-devel

Build OpenTimelineIO (required, no distro package):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="$PWD/otio-install"
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

Arch Linux

Install dependencies:

sudo pacman -Syu
sudo pacman -S --needed \
  cmake ninja pkgconf \
  qt6-base qt6-tools \
  ffmpeg \
  openimageio \
  opencolorio \
  openexr \
  expat \
  portaudio \
  opentimelineio \
  mesa \
  vulkan-headers \
  vulkan-icd-loader \
  libxkbcommon \
  fmt \
  gcc

Note: On Arch Linux, Qt 6 private headers are included in the qt6-base package.

Configure and build:

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

macOS

macOS is now a fully supported platform. See build_macos.md for a dedicated, step-by-step guide.

Install dependencies:

brew update
brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader

Build OpenTimelineIO (required):

git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
  -DOTIO_SHARED_LIBS=ON \
  -DOTIO_PYTHON_BINDINGS=OFF \
  -DOTIO_FIND_IMATH=ON \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
cmake --build OpenTimelineIO/build
cmake --install OpenTimelineIO/build

Configure and build:

export PATH="$(brew --prefix qt@6)/bin:$PATH"
export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
export OTIO_LOCATION="${PWD}/otio-install"
export OCIO_LOCATION="$(brew --prefix opencolorio)"
# Let CMake's FindVulkan locate the Homebrew Vulkan loader (optional,
# enables the Vulkan render backend)
export VULKAN_SDK="$(brew --prefix vulkan-loader)"

cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
  -DOTIO_LOCATION="${OTIO_LOCATION}" \
  -DOCIO_LOCATION="${OCIO_LOCATION}"
cmake --build build --config Release

Run tests:

ctest --test-dir build --output-on-failure -C Release

Build Options

Option	Default	Description
`BUILD_TESTS`	`OFF`	Build unit tests
`BUILD_DOXYGEN`	`OFF`	Build Doxygen documentation
`USE_WERROR`	`OFF`	Treat warnings as errors
`BUILD_QT6`	`ON`	Build with Qt 6 instead of Qt 5
`OTIO_LOCATION`	-	Path to OpenTimelineIO installation (required)
`OAK_BUNDLE_OTIO`	`ON`	Install OTIO runtime libraries alongside Oak (set `OFF` for distro-native packaging where `opentimelineio` is a package dependency, e.g. Arch)
`OCIO_LOCATION`	-	Path to OpenColorIO installation
`OAK_ENABLE_DYNAMIC_RENDER_BACKEND`	`ON`	Build dynamic render backend libraries (`liboakgl.so` / `liboakvulkan.so`)

Troubleshooting

Qt 6 Not Found

Ensure Qt 6 is in your PATH and CMake prefix path:

# Linux / macOS
export PATH="/path/to/qt6/bin:$PATH"
export CMAKE_PREFIX_PATH="/path/to/qt6"

# Windows (MSYS2)
export PATH="/ucrt64/bin:$PATH"

Missing Private Headers

If you see errors about missing Qt private headers, install the corresponding private development package for your distribution (e.g., qt6-base-private-dev on Debian/Ubuntu, qt6-qtbase-private-devel on Fedora).

FFmpeg Not Found

Make sure FFmpeg development libraries are installed and pkg-config can locate them:

pkg-config --exists libavcodec && echo "Found" || echo "Not found"

FFmpeg Version Too Old

Oak requires FFmpeg 6.0 or newer; CMake configure fails with Could NOT find FFMPEG (missing: FFMPEG_VERSION) (Required is at least version "6.0") on older versions. Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 all ship new enough FFmpeg. If your distro is older, build from source:

git clone --branch n8.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git ffmpeg-src
cd ffmpeg-src
./configure \
  --prefix="$PWD/../ffmpeg-install" \
  --enable-static \
  --disable-shared \
  --disable-doc \
  --disable-programs \
  --disable-avdevice \
  --disable-network \
  --enable-pic \
  --enable-gpl \
  --enable-version3
make -j$(nproc)
make install
cd ..

Then pass -DFFMPEG_ROOT="$PWD/ffmpeg-install" to CMake.

OpenTimelineIO Not Found

OpenTimelineIO is a required dependency. Build it from source as shown in your platform's section above and pass -DOTIO_LOCATION=/path/to/otio-install to CMake. On Arch Linux the opentimelineio package provides it directly.

11 KiB Raw Blame History

Build Guide

FFmpeg for the Rust build

Prerequisites

Windows (MSYS2)

1. Install MSYS2

2. Install Dependencies

3. Build OpenTimelineIO (required)

4. Clone and Build

5. Run Tests (Optional)

Linux

Debian / Ubuntu

Fedora

Arch Linux

macOS

Build Options

Troubleshooting

Qt 6 Not Found

Missing Private Headers

FFmpeg Not Found

FFmpeg Version Too Old

OpenTimelineIO Not Found

11 KiB

Raw Blame History