PROfessional MEdia toolKIt

A modern C++20 library that makes writing audio, video, and media applications in C++ easier.

libpromeki provides the foundational building blocks that professional media software needs: timecode, frame rates, image and audio descriptors, pixel formats, color spaces, memory management, signal/slot event systems, and more. It is designed so that you can focus on your application logic instead of reinventing infrastructure.

Library Architecture

libpromeki is split into three shared libraries:

promeki-core — General-purpose C++ utilities with no media-specific dependencies. Includes strings with copy-on-write, shared pointers, points/matrices, date/time, timecode, UUID, logging, JSON, signals/slots, an object system, command-line parsing, file I/O, memory pools, and a unit test framework.

promeki-proav — Professional audio/video classes built on top of promeki-core. Includes image and audio descriptors, pixel format registry, image file I/O (PNG, JPEG), audio file I/O (WAV, AIFF, OGG), font painting, color space conversion, codecs, and frame/video descriptors.

promeki-music — Music and MIDI utilities built on top of promeki-proav. Includes MIDI note representation with named constants for all 128 notes and General MIDI percussion, customizable note name overlays, musical scales with degree-to-MIDI mapping, and a note-sequence parser for text-based musical notation.

You can use promeki-core on its own for non-media projects, link against promeki-proav to get the full media toolkit, or add promeki-music for music and MIDI functionality.

No Dependency Hell

All third-party libraries that promeki-proav depends on (zlib, libpng, FreeType, libjpeg-turbo, libsndfile) are vendored as git submodules, built as static libraries with -fPIC, and absorbed directly into libpromeki-proav.so. Their headers are installed under promeki/thirdparty/ to avoid collisions with system versions.

When you install libpromeki, you get three shared libraries and a set of headers. Your application links against promeki::core and/or promeki::proav — no chasing down system packages, no version mismatches, no transitive dependency surprises.

History

The bulk of the code that makes up libpromeki started out life as code that existed across multiple libraries originally developed by my (now defunct) company, SpectSoft, for our video disk recorder product called RaveHD. During its run, it was used in post production, VFX, animation, and other media related sectors. At that time, the entire application stack was built on top of the Qt framework. The Qt design patterns, aesthetic, and general way of doing things has certainly informed much of how this library was architected.

What you see now is a library that takes the good bits from that old code base and has removed the Qt coupling and replaced it with modern C++ native STL. Hopefully you'll find it as useful as I have over the years. –jth

Building

Requirements: a C++20 compiler, CMake 3.22+, and git.

git clone --recurse-submodules https://github.com/user/libpromeki.git
cd libpromeki
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

CMake Build Options

Option	Default	Description
PROMEKI_BUILD_PROAV	ON	Build the promeki-proav media library
PROMEKI_BUILD_MUSIC	ON	Build the promeki-music library (requires proav)
PROMEKI_BUILD_TESTS	ON	Build unit tests
PROMEKI_BUILD_DOCS	OFF	Build Doxygen API documentation

To build only the core library without media or music components:

cmake -B build -DPROMEKI_BUILD_PROAV=OFF -DPROMEKI_BUILD_MUSIC=OFF

Cleaning

The libclean target removes only the promeki library objects, test executables, and utilities while preserving third-party builds. This avoids rebuilding vendored dependencies (zlib, libpng, FreeType, etc.) which rarely change:

cmake --build build --target libclean

To clean everything including third-party builds, use the standard CMake clean target:

cmake --build build --target clean

Running Tests

cd build
ctest --output-on-failure

Installing

cmake --install build
# or to a custom prefix:
cmake --install build --prefix /opt/promeki

This installs:

• lib/libpromeki-core.so, lib/libpromeki-proav.so, and lib/libpromeki-music.so (versioned, with SONAME)
• include/promeki/ — all public headers
• include/promeki/thirdparty/ — bundled third-party headers
• lib/cmake/promeki/ — CMake package config files
• share/doc/promeki/ — license and third-party notices

Using libpromeki in Your Project

After installing, add this to your project's CMakeLists.txt:

find_package(promeki REQUIRED)
 
# For general-purpose utilities only:
target_link_libraries(myapp PRIVATE promeki::core)
 
# For media/audio/video functionality (includes core):
target_link_libraries(myapp PRIVATE promeki::proav)
 
# For music/MIDI functionality (includes proav and core):
target_link_libraries(myapp PRIVATE promeki::music)

If you installed to a non-standard prefix, tell CMake where to find it:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/promeki

Include Conventions

All promeki headers live under the promeki/ namespace:

#include <promeki/core/string.h>
#include <promeki/core/timecode.h>
#include <promeki/proav/imagedesc.h>

Bundled third-party headers are under promeki/thirdparty/:

#include <promeki/thirdparty/png.h>
#include <promeki/thirdparty/freetype2/ft2build.h>

Everything in promeki is in the promeki namespace:

using namespace promeki;
 
String name("hello");
Timecode tc(1, 2, 3, 4, FrameRate::fps24());
UUID id = UUID::generate();

Documentation

Build the API documentation (requires Doxygen):

cmake -B build -DPROMEKI_BUILD_DOCS=ON
cmake --build build --target docs

A hosted copy of the documentation is available at: API Documentation

Debugging

If you build the library in Debug mode (-DCMAKE_BUILD_TYPE=Debug), the promekiDebug() logging function is enabled. Each source file that wants to use it must register a debug channel:

PROMEKI_DEBUG(MyChannel)
 
// elsewhere in your code
promekiDebug("This is a debug log entry")

Then enable channels at runtime via the PROMEKI_DEBUG environment variable (comma-separated):

export PROMEKI_DEBUG=MyChannel,AnotherChannel
./yourapp

License

libpromeki is licensed under the [MIT License](LICENSE).

Third-party library licenses and attribution notices are documented in [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES).