--- title: User data atoms framework: quicktime-file-format role: collectionGroup role_heading: API Collection path: quicktime-file-format/user_data_atoms --- # User data atoms Atoms you use to define and store data associated with a QuickTime object. ## Overview Overview User data atoms allow you to define and store data associated with a QuickTime object, such as a movie 'moov', track 'trak', or media 'mdia'. This includes both information that QuickTime looks for, such as copyright information or whether a movie should loop, and arbitrary information — provided by and for your application — that QuickTime simply ignores. A user data atom whose immediate parent is a movie atom contains data relevant to the movie as a whole. A user data atom whose parent is a track atom contains information relevant to that specific track. A QuickTime movie file may contain many user data atoms, but only one user data atom is allowed as the immediate child of any given movie atom or track atom. The user data atom has an atom type of 'udta'. Inside the user data atom is a list of atoms describing each piece of user data. User data provides a simple way to extend the information stored in a QuickTime movie. For example, user data atoms can store a movie’s window position, playback characteristics, or creation information. This section describes the data atoms that QuickTime recognizes. You may create new data atom types that your own application recognizes. Applications should ignore any data atom types that they do not recognize. User data list entry types The user data list entry types are as follows. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The user-data items labelled “keywords” and marked as “For Sorting” are for use when the display text does not have a pre-determined sorting order (for example, in oriental languages when the sorting depends on the contextual meaning). These keywords can be sorted algorithmically to place the corresponding items in correct order. The window location, looping, play selection only, play all frames, and print to video atoms control the way QuickTime displays a movie. These atoms are interpreted only if the user data atom’s immediate parent is a movie atom ('moov'). If they are included as part of a track atom’s user data, they are ignored. User data text strings and language codes All user data list entries whose type begins with the © character (ASCII 169) are defined to be international text. These list entries must contain a list of text strings with associated language codes. By storing multiple versions of the same text, a single user data text item can contain translations for different languages. The list of text strings uses a small integer atom format, which is identical to the QuickTime atom format except that it uses 16-bit values for size and type instead of 32-bit values. The first value is the size of the string, including the size and type, and the second value is the language code for the string. User data text strings may use either Macintosh text encoding or Unicode text encoding. The format of the language code determines the text encoding format. Macintosh language codes are followed by Macintosh-encoded text. If the language code is specified using the ISO language codes listed in specification ISO 639-2/T, the text uses Unicode text encoding. When Unicode is used, the text is in UTF-8 unless it starts with a byte-order-mark (BOM, 0xFEFF), in which case the text is in UTF-16. Both the BOM and the UTF-16 text should be big-endian. Multiple versions of the same text may use different encoding schemes. important: Language code values less than 0x400 are Macintosh language codes. Language code values greater than or equal to 0x400 are ISO language codes. The exception to this rule is language code 0x7FFF, which indicates an unspecified Macintosh language. ISO language codes are three-character codes. In order to fit inside a 16-bit field, the characters must be packed into three 5-bit subfields. This packing is described in Language code values. Media characteristic tags A track ('trak') atom’s user data atom may contain zero or more media characteristic tag atoms ('tagc'). The media characteristic tag atom’s payload data is a tag that indicates something of interest about the track. This is a specialized string consisting of a subset of US-ASCII (7 bits plus a clear high bit) characters and conforming to the structure described in the following paragraphs. This is not a C string; there is no terminating null, so the number of characters is determined from the atom’s size. Legal characters are alphabetic (A-Z, a-z), digits (0-9), dash (-), period (.), underscore (_), and tilde (~). Any track of a QuickTime file can be associated with one or more tags that indicate the media’s characteristics. Tags indicate something of interest about a track. For example, a tag could indicate the purpose of the track (it is commentary), an abstract characteristic of the track (it requires hardware decoding), or an indication that the track includes legible text (a chapter track and subtitle track both can be read by the user). Comparison of tags is case sensitive; two tags match if the bytes of the strings match exactly. To avoid possible confusion for developers or content creators, don’t use two tag strings differing only by case. Duplicate tags in a single track are allowed but are discouraged. Duplication has no special meaning. Tag strings are not localized and are meant to be machine interpreted; however, mnemonic strings are encouraged. A tag is either public or private: Public tags allow shared semantics to be deployed widely. Apple defines public tags. Private tags can be defined for private use. Tag strings have the following structure: A public tag starts with the prefix “public.”, which is followed by one or more segments separated by periods. Examples (not defined) might be public.subtitle or public.commentary.director. note: Public tags are public because they are documented in this specification or are available in Apple APIs. Other definitions of tags with the “public.” prefix are prohibited; use private tags instead. A private tag starts with the private entity’s domain using a reverse DNS naming convention. For example, apple.com becomes com.apple. This is followed by one or more segments separated by periods. Examples (not defined) might be com.apple.this-is-a-tag, com.apple.video.includes-sign-language, and org.w3c.html5.referenced-video. The only allowed prefixes are “public.” and reversed domains. All other prefixes are reserved for future use. note: Generic top-level domains other than “public” (if it were to be assigned) are supported. The string “public” is reserved to signal public media characteristic tags. This specification defines the following public media characteristic tags. Other public and private tags could be defined outside the specification; unrecognized tags should be ignored. ## Topics ### Atoms for user data - [User data atom ('udta')](quicktime-file-format/user_data_atom.md) - [Track name atom ('tnam')](quicktime-file-format/track_name_atom.md) - [Print to video atom ('ptv ')](quicktime-file-format/print_to_video_atom.md) ## See Also ### Describing movies - [Movie atom ('moov')](quicktime-file-format/movie_atom.md) - [Movie header atom ('mvhd')](quicktime-file-format/movie_header_atom.md) - [Color table atom ('ctab')](quicktime-file-format/color_table_atom.md) - [Interleaving movie data](quicktime-file-format/interleaving_movie_data.md)