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 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:

AMWA AS-02 MXF Versioning
AMWA AS-10 MXF for Production
AMWA AS-11 Media Contribution File Formats (MXF)
SMPTE ST 378 MXF OP1a
SMPTE RDD 9 MXF MPEG Long GOP (Sony XDCAM)
SMPTE ST 386 MXF D-10 (Sony MPEG IMX)
SMPTE ST 2067-5 Interoperable Master Format (IMF) - Essence Component
Avid native MXF OPAtom
WAV

The following essence formats are supported:

SMPTE RP 2027 AVC-Intra video, class 50 / 100 / 200
SMPTE ST 356 D-10 video, 30 / 40 / 50 MBit/s
DV video, 25 / 50 / 100 MBit/s
MPEG-2 Long GOP video, 422P@HL, MP@HL (1920 and 1440) and MP@H14
JPEG 2000 video
H.264 video
SMPTE ST 2019 VC-3 video (Avid DNxHD)
SMPTE ST 2042 VC-2 video
SMPTE RDD 36 video (Apple ProRes)
Uncompressed video, UYVY / v210
Avid MJPEG video
WAV PCM audio
SMPTE ST 436 encapsulated ANC and VBI data
IMSC 1 Timed Text

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 required. They are included as git submodules in the deps/ directory. Run

git submodule update --init

to ensure the submodules are available and up-to-date in the working tree.

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

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

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)

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

Docker

A Dockerfile is provided 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.

Build

Ensure that the libMXF and libMXFpp git submodules are available and up-to-date in the deps/ directory by running,

git submodule update --init

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.

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 for the Windows build, and Windows binaries are made available in this GitHub repo. 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.

License

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

pcipriano / bmx