tv.amwa.maj.io.mxf (Media Authoring with Java API)
Date: 2016-02-05

# Package tv.amwa.maj.io.mxf

Support for the serialization of AAF data to and from KLV format files and streams according to the SMPTE MXF standards.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  BodyClosedCompletePartitionPack | Represents the description of body partition that is closed and complete.
  BodyClosedIncompletePartitionPack | Represents the description of body partition that is closed and incomplete.
  BodyOpenCompletePartitionPack | Represents the description of body partition that is open and complete.
  BodyOpenIncompletePartitionPack | Represents the description of body partition that is open and incomplete.
  BodyPartition | Represents a body partition of an MXF file, providing access to its constituent parts.
  BodyPartitionPack | Represents the description of a body partition, including its size and what it contains.
  CPSystemItem |
  DeltaEntry | Elements of an array defining byte offset values along an incrementing timeline, mapping indexed elements into slices.
  EssenceContainer |
  EssenceElement |
  EssencePartition |
  EssenceSubParserFactory | Specifies a class that can create a new essence sub-parser instance.
  FixedLengthPack | Labels a metadata object that can be serialized as a fixed length pack for which the order of the values in the buffer is important.
  FooterClosedCompletePartitionPack | Represents the description of footer partition that is closed and complete.
  FooterClosedIncompletePartitionPack | Represents the description of footer partition that is closed and incomplete.
  FooterPartition | Represents the footer partition of an MXF file, providing access to its constituent parts.
  FooterPartitionPack | Represents the description of a footer partition, including its size and what it contains.
  GCSystemItem |
  HeaderClosedCompletePartitionPack | Represents the description of header partition that is closed and complete.
  HeaderClosedIncompletePartitionPack | Represents the description of header partition that is closed and incomplete.
  HeaderMetadata | Represents header metadata in an MXF file that must be present in the mandatory header partition of every MXF file.
  HeaderOpenCompletePartitionPack | Represents the description of header partition that is open and complete.
  HeaderOpenIncompletePartitionPack | Represents the description of header partition that is open and incomplete.
  HeaderPartition | Represents the header partition of an MXF file, providing access to its constituent parts.
  HeaderPartitionPack | Represents the description of a header partition, including its size and what it contains.
  IndexEntry | Element of an array that provides stream offsets and other description of an edit unit along an incrementing timeline.
  IndexTable | Represents an index table in an MXF file, providing a means to calculate byte offsets for the indexed essence container.
  IndexTableSegment | An index table segment makes up part or all of an index table.
  LocalTagEntry | Represents a single entry of the tag-to-key lookup table of a primer pack, mapping a 2 byte tag to a 16 byte key.
  MXFConstants | Constants used by the MXF capability of the MAJ API.
  MXFFile | Represents and provides access to the components of an MXF file, including the partitions that it contains.
  MXFUnit |
  Padded |
  Partition | Represents a partition of an MXF file, which is the top-level sub-division of an MXF file.
  PartitionPack | Represents a partition pack that describes and starts every partition of an MXF file.
  PrimerPack | Represents the local primer pack of header metadata required for the local set encoding of metadata objects.
  RandomIndexItem | Entry in a random index pack of an MXF file that indexes the byte offset of a partition in a file.
  RandomIndexPack | Represents a random index pack at the end of an MXF file that lists the byte offsets of all the partitions.
  TypeDefinitions | Definitions of data types used specifically in the serialization of AAF data to and from KLV format.
  UL |
  UUID |

- Class Summary
  Class | Description
  --- | ---
  BodyReader | Reads data from the body of a MXF file.
  EssenceSink | Objects that receive large quantities of essence data.
  EssenceSource | Objects that supply large quantities of essence data.
  EssenceStreamDescriptor | Description of an essence stream.
  GenericContainerElementKind | Information about each stream in a generic container.
  GenericContainerReader | Reads data from an MXF file.
  KLVObject | Implementation of a KLV triple value.
  ListOfFiles | Handles a list of files.
  MXFBuilder | Collection of static methods that provide the ability to build MXF files from in memory data models (e.g.
  MXFFactory | Factory for reading and creating MXF files.
  MXFStream |
  MXFStream.KeyAndConsumed |
  MXFStream.LengthAndConsumed |
  VBILine | A single line of VBI data.
  VBISource | VBI data for a frame, supplied as an essence source.

- Enum Summary
  Enum | Description
  --- | ---
  KLVObject.KeyFormat |
  KLVObject.LengthFormat |
  UnitType |
  VBISampleCoding | Sample coding enumeration, as per SMPTE-436M.
  VBIWrappingType | VBI wrapping type enumeration, as per SMPTE-436M.

- Exception Summary
  Exception | Description
  --- | ---
  MAJMXFStreamException |

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  EditUnitFlag | Represents a flag used in an index entry to indicate the nature of the indexed edit unit.
  GCStreamID | Labels an `int` value as a generic container stream identifier.
  MXFLength | Labels a value that represents the length of an item in an MXF file, measured in bytes.
  MXFPosition | Labels a value that represents a position in an MXF file.

## Package tv.amwa.maj.io.mxf Description

Support for the serialization of AAF data to and from KLV format files and streams according to the SMPTE MXF standards. The MXF file format is specified by SMPTE 0377-1-2009.

This implementation supports clip-based wrapping of uni-track streams into a generic container according to SMPTE ST 0385-2004. Future versions will support many more mapping and codecs, including the AMWA application specifications.

## Reading MXF partitions

MXF files, also known as AAF-KLV files, consist of sequence of partitions. Partitions contain a partition description, known as a `partition pack`, and may contain metadata, index tables and/or body essence streams.

MXF files contain one or more partitions. The first step in reading an MXF file is to build an in memory cache of the structure of those partitions as an `MXFFile`. To do this, use the `readParitions()` method of the MXF factory. For example:

    import tv.amwa.maj.industry.MediaEngine;
    import tv.amwa.maj.io.mxf.MXFFactory;
    import tv.amwa.maj.io.mxf.MXFFile;

    ...

      MXFFile mxfFile = MXFFactory.readPartitions("filename.mxf");

All MXF files contain a header partition. Most also contain a footer partition. To access these, use the `getHeaderPartition()` and `getFooterPartition()` methods. For example:

    import tv.amwa.maj.io.mxf.HeaderPartition;
    import tv.amwa.maj.io.mxf.FooterPartition;

    ...

      HeaderPartition header = mxfFile.getHeaderPartition();
      FooterPartition footer = mxfFile.getFooterPartition();

## Reading header metadata

Partitions can contain header metadata and this is split into a primer pack and a preface. The metadata can be read into memory from a file using the `readHeaderMetadata()` method.

If a footer partition is present in an MXF file and it contains header metadata, this version is often the most trusted source for metadata about the file as it was written once the rest of the file is complete. If the footer partition is not present or does not contain header metadata, read the header partition's header metadata instead. For example:

    import tv.amwa.maj.model.Preface;
    import tv.amwa.maj.io.mxf.HeaderMetadata;

    ...

      HeaderMetadata headerMD = null;
      if ((footer != null) && (footer.hasHeaderMetadata())
        headerMD = footer.readHeaderMetadata();
      else
        headerMD = header.readHeaderMetadata();

      Preface preface = headerMD.getPreface();

Methods of the preface interface can be used to interrogate what is in the MXF file, or you can call `toString()` on the preface to get an XML representation.

## Writing header metadata

To follow.

## Reading the index table

An index table maps edit unit indexes to stream offsets in essence containers. This enables the data representing a specific frame of video or audio sample to be located in the file, for example to generate a still frame or carry out a partial restore. Any long GOP structure used to store the essence can also be interrogated to work out a safe point to break a file, e.g. don't forget the preceding I-frame!

Any partition may have an index table. To read the index table and find the stream offset to the 10th frame 2nd element, measured in bytes from the beginning of its essence container, use the `readIndexTable()` method. For example:

    import tv.amwa.maj.io.mxf.IndexTable;

    ...

      IndexTable index = footer.readIndexTable();
      long tenthFrameOffset = index.streamOffset(10, 2);

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.