Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

# bmx Library and Utilities

bmx is a library and set of utilities to read and write the [SMPTE ST 377-1 MXF file format](https://ieeexplore.ieee.org/document/7292073).
bmx is a library and set of utilities to read and write the [SMPTE ST 377-1 MXF file format](https://doi.org/10.5594/SMPTE.ST377-1).

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.

Expand Down Expand Up @@ -32,29 +32,29 @@ The following input and output wrapper formats and flavours are supported:
* [AMWA AS-02](https://www.amwa.tv/specifications) MXF Versioning
* [AMWA AS-10](https://www.amwa.tv/specifications) MXF for Production
* [AMWA AS-11](https://www.amwa.tv/specifications) Media Contribution File Formats (MXF)
* [SMPTE ST 378](https://ieeexplore.ieee.org/document/7291764) MXF OP1a
* [SMPTE RDD 9](https://ieeexplore.ieee.org/document/7290714) MXF MPEG Long GOP (Sony XDCAM)
* [SMPTE ST 386](https://ieeexplore.ieee.org/document/7291350) MXF D-10 (Sony MPEG IMX)
* [SMPTE ST 2067-5](https://ieeexplore.ieee.org/document/9099734) Interoperable Master Format (IMF) - Essence Component
* [SMPTE ST 378](https://doi.org/10.5594/SMPTE.ST378.2004) MXF OP1a
* [SMPTE RDD 9](https://doi.org/10.5594/SMPTE.RDD9.2013) MXF MPEG Long GOP (Sony XDCAM)
* [SMPTE ST 386](https://doi.org/10.5594/SMPTE.ST386.2004) MXF D-10 (Sony MPEG IMX)
* [SMPTE ST 2067-5](https://doi.org/10.5594/SMPTE.ST2067-5) Interoperable Master Format (IMF) - Essence Component
* [Avid native MXF OPAtom](https://www.avid.com/static/resources/common/documents/mxf.pdf)
* [WAV](https://en.wikipedia.org/wiki/WAV)

The following essence formats are supported:

* [SMPTE RP 2027](https://ieeexplore.ieee.org/document/7290936) AVC-Intra video, class 50 / 100 / 200
* [SMPTE ST 356](https://ieeexplore.ieee.org/document/7290684) D-10 video, 30 / 40 / 50 MBit/s
* [SMPTE RP 2027](https://doi.org/10.5594/SMPTE.RP2027.2012) AVC-Intra video, class 50 / 100 / 200
* [SMPTE ST 356](https://doi.org/10.5594/SMPTE.ST356.2001) D-10 video, 30 / 40 / 50 MBit/s
* [DV](https://en.wikipedia.org/wiki/DV) video, 25 / 50 / 100 MBit/s
* [MPEG-2](https://www.itu.int/rec/T-REC-H.262) Long GOP video, 422P@HL, MP@HL (1920 and 1440) and MP@H14
* [JPEG 2000](https://www.itu.int/rec/T-REC-T.800) video
* [JPEG XS](https://jpeg.org/jpegxs/) video
* [H.264](https://www.itu.int/rec/T-REC-H.264) video
* [SMPTE ST 2019](https://ieeexplore.ieee.org/document/7291983) VC-3 video (Avid DNxHD)
* [SMPTE ST 2042](https://ieeexplore.ieee.org/document/7967896) VC-2 video
* [SMPTE RDD 36](https://ieeexplore.ieee.org/document/7438722) video (Apple ProRes)
* [SMPTE ST 2019](https://pub.smpte.org/doc/2019/) VC-3 video (Avid DNxHD)
* [SMPTE ST 2042](https://pub.smpte.org/doc/2042/) VC-2 video
* [SMPTE RDD 36](https://doi.org/10.5594/SMPTE.RDD36.2022) video (Apple ProRes)
* Uncompressed video, UYVY / v210
* Avid [MJPEG](https://en.wikipedia.org/wiki/Motion_JPEG) video
* [WAV](https://en.wikipedia.org/wiki/WAV) PCM audio
* [SMPTE ST 436](https://ieeexplore.ieee.org/document/7290051) encapsulated ANC and VBI data
* [SMPTE ST 436](https://doi.org/10.5594/SMPTE.ST436-1.2013) encapsulated ANC and VBI data
* [IMSC 1 Timed Text](https://www.w3.org/TR/ttml-imsc1.0.1/)

## Topics
Expand All @@ -69,7 +69,7 @@ including the following:
* [IMF JPEG 2000 Track Files](./docs/imf_jpeg_2000_track_files.md)
* [IMF Audio Track Files](./docs/imf_audio_track_files.md)
* [IMF ProRes Image Track Files](./docs/imf_prores_track_files.md)
* [(Beta) Audio Definition Model (ADM) & metadata RIFF chunks](./docs/audio_definition_model.md)
* [Audio Definition Model (ADM) & metadata RIFF chunks](./docs/audio_definition_model.md)

## Build, Test and Install

Expand Down Expand Up @@ -173,10 +173,10 @@ set(BMX_BUILD_LIB_ONLY ON CACHE BOOL "Build bmx, MXF and MXF++ libraries only")

## Docker

The [bmxtools](https://github.com/orgs/bbc/packages?repo_name=bmx) Docker images are made available in the GitHub Container Registry. Pull the latest version using,
The [bmxtools](https://github.com/orgs/ebu/packages?repo_name=bmx) Docker images are made available in the GitHub Container Registry. Pull the latest version using,
Comment thread
scenarnick marked this conversation as resolved.

```bash
docker pull ghcr.io/bbc/bmxtools:latest
docker pull ghcr.io/ebu/bmxtools:latest
```

The [docker/bmx_docker.sh](./docker/bmx_docker.sh) shell script is provided to make it easier to run the Docker container. Run
Expand Down Expand Up @@ -240,7 +240,7 @@ This example runs `bmxtranswrap` from input `./sources/in.mxf` to output `./dest

## Source and Binary Distributions

Source distributions, including dependencies, and binaries are made available in the [Releases](https://github.com/ebu/bmx/releases) on GitHub. Older distributions can be found on [SourceForge](https://sourceforge.net/projects/bmxlib/files/).
Source distributions, including dependencies, and binaries are made available in the [Releases](https://github.com/ebu/bmx/releases) on GitHub. Older distributions can be found on [the BBC GitHub repo](https://github.com/bbc/bmx/releases) and on [SourceForge](https://sourceforge.net/projects/bmxlib/files/).

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.

Expand Down
2 changes: 1 addition & 1 deletion apps/raw2bmx/raw2bmx.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -744,7 +744,7 @@ static void usage(const char *cmd)
printf(" The <ids> is a comma separated list of chunk IDs. Spaces are automatically appended to IDs if they are less than 4 letters\n");
printf(" The built-in WAVE chunk IDs are: %s\n", WaveReader::GetBuiltinChunkListString().c_str());
printf(" --adm-wave-chunk <id>[,<label>]* Identifies a non-builtin ADM WAVE chunk to transfer across from the input\n");
printf(" ADM Soundfield Groups can be reference this chunk\n");
printf(" ADM Soundfield Groups can reference this chunk\n");
printf(" A comma separated list of profile and level labels can be provided as well. A <label> can be:\n");
printf(" * a SMPTE UL, formatted as a 'urn:smpte:ul:...',\n");
printf(" * 'adm_itu2076', which corresponds to urn:smpte:ul:060e2b34.0401010d.04020211.01010000\n");
Expand Down
2 changes: 1 addition & 1 deletion deps/libMXF/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# libMXF

libMXF is a low-level C library for reading and writing the [SMPTE ST 377-1 MXF file format](https://ieeexplore.ieee.org/document/7292073).
libMXF is a low-level C library for reading and writing the [SMPTE ST 377-1 MXF file format](https://doi.org/10.5594/SMPTE.ST377-1).

libMXF was originally developed as part of the [Ingex Project](http://ingex.sourceforge.net/) where it supported MXF transfer, playback and storage applications. libMXF was also used in the [BBC Archive Preservation Project](https://www.bbc.co.uk/rd/publications/whitepaper275) to migrate BBC archive content from video tapes to files.

Expand Down
4 changes: 2 additions & 2 deletions deps/libMXFpp/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# libMXF++

libMXF++ is a C++ wrapper library for [libMXF](../libMXF/) that supports reading and writing the [SMPTE ST 377-1 MXF file format](https://ieeexplore.ieee.org/document/7292073).
libMXF++ is a C++ wrapper library for [libMXF](../libMXF/) that supports reading and writing the [SMPTE ST 377-1 MXF file format](https://doi.org/10.5594/SMPTE.ST377-1).

libMXF++ and [libMXF](../libMXF/) are used in the [bmx](../../) project.

Expand All @@ -10,7 +10,7 @@ libMXF++ was originally developed as part of the [Ingex Project](http://ingex.so

A number of examples can be found in the [examples](./examples) directory. These are not part of the core library and are not required to build [bmx](../../).

* [D10MXFOP1AWriter](./examples/D10MXFOP1AWriter): library code used in the [Ingex Project](http://ingex.sourceforge.net/) for writing [SMPTE ST 386](https://ieeexplore.ieee.org/document/7291350) MXF D-10 (Sony MPEG IMX) files.
* [D10MXFOP1AWriter](./examples/D10MXFOP1AWriter): library code used in the [Ingex Project](http://ingex.sourceforge.net/) for writing [SMPTE ST 386](https://doi.org/10.5594/SMPTE.ST386.2004) MXF D-10 (Sony MPEG IMX) files.
* [OPAtomReader](./examples/OPAtomReader): library code used in the [Ingex Project](http://ingex.sourceforge.net/) for recovering Avid MXF OP-Atom files after a system failure.

## Build, Test and Install
Expand Down
2 changes: 1 addition & 1 deletion docker/bmx_docker.sh
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@

SCRIPT=$(basename $0)

DEFAULT_DOCKER_IMAGE="ghcr.io/bbc/bmxtools:latest"
DEFAULT_DOCKER_IMAGE="ghcr.io/ebu/bmxtools:latest"
Comment thread
scenarnick marked this conversation as resolved.
DEFAULT_INPUT="."
DEFAULT_OUTPUT="."

Expand Down
53 changes: 39 additions & 14 deletions docs/audio_definition_model.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# (BETA) -- Audio Definition Model (ADM) and other audio metadata RIFF Chunks
# Audio Definition Model (ADM) and other audio metadata RIFF Chunks

## Quick start: Example: convert Wave+ADM (BW64) to IMF ADM Audio Track File (MXF)

Expand Down Expand Up @@ -26,21 +26,17 @@ _See below for guidance on writing `mca.txt` including specific IMF advice_

## SMPTE ST 2131 and SMPTE ST 2067-204

SMPTE ST 2131 defines a mechanism for mapping Resource Interchange File Format (RIFF) Chunks containing audio metadata to MXF files to augment MXF Sound Tracks. It defines additional MXF support specifically for the mapping and labeling of content described by Audio Definition Model (ADM) metadata (Recommendation ITU-R BS.2076) which is often carried in Broadcast Wave 64-bit (BW64) RIFF files (Recommendation ITU-R BS.2088).
[SMPTE ST 2131](https://doi.org/10.5594/SMPTE.ST2131) defines a mechanism for mapping Resource Interchange File Format (RIFF) Chunks containing audio metadata to MXF files to augment MXF Sound Tracks. It defines additional MXF support specifically for the mapping and labeling of content described by Audio Definition Model (ADM) metadata ([Recommendation ITU-R BS.2076](https://www.itu.int/rec/R-REC-BS.2076/)) which is often carried in Broadcast Wave 64-bit (BW64) RIFF files ([Recommendation ITU-R BS.2088](https://www.itu.int/rec/R-REC-BS.2088/)).

SMPTE ST 2067-204 defines a plug-in mechanism to add audio with ADM metadata to IMF Compositions.

Both documents are currently available as Public Committee Drafts (PCD):
* https://github.com/SMPTE/st2131
* https://github.com/SMPTE/st2067-204
[SMPTE ST 2067-204](https://doi.org/10.5594/SMPTE.ST2067-204) defines a plug-in mechanism to add audio with ADM metadata to IMF Compositions.

## bmx support

Provisional support for SMPTE ST 2131 (PCD) has been implemented in `bmx`. This allows the creation of MXF files for a variety of use cases, including ADM Audio Track Files for use in IMF Compositions (per SMPTE ST 2067-204 (PCD)).
Support for [SMPTE ST 2131](https://doi.org/10.5594/SMPTE.ST2131) has been implemented in `bmx`. This allows the creation of MXF files for a variety of use cases, including ADM Audio Track Files for use in IMF Compositions (per [SMPTE ST 2067-204](https://doi.org/10.5594/SMPTE.ST2067-204)).

The following formats are supported:
* **Component form**
* Audio as Wave / raw PCM, \<chna\> text file (`bmx` format as [defined below](#chna-text-file-definition-format)) and Wave/RIFF chunk data files (e.g. ADM XML file)
* Audio as Wave / raw PCM, \<chna\> text file (`bmx` format as [defined below](#chna-text-file-format)) and Wave/RIFF chunk data files (e.g. ADM XML file)
* **Wave (BW64)**
* Reading Wave (BW64) with access to Wave chunks (e.g. ADM \<axml\>) and a parsed ADM \<chna\> chunk
* Writing Wave (BW64) with additional Wave chunks (e.g. ADM \<axml\>) and a serialised ADM \<chna\> chunk
Expand All @@ -66,20 +62,22 @@ The known limitations in the current implementation are:
- mxf2raw doesn't yet show ADM metadata presence or extraction of all related signalling.
- There is no parsing of the ADM metadata. Therefore, re-wrapping a file using raw2bmx or bmxtranswrap with an offset or duration change might result in the ADM metadata and references becoming invalid. For example, an ADM audio object might no longer be available after re-wrapping, or its start offset might have changed.
- \> 4 GB chunk size is only supported for the \<data\> chunk. The ADM chunks are unlikely to be that large but ideally `bmx` would provide support.
- raw2bmx doesn't provide a way to set the MXF properties `RIFFChunkUUID` and `RIFFChunkHashSHA1` defined by [SMPTE ST 2131](https://doi.org/10.5594/SMPTE.ST2131)

## Wave+ADM to MXF+ADM mapping process

The process of mapping Wave+ADM to MXF+ADM is basically as follows:

- A \<chna\> chunk is converted to a ADM_CHNASubDescriptor in each Sound Track using the audio channel mapping defined by the `--track-map` option
- Any null / placeholder entries (those with a trackIndex/track_index of zero) are discarded
- The `--no-chna-chunk` option can be used to ignore the \<chna\> chunk
- The `--wave-chunks` and `--adm-wave-chunk` options are used to select the (non built-in) chunks to transfer to the MXF file
- The built-in chunks that can't be selected are: \<JUNK\>, \<ds64\>, \<fmt\>, \<fact\>, \<bext\>, \<data\> and \<chna\>
- The chunk data is copied into MXF generic streams and each will have a RIFFChunkDefinitionSubDescriptor associated with it
- Sound Tracks containing channels originating from the input file will reference all the chunks from that input file using RIFFChunkReferencesSubDescriptors
- The `--adm-wave-chunk` option is the same as `--wave-chunks` except that:
- It identifies only one chunk at a time (but can be used multiple times) and signals that the chunk contains ADM metadata
- ADM Profile/Level labels can be provided with the option
- ADM Profile/Level labels can be provided with the option ([see below](#adm-profilelevel-labels))
- An ADMAudioMetadataSubDescriptor descriptor is created and it sits alongside the RIFFChunkDefinitionSubDescriptor for the chunk

## Creating a Wave+ADM sample file
Expand All @@ -88,7 +86,7 @@ A Wave+ADM sample file can be created using the following example commandline gi

`raw2bmx -t wave -o output.wav --wave-chunk-data axml.xml axml --chna-audio-ids chna.txt --wave input.wav`

The \<axml\> file `axml.xml` contains the data that will be written into the \<axml\> chunk. The \<chna\> text file `chna.txt` lists the audio identifiers that make up the \<chna\> chunk. The format of the text file is described in [\<chna\> Text file Definition Format](#chna-text-file-definition-format).
The \<axml\> file `axml.xml` contains the data that will be written into the \<axml\> chunk. The \<chna\> text file `chna.txt` lists the audio identifiers that make up the \<chna\> chunk. The format of the text file is described in [\<chna\> Text file Definition Format](#chna-text-file-format).

A Wave+ADM sample file can be created without a \<axml\> chunk, i.e. just a \<chna\> chunk, using the following example commandline given a Wave file (which doesn't have a \<axml\> chunk!) and a \<chna\> text file:

Expand Down Expand Up @@ -173,16 +171,16 @@ The following extra properties can be used on any line where the `chunk_id` prop

### MCA details for IMF ADM Audio Track Files

If an IMF Audio Track File is being created following Operational Mode A (see SMPTE ST 2067-204) then the following example approach to creating MCA is likely to be appropriate:
If an IMF Audio Track File is being created following Operational Mode A (see [SMPTE ST 2067-204](https://doi.org/10.5594/SMPTE.ST2067-204)) then the following example approach to creating MCA is likely to be appropriate:

* Write one soundfield group (SG) "label line" for each audioProgramme element defined by the ADM metadata, with the audioProgramme ID put into ADMAudioProgrammeID
* Start each soundfield group (SG) "label line" with `ADM, chunk_id=axml`
* Set RFC5646SpokenLanguage and MCATitle to match the ADM metadata (see ST 2067-204 for details)
* Set RFC5646SpokenLanguage and MCATitle to match the ADM metadata (see [SMPTE ST 2067-204](https://doi.org/10.5594/SMPTE.ST2067-204) for details)
* RFC5646SpokenLanguage can be left out when appropriate
* RFC5646SpokenLanguage uses RFC 5646 language tags whereas ADM suggests the use of older ISO 639-1 or -2 codes so translation might be needed
- MCATitleVersion is always "n/a" unless there are special requirements
- Set MCAContent and MCAUseClass to properly represent the content of each audioProgramme
- Refer to SMPTE ST 377-41 for values and to https://www.imfug.com/TR/audio-track-files/ for examples (Note: the IMF UG document uses the same values but populates older MCA properties)
- Refer to [SMPTE ST 377-41](https://doi.org/10.5594/SMPTE.ST377-41) for values and to https://www.imfug.com/TR/audio-track-files/ for examples (Note: the IMF UG document uses the same values but populates older MCA properties)

### MXF creation commandline for MCA

Expand Down Expand Up @@ -240,3 +238,30 @@ uid: ATU_00000004
track_ref: AT_00010002_01
pack_ref: AP_00010002
```

## ADM Profile/Level labels

The raw2bmx option `--adm-wave-chunk` is used in the following form in most of the examples above:

```
--adm-wave-chunk axml,adm_itu2076
```

The first part of the value (`axml`) identifies the non-builtin ADM WAVE chunk to transfer across from the input.

The second part (`adm_itu2076`) identifies that the `ADMProfileLevelULBatch` property is to include the Label with Symbol `ADM_ITU2076`. This signals that the ADM metadata conforms to [Recommendation ITU-R BS.2076](https://www.itu.int/rec/R-REC-BS.2076/) but is not further constrained by any defined Profile or Level.

If the ADM is in fact constrained by a Profile/Level then this should be signalled. Other Labels must be formatted as 'urn:smpte:ul:...'

For example, if the ADM conforms to [Recommendation ITU-R BS.2168](https://www.itu.int/rec/R-REC-BS.2168/) ADM Emission Profile Version "1", Level "0" then the following could be used:

```
--adm-wave-chunk axml,urn:smpte:ul:060e2b34.0401010d.04020211.02010000
```

Multiple Labels can be specified if required (comma separated).

Normally there should be one Label for each `profile` sub-element of the `profileList` element (if present) in the ADM metadata.

Labels for ADM Profiles/Levels have been added to the SMPTE Metadata Registers. These Labels are used by all MXF/IMF ADM & S-ADM mappings. Labels can be viewed in this public XML file (search for "ADMProfileLevel"): https://registry.smpte-ra.org/view/draft/Labels.xml

2 changes: 1 addition & 1 deletion docs/imf_audio_track_files.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# IMF Audio Track Files

The following examples demonstrate how the [IMF Flavour](./imf_track_files.md) of raw2bmx can be used to create Audio Track Files, from multichannel WAV files, that conform to version 1.2 of the [BBC UHD Delivery Document](https://www.dropbox.com/s/tkvwxksgy3izpca/TechnicalDeliveryStandardsBBCUHDiPlayerSupplement.pdf?dl=0). They have wide general applicability as they follow [IMF User Group Best Practice](https://www.imfug.com/TR/audio-track-files/).
The following examples demonstrate how the [IMF Flavour](./imf_track_files.md) of raw2bmx can be used to create Audio Track Files, from multichannel WAV files, that conform to version 1.2 of the [BBC UHD Delivery Document](https://www.bbc.co.uk/delivery/technical-requirements). They have wide general applicability as they follow [IMF User Group Best Practice](https://www.imfug.com/TR/audio-track-files/).

```bash
raw2bmx -o {Type}_{fp_uuid}.mxf \
Expand Down
Loading
Loading