Skip to content

Latest commit

 

History

History
253 lines (170 loc) · 11.5 KB

README.md

File metadata and controls

253 lines (170 loc) · 11.5 KB
Raw

bmx Library and Utilities

bmx is a library and set of utilities to read and write the SMPTE ST 377-1 MXF file format.

bmx is used to support standardisation efforts in the broadcast industry. It provides utilities for creating standard compliant sample files. It serves as an example implementation for MXF file format standards.

bmx includes the libMXF low-level MXF C library and the libMXF++ C++ wrapper library.

bmx provides a set of commandline applications:

  • raw2bmx: create MXF files from raw essence files
  • bmxtranswrap: re-wrap from one MXF file to another MXF file
  • mxf2raw: output MXF file metadata and raw essence
  • bmxparse: text dump raw essence files using the bmx library's parser class

bmx provides a set of file format text dumper and essence extraction tools:

  • h264dump: text dump raw H.264 bitstream files
  • j2cdump: text dump raw JPEG 2000 codestreams
  • jp2extract: extract JPEG 2000 codestream from a JP2 file (ISO/IEC 15444-1 / ITU T.800 Annex I)
  • movdump: text dump Quicktime / MP4 files
  • rdd36dump: text dump SMPTE RDD 36 (Apple ProRes) bitstream files
  • vc2dump: text dump SMPTE ST 2042 VC-2 bitstream files
  • MXFDump: text dumper for MXF files from the AAF SDK. This utility is made available and built as part of libMXF.

The following input and output wrapper formats and flavours are supported:

The following essence formats are supported:

Topics

A number of topics are described in more detail in the docs/ directory, including the following:

Build, Test and Install

bmx is developed on Ubuntu Linux but is supported on other Unix-like systems and Windows.

The cmake build system is used, with minimum version 3.12. The build requires the git tool along with the C/C++ compilers.

The build process has been tested on Ubuntu, Debian, MacOS and Windows (Microsoft Visual C++ 2017 v15.9.51 and later versions).

Dependencies

The libMXF and libMXF++ libraries are provided in the deps/ directory.

The uriparser and expat libraries are required. These libraries are typically provided as software packages on Unix-like systems; the Ubuntu / Debian package names are liburiparser-dev and libexpat1-dev. The libraries are built from the GitHub source when building on Windows using Microsoft Visual Studio C++.

The uuid library (Ubuntu / Debian package name uuid-dev) is also required for non-Apple Unix-like systems.

The libcurl (Ubuntu / Debian package name libcurl4-openssl-dev) library is an optional dependency for Unix-like systems. It enables support for reading MXF files over HTTP(S). Add the -DBMX_BUILD_WITH_LIBCURL=ON option to the cmake configure command to include it in the build.

Commands

A basic commandline process is described here for platforms that default to the Unix Makefiles or Visual Studio cmake generators. See build.md for more detailed build options.

Replace <build type> in the commandlines below with Debug or Release. Note that the Visual Studio generator supports multiple build types for a configuration, which is why the build type is selected after configuration.

The default generator can be overridden using the cmake -G option. The list of available generators is shown at the end of the output of cmake --help.

Start by creating a build directory and change into it. The commandlines below use a out/build build directory in the working tree, which follows the approach taken by Microsoft Visual Studio C++.

Unix-like (Unix Makefiles)

Build and test using

mkdir -p out/build
cd out/build
cmake ../../ -DCMAKE_BUILD_TYPE=<build type>
cmake --build .
make test

Install using

sudo make install

The installation may require root permissions. Add -DCMAKE_INSTALL_PREFIX=<install dir> (fill in <install dir>) to the first cmake command above to change the installation directory.

If not using macOS, run ldconfig to update the runtime linker cache. This avoids library link errors similar to "error while loading shared libraries".

sudo /sbin/ldconfig

Windows (Visual Studio)

Build and test using

mkdir out\build
cd out\build
cmake ..\..\
cmake --build . --config <build type>
ctest -C <build type>

Install using

cmake --build . --config <build type> --target install

The installation may require administrator privileges. Add -DCMAKE_INSTALL_PREFIX=<install dir> (fill in <install dir>) to the first cmake command above to change the installation directory.

Building External Applications

External applications that require bmx can be built using cmake similar to the simple executable example shown below.

cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
project(example_project LANGUAGES CXX)

include(FetchContent)
FetchContent_Declare(bmx
    GIT_REPOSITORY "https://github.com/bbc/bmx"
    GIT_TAG "origin/main"
)
FetchContent_GetProperties(bmx)
if(NOT bmx_POPULATED)
    FetchContent_Populate(bmx)
    add_subdirectory(${bmx_SOURCE_DIR} ${bmx_BINARY_DIR})
endif()

add_executable(example example.cpp)
target_link_libraries(example bmx)

The BMX_BUILD_LIB_ONLY cmake option can be set to ON to avoid building the apps and examples in bmx, libMXF and libMXF++. Setting the option to ON will disable the bmx tests because they requires the apps. Add this line to the cmake

set(BMX_BUILD_LIB_ONLY ON CACHE BOOL "Build bmx, MXF and MXF++ libraries only")

Docker

The bmxtools Docker images are made available in the GitHub Container Registry. Pull the latest version using,

docker pull ghcr.io/bbc/bmxtools:latest

The docker/bmx_docker.sh shell script is provided to make it easier to run the Docker container. Run

./docker/bmx_docker.sh

See Docker Run for more details on the script.

Docker Build

The Dockerfile is used for building a Docker image containing a set of tools from bmx, libMXF and AAF SDK.

The Dockerfile contains a build and runtime layer:

  • build: builds and checks the libMXF, libMXF++ and bmx code.
  • runtime: provides the commandline tool executables built in the build layer.

The runtime Docker image can be built in the top-level directory using docker build,

DOCKER_BUILDKIT=1 docker build -t bmxtools .

If you are behind a proxy then remember to use the --build-arg commandline arguments to set the Docker proxy ARGS.

Docker Run

The docker/bmx_docker.sh shell script is provided to make it easier to run the Docker container. Run

./docker/bmx_docker.sh

to see the usage and list of available tools.

The script maps the file user and group ID so that files have the user's identity when written to the output directory on the host. This is needed if Docker runs the container as the root user.

The script bind mounts input and output directories on the host to /input and /output directories on the container. The default is to set input and output directories to the current host directory.

If the input and output directories are the same then that directory is also bind mounted to the container's working directory. If the input or output directory is the current directory then it is also bind mounted to the container's working directory.

This example runs bmxtranswrap from input ./in.mxf to output ./out.mxf.

./docker/bmx_docker.sh bmxtranswrap -o out.mxf in.mxf

This example runs bmxtranswrap from input ./in.mxf to output /tmp/out.mxf.

./docker/bmx_docker.sh --output /tmp bmxtranswrap -o /output/out.mxf in.mxf

This example runs bmxtranswrap from input ./sources/in.mxf to output ./dests/out.mxf.

./docker/bmx_docker.sh --input ./sources --output ./dests bmxtranswrap -o /output/out.mxf /input/in.mxf

Source and Binary Distributions

Source distributions, including dependencies, and binaries are made available in the Releases on GitHub. Older distributions can be found on SourceForge.

Source and binary distributions are generally only created when a new feature is required for creating standard compliant sample files for example, or when a release hasn't been made for a long time.

Conan

Additionally bmx (including MXF and MXF++) is available via the Conan package manager for C/C++: bmx Conan recipe. Conan Center Index offers precompiled packages for many target systems and otherwise allows to build locally according to a local conan build profile. Follow the code snippets and documentation on the linked page for integrating it.

License

The bmx library is provided under the BSD 3-clause license. See the COPYING file provided with this library for more details.