This topic encompasses two kinds of object identifiers - the Omf "Mob" unique identifier property and the underlying Bento Container object index number. This is an important aspect of Omf and using MaxOmfSdk. It is here you must make the connections between your application's internal edit data and MaxOmfSdk objects.
Your client application will have some internal edit data design, or object model. This data must be transformed, or mapped, to the MaxOmfSdk objects to represent the composition correctly. The Omf UIDs are the key to associating your data to MaxOmfSdk's data. Bento IDs are useful when interpreting Omf data.
Lets take the "Bento ID" first. Bento records objects and their properties on disk by the rules of the Bento specification. A crucial part of the design is the "TOC" (Table Of Contents) - a lookup table of the objects and their actual byte location in the file. Here, each object is assigned a "Bento ID value" as the file is created. These are simply index integers unique to the objects in that file. Bento IDs are unique and valid only within a single Omf file, NOT across separate files.
All Omf objects recorded in an Omf file have a Bento ID. But some Omf objects are special - they are the "Mobs". Mobs have an additional unique identifier - the "Mob ID", or the omfUID_t property. It is important to take note of this difference between a "Mob" and other objects in the Omf.
The term "Mob" comes from "Media Object", in the sense that the object represents something about "media". But this name can be misleading since all the objects in an Omf represent something about "media", in a general sense. In fact, the important differences between Mobs and other Omf objects are the specific class they represent (such as "Master Mob" and "Composition Mob") and the fact they possess an Omf UID. Omf UIDs are INSTANCE identifiers - they label a specific instantiation of a Mob (a class).
This identifier is the Mob's instance identity and is how other objects refer, or link, to it. The entire Omf design relies on this mechanism - the Omf's tree of objects is hung together with links between Omf UIDs.
All Mobs in an individual Omf file MUST have unique identities. - a Mob identity collision can render an Omf useless, or worse. It is possible, and likely, that two separate Omf files may contain COPIES of Mobs, including their omfUID_t. For example, two composition Omfs from the same project timeline will have the same omfUID_ts attached to identical objects. In other words, where an identical object exists in two Omf files it will have the same omfUID_t. You should keep this in mind in system design.
The Bento IDs label all objects in the Bento Container of the Omf file, and Omf UIDs label specific objects *globally* across multiple Omf files. While the Bento IDs are useful for keeping track of things within a given file, the Omf UIDs are more important - they truly identify the Mobs. Bento IDs are useful for debugging within a given Omf file, especially tracking non-Mob objects. Omf UIDs are the real deal - this is the true identity of the Mob both within a file, and, potentially, to copies of the same Mob in external Omf files.
Bento IDs are unsigned long integers.
Omf UIDs are structures. For reference, a omfUID_t data type as declared in the Avid Omf Toolkit is -
typedef struct
{
omfInt32 prefix;
omfUInt32 major;
omfUInt32 minor;
} omfUID_t;
MaxOmfSdk declares an identical type to separate the names -
typedef struct tagMxOmfUID_t identical to Omf toolkit omfUID_t
{
signed long prefix;
unsigned long major;
unsigned long minor;
} mxOmfUID_t;
The major and minor members contain the unique value, made up by an algorithm based on system date and time.
The "prefix" requires special explanation. It is an officially registered value, assigned by Avid Corp., to identify the manufacturer or product which produced the Omf. The prefix is helpful for applications to identify the specific flavor of Omf and it is best to "play by the rules" - all manufacturers producing Omfs should have a unique prefix assignment. You obtain your prefix assignment from EdlMax with your MaxOmfSdk license.
(MaxOmfSdk will use the EdlMax prefix ID 453 for any required defaults and in the demonstration application. Two values of particular interest are - Avid products: 42 and Protools products: 444.)
Using Bento IDs and, especially, Omf UIDs, has much to do with your task of mapping data between MaxOmfSdk and your application,
The input/output data structures of MaxOmfSdk (mxOmfProjectInfo_t, mxOmfEventInfo_t, mxOmfMasterInfo_t, mxOmfTapeInfo_t) include Bento ID and Omf UID members.
On import, that is, when MaxOmfSdk has opened, read, and populated its internal data, calls to the mxOmfGetNext() functions will populate the input data structures. The m_ulxxxBentoID members will contain the Bento ID values of that Omf file's Bento objects and the m_xxxOMFUID members hold the Omf object UIDs. These can be used by you to identify and, perhaps, assign unique identities to your internal data. If your internal data model uses some form of unique identifier you might consider using, or transforming for use, the Omf UIDs because they guarantee unique object identity.
On export, that is, as your application populates MaxOmfSdk internal data before actually writing out an Omf file, there are similar and additional considerations. MaxOmfSdk input (that is, "input" to MaxOmfSdk from your application) requires each object to have a unique identify.
MaxOmfSdk provides several "smart" mechanisms for assisting you in managing UIDs. Several functions which include "unique" somewhere in their name, such as mxOmfMasterAppendUnique() and mxFileAppendUnique(), have important utility. They can check the MaxOmfSdk internal data to determine whether or not the object has already been created.
This is especially useful when looping through your data and presenting objects to MaxOmfSdk input. In most situations, as your code loops through your data, the same object may be encountered more than once. For example, if you are enumerating your "events" or "cells" along a timeline track, many events will likely use the same source material. Typically, you want only one copy of that source - there is not usually any reason to have multiple copies.
To use the SDKs "unique" functions most effectively you should supply them with an Omf UID (actually, a mxOmfUID_t) which is somehow related to your internal data objects. For example, if your system identifies objects with UUIDs (GUID) you could down-convert them to Omf UID (see GUIDs and AAF, below). If you have no explicit object identity, or if there is no reasonable way to make a one-to-one mapping of your object model to the MaxOmfSdk object model, you may need to invent a scheme to do the labeling.
The "unique" functions can be used with no (or NIL) Omf UID parameter, in which case they will automatically assign a synthesized Omf UID. A composition can be successfully created this way, and this may be useful for some limited purposes. However, it forces the creation of every object, resulting in object redundancy which can be very inefficient and may result in an awkward representation of the project for the end user.
AAF (Advanced Authoring Format) and many modern editing system architectures use UUID (Universal Unique Identifier), or its counterpart, GUID (Globally Unique Identifier), to lable objects.
GUIDs are 16 bytes, while an omfUID_t is only 8 (the "prefix" is not counted).
MxOmdSdk provides a special utility function for down-converting UUID/GUID to mxOmfUID_t - mxGUID2MxOmfUID()