ISO Base Media File Format (ISOBMFF) Reference Implementation

The project uses clang-format to enforce coding style in the libisomediafile library. To format all .c, .h, and .cpp files within the IsoLib/libisomediafile directory, use the following command. Ensure clang-format is installed and in your PATH.

find IsoLib/libisomediafile -name "*.h" -o -name "*.cpp" -o -name "*.c" | xargs clang-format -style=file -i

The project provides documentation in two formats:

• API Reference: Hosted on GitHub Pages.
• Usage Examples & Legacy API Docs: Available on the project Wiki.

To generate documentation locally, use Doxygen with the provided Doxyfile.

doxygen Doxyfile

If you want to integrate the core library into another project without building the command-line tools, tests, or submodule dependencies, use the ISOBMFF_BUILD_LIB_ONLY=ON flag. For maximum compatibility during integration, you may also want to disable strict warnings.

# Library-only integration (no submodules needed)
cmake -DISOBMFF_BUILD_LIB_ONLY=ON ..
make

# Relaxed build for integration (library-only + no strict warnings)
cmake -DLIBISOMEDIAFILE_STRICT_WARNINGS=OFF -DISOBMFF_BUILD_LIB_ONLY=ON ..

By default, build artifacts are placed in the build directory. To place binaries in <source>/bin/ and libraries in <source>/lib/, enable SET_CUSTOM_OUTPUT_DIRS.

cmake -DSET_CUSTOM_OUTPUT_DIRS=ON ..
make
# Outputs: bin/hevc_muxer, lib/liblibisomediafile.a, etc.

To build the entire project including the core library and all command-line tools, follow these steps on a Linux platform:

1. Clone the repository.
2. Create and enter a build directory.
3. Run cmake .. to configure the build.
4. Run make to compile.

git clone https://github.com/MPEGGroup/isobmff.git
cd isobmff
mkdir build && cd build
cmake ..
make

The isoiff_tool is the reference software for the Still Image File Format. It is designed to work with bitstreams created by the HEVC reference software (HM) using the main-still-image profile.

Key components include:

• libisoiff: A C library used to create and manipulate image collections. It abstracts the ISO Base Media Meta box structure and supports various image formats and metadata.
• isoiff_tool: A command-line tool that utilizes libisoiff and HEVC's HM software to create image collections from single HEVC images.

Note on Scope: libisoiff and isoiff_tool are specifically designed for image collections (consisting of Meta atoms). They do not support image sequences (which consist of track atoms, similar to movies).

The tool supports the following core operations:

• DRC_to_MP4: Converts DRC data into an MP4-compatible format.
• MP4_to_DRC: Extracts or converts DRC information from an MP4 file.

The project uses CMake for configuration. You can pass several flags to customize the build output and dependencies.

Building these components requires a specific directory structure (a "build folder") to ensure relative paths for includes work correctly. All dependencies must be placed within this build folder.

Dependencies

1. libisomediafile: Required by libisoiff. Download the folder structure and build it for your target OS.
2. HM (HEVC Reference Software): Required by isoiff_tool to parse NAL units.
   • Download the trunk folder.
   • Rename the trunk folder to HM.
   • Build HM for your target OS.

Build Order

1. Place libisomediafile and HM in your build folder.
2. Build libisomediafile.
3. Build HM.
4. Build libisoiff.
5. Build isoiff_tool.

Note: If dependencies are not found in the expected locations, you must adjust the dependency paths in the build configuration.

To compile the FAVS example software on Windows using Visual Studio, build the following solutions in order:

1. Build the libisomediafile solution: IsoLib/libisomediafile/w32/libisomediafile/libisomedia.sln
2. Build the favs_example solution: IsoLib/favs_example/w32/favs_example.sln

The output will be generated in IsoLib/libisomediafile/w32/libisomediafile/Debug/ (or Release/).

# Use Visual Studio to build:
# 1. IsoLib/libisomediafile/w32/libisomediafile/libisomedia.sln
# 2. IsoLib/favs_example/w32/favs_example.sln

The DRC tools (DRC_to_MP4 and MP4_to_DRC) are strongly coupled with the MPEG-D reference software and libisomediafile.

Build Steps:

1. Download the MPEG-D reference software and build drcToolDecoder and drcToolEncoder.
2. Build libisomediafile.
3. Copy or link the built MPEG-D reference software and libisomediafile into the same folder as the drc_in_isom directory.
4. Build DRC_to_MP4 and MP4_to_DRC.