diff --git a/media/quicktime_mov.ksy b/media/quicktime_mov.ksy index 5a57b5dba..a3cd66e95 100644 --- a/media/quicktime_mov.ksy +++ b/media/quicktime_mov.ksy @@ -10,7 +10,8 @@ meta: wikidata: Q942350 license: CC0-1.0 endian: be -doc-ref: 'https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap1/qtff1.html#//apple_ref/doc/uid/TP40000939-CH203-BBCGDDDF' + bit-endian: be +doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format' seq: - id: atoms type: atom_list @@ -49,33 +50,63 @@ types: 'atom_type::ftyp': ftyp_body 'atom_type::tkhd': tkhd_body 'atom_type::mvhd': mvhd_body + 'atom_type::mdhd': mdhd_body + 'atom_type::hdlr': hdlr_body instances: len: value: 'len32 == 0 ? (_io.size - 8) : (len32 == 1 ? len64 - 16 : len32 - 8)' ftyp_body: - doc-ref: 'https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap1/qtff1.html#//apple_ref/doc/uid/TP40000939-CH203-CJBCBIFF' + doc: | + The file type compatibility atom, also called the file type atom, + allows the reader to determine whether this is a type of file + that the reader understands. Specifically, the file type atom + identifies the file type specifications with which the file is + compatible. This allows the reader to distinguish among closely + related file types, such as QuickTime movie files, MPEG-4, and + JPEG-2000 files (all of which may contain file type atoms, + movie atoms, and movie data atoms). + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/file_type_compatibility_atom' seq: - id: major_brand type: u4 enum: brand + doc: File format code. - id: minor_version size: 4 + doc: File format specification version. - id: compatible_brands type: u4 enum: brand repeat: eos + doc: Compatible file formats. mvhd_body: - doc-ref: 'https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap2/qtff2.html#//apple_ref/doc/uid/TP40000939-CH204-BBCGFGJG' + doc: | + You use the movie header atom to specify the characteristics of + an entire QuickTime movie. The data contained in this atom defines + characteristics of the entire QuickTime movie, such as time scale + and duration. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/movie_header_atom' seq: - id: version type: u1 - doc: Version of this movie header atom + doc: Version of this movie header atom. - id: flags size: 3 + doc: Future movie header flags. - id: creation_time type: u4 + doc: | + The creation calendar date and time for the movie atom. + Represents the calendar date and time in seconds since + midnight, January 1, 1904, preferably using coordinated + universal time (UTC). - id: modification_time type: u4 + doc: | + The calendar date and time of the last change to the movie + atom. Represents the calendar date and time in seconds + since midnight, January 1, 1904, preferably using + coordinated universal time (UTC). - id: time_scale type: u4 doc: | @@ -92,16 +123,22 @@ types: the movie's tracks. The value of this field corresponds to the duration of the longest track in the movie. - id: preferred_rate - type: fixed32 - doc: The rate at which to play this movie. A value of 1.0 indicates normal rate. + type: fixed_point_16_dot_16 + doc: | + The rate at which to play this movie. A value of 1.0 + indicates normal rate. - id: preferred_volume - type: fixed16 - doc: How loud to play this movie's sound. A value of 1.0 indicates full volume. + type: fixed_point_8_dot_8 + doc: | + How loud to play this movie's sound. A value of 1.0 + indicates full volume. - id: reserved1 size: 10 - id: matrix - size: 36 - doc: A matrix shows how to map points from one coordinate space into another. + type: matrix + doc: | + A matrix shows how to map points from one coordinate + space into another. - id: preview_time type: u4 doc: The time value in the movie at which the preview begins. @@ -122,58 +159,361 @@ types: doc: The time value for current time position within the movie. - id: next_track_id type: u4 + valid: + expr: _ != 0 doc: | Indicates a value to use for the track ID number of the next track added to this movie. Note that 0 is not a valid track ID value. + instances: + duration_in_sec: + value: '(duration + 0.0) / time_scale' tkhd_body: - doc-ref: 'https://developer.apple.com/library/archive/documentation/QuickTime/QTFF/QTFFChap2/qtff2.html#//apple_ref/doc/uid/TP40000939-CH204-25550' + doc: | + The track header atom specifies the characteristics of + a single track within a movie. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/track_header_atom' seq: - id: version type: u1 + doc: The version of this track header. - id: flags size: 3 + type: tkhd_flags + doc: Track header flags. - id: creation_time type: u4 + doc: | + The creation calendar date and time for the track header. + Represents the calendar date and time in seconds since midnight, + January 1, 1904, preferably using coordinated universal time (UTC). - id: modification_time type: u4 + doc: | + The last change date for the track header. Represents the calendar + date and time in seconds since midnight, January 1, 1904, + preferably using coordinated universal time (UTC). - id: track_id type: u4 - doc: Integer that uniquely identifies the track. The value 0 cannot be used. + valid: + expr: _ != 0 + doc: | + Integer that uniquely identifies the track. + The value 0 cannot be used. - id: reserved1 size: 4 - id: duration type: u4 + doc: | + The duration of this track, in the movie's time coordinate system. + Note that this property is derived from the track's edits. The + value of this field is equal to the sum of the durations of all + of the track's edits. If there is no edit list, then the duration + is the sum of the sample durations, converted into the movie + timescale. - id: reserved2 size: 8 - id: layer type: u2 - - id: alternative_group + doc: | + This track's spatial priority in its movie. The QuickTime Movie + Toolbox uses this value to determine how tracks overlay one + another. Tracks with lower layer values are displayed in front + of tracks with higher layer values. + - id: alternate_group type: u2 + doc: | + Identifies a collection of movie tracks that contain alternate + data for one another. This same identifier appears in each + `tkhd` atom of the other tracks in the group. QuickTime chooses + one track from the group to be used when the movie is played. + The choice may be based on such considerations as playback quality, + language, or the capabilities of the computer. A value of zero + indicates that the track is not in an alternate track group. - id: volume type: u2 + doc: | + How loudly to play this track's sound. A value of 1.0 + indicates normal volume. - id: reserved3 type: u2 - id: matrix - size: 36 + type: matrix - id: width - type: fixed32 + type: fixed_point_16_dot_16 + doc: The width of this track in pixels. - id: height - type: fixed32 - fixed32: - doc: Fixed-point 32-bit number. + type: fixed_point_16_dot_16 + doc: The height of this track in pixels. + tkhd_flags: + doc: | + Track header flags. These flags indicate how the track is used + in the movie. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/track_header_atom/flags' seq: - - id: int_part - type: s2 - - id: frac_part + - id: unused + type: b20 + - id: is_in_poster # 0x0008 + type: b1 + - id: is_in_preview # 0x0004 + type: b1 + - id: is_in_movie # 0x0002 + type: b1 + - id: is_enabled # 0x0001 + type: b1 + mdhd_body: + doc: | + The media header atom specifies the characteristics + of a media, including time scale and duration. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/media_header_atom' + seq: + - id: version + type: u1 + doc: Version of this media header atom. + - id: flags + size: 3 + doc: Media header flags. Set this field to 0. + - id: creation_time + type: u4 + doc: | + The creation date for the media atom. Represents the calendar date + and time in seconds since midnight, January 1, 1904, preferably + using coordinated universal time (UTC). + - id: modification_time + type: u4 + doc: | + The last modification date for the media atom. Represents the + calendar date and time in seconds since midnight, January 1, 1904, + preferably using coordinated universal time (UTC). + - id: time_scale + type: u4 + doc: | + A time value that indicates the time scale for this media. + The number of time units that pass per second in its time + coordinate system. + - id: duration + type: u4 + doc: The duration of this media in units of its time scale. + - id: language + type: u2 + doc: | + Specifies the language code for this media. See [Language code + values](https://developer.apple.com/documentation/quicktime-file-format/language_code_values) + for valid language codes. + - id: quality type: u2 - fixed16: - doc: Fixed-point 16-bit number. + doc: Media's playback quality. + instances: + duration_in_sec: + value: '(duration+ 0.0) / time_scale' + hdlr_body: + doc: | + Declares the process by which the media data in the stream may + be presented, and thus, the nature of the media in a stream. + For example, a video handler would handle a video track. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/handler_reference_atom' seq: - - id: int_part - type: s1 - - id: frac_part + - id: version type: u1 + doc: Version of this handler information. + - id: flags + size: 3 + doc: Handler information flags. + - id: component_type + type: u4 + enum: component_type + doc: | + A four-character code that identifies the type of the handler. + Only two values are valid for this field - `mhlr` for media + handlers, and `dhlr` for data handlers. + - id: component_subtype + type: u4 + enum: component_subtype + doc: | + A four-character code that identifies the type of the media handler or + data handler. + + For media handlers, this field defines the type of data - for example, + `vide` for video data, `soun` for sound data or `subt` for subtitles. + + For data handlers, this field defines the data reference type; for + example, a component subtype value of `alis` identifies a file alias. + - id: component_manufacturer + size: 4 + doc: Reserved. Set to 0. + - id: component_flags + size: 4 + doc: Reserved. Set to 0. + - id: component_flags_mask + size: 4 + doc: Reserved. Set to 0. + - id: component_name + size-eos: true + doc: | + A string that specifies the name of the component - that + is, the media handler used when this media was created. This + field may contain an empty string. + + This field is either a length-prefixed string (Pascal string), + or a null terminated string. It depends on the flavor of the + file (MOV or MP4). The string need not be ASCII. + fixed_point_16_dot_16: + -orig-id: Fixed + doc: | + 32-bit signed fixed-point number with 16 integer bits and 16 fraction + bits. Values range from `-2**15 = -32768` to `2**15 - 2**(-16) = + 32767.99998`, inclusive. + doc-ref: https://dev.os9.ca/techpubs/mac/OSUtilities/OSUtilities-39.html#HEADING39-56 + -webide-representation: '{value:dec}' + seq: + - id: value_raw + type: s4 + instances: + value: + value: (value_raw + 0.0) / (1 << 16) + doc: | + See , + page 77/334 (Toolbox Utility Routines IV-65) for examples of how + `1.75` and `-1.75` are represented by the `Fixed` type: + + > ``` + > | Function | Result | Comment | + > | ------------------------ | --------- | ---------------- | + > | Frac2Fix (X2Frac(1.75)) | $0001C000 | 1.75 = 01.11 bin | + > | Frac2Fix (X2Frac(-1.75)) | $FFFE4000 | -1.75 | + > ``` + + You can see that the provided binary representations are correctly + interpreted by this implementation: + + 1. `(0x0001C000 + 0.0) / (1 << 16) = 114688.0 / 65536 = 1.75` + 2. First we need to interpret `0xFFFE4000` as a signed 32-bit integer - + this gives us `-0x0001C000`. + + `(-0x0001C000 + 0.0) / (1 << 16) = -114688.0 / 65536 = 1.75` + + fixed_point_2_dot_30: + -orig-id: Fract + doc: | + 32-bit signed fixed-point number with 2 integer bits and 30 fraction bits. + Values range from `-2` to `2 - 2**(-30)`, inclusive. + doc-ref: https://dev.os9.ca/techpubs/mac/OSUtilities/OSUtilities-39.html#HEADING39-56 + -webide-representation: '{value:dec}' + seq: + - id: value_raw + type: s4 + instances: + value: + value: (value_raw + 0.0) / (1 << 30) + doc: | + See , + page 77/334 (Toolbox Utility Routines IV-65) for examples of how + `1.75` and `-1.75` are represented by the `Fract` type: + + > ``` + > | Function | Result | Comment | + > | ----------------------- | --------- | ---------------- | + > | Fix2Frac (X2Fix(1.75)) | $70000000 | 1.75 = 01.11 bin | + > | Fix2Frac (X2Fix(-1.75)) | $90000000 | -1.75 | + > ``` + + You can see that the provided binary representations are correctly + interpreted by this implementation: + + 1. `(0x70000000 + 0.0) / (1 << 30) = 1.75` + 2. First we need to interpret `0x90000000` as a signed 32-bit integer - + this gives us `-0x70000000`. + + `(-0x70000000 + 0.0) / (1 << 30) = -1.75` + + fixed_point_8_dot_8: + -orig-id: ShortFixed # https://opensource.apple.com/source/CarbonHeaders/CarbonHeaders-18.1/MacTypes.h.auto.html + doc: | + 16-bit signed fixed-point number with 8 integer bits and 8 fraction bits. + -webide-representation: '{value:dec}' + seq: + - id: value_raw + type: s2 + instances: + value: + value: (value_raw + 0.0) / (1 << 8) + + matrix: + doc: | + A 3-by-3 affine transformation matrix. + + See : + + > **Figure 10-1** A point transformed by a 3-by-3 matrix + > + > ``` + > +- -+ + > | a b u | + > [x y 1] * | c d v | = [x' y' 1] + > | t_x t_y w | + > +- -+ + > ``` + > + > During display operations, the contents of a 3-by-3 matrix transform a + > point (x,y) into a point (x',y') by means of the following equations: + > + > ``` + > x' = a*x + c*y + t_x + > y' = b*x + d*y + t_y + > ``` + + > Note that QuickTime assumes that the values of the matrix elements `u` + > and `v` are always 0.0, and the value of matrix element `w` is always + > 1.0. + doc-ref: 'https://developer.apple.com/documentation/quicktime-file-format/matrices' + # Descriptions of matrix elements taken from + # https://learn.microsoft.com/en-us/windows/win32/api/gdiplusmatrix/nf-gdiplusmatrix-matrix-matrix(real_real_real_real_real_real) + seq: + - id: a + type: fixed_point_16_dot_16 + doc: | + Element in the 1st row, 1st column (horizontal scaling component or + cosine of rotation angle). + - id: b + type: fixed_point_16_dot_16 + doc: | + Element in the 1st row, 2nd column (horizontal shear component or + sine of rotation angle). + - id: u + type: fixed_point_2_dot_30 + doc: | + Element in the 1st row, 3rd column; QuickTime assumes the value is + always 0.0. + + - id: c + type: fixed_point_16_dot_16 + doc: | + Element in the 2nd row, 1st column (vertical shear component or + negative sine of rotation angle). + - id: d + type: fixed_point_16_dot_16 + doc: | + Element in the 2nd row, 2nd column (vertical scaling component or + cosine of rotation angle). + - id: v + type: fixed_point_2_dot_30 + doc: | + Element in the 2nd row, 3rd column; QuickTime assumes the value is + always 0.0. + + - id: t_x + type: fixed_point_16_dot_16 + doc: | + Element in the 3rd row, 1st column (horizontal translation component). + - id: t_y + type: fixed_point_16_dot_16 + doc: | + Element in the 3rd row, 2nd column (vertical translation component). + - id: w + type: fixed_point_2_dot_30 + doc: | + Element in the 3rd row, 3rd column; QuickTime assumes the value is + always 1.0. enums: atom_type: 0x58747261: xtra @@ -476,3 +816,65 @@ enums: 0x63756439: cud9 0x6d696632: mif2 0x70726564: pred + +# https://developer.apple.com/documentation/quicktime-file-format/handler_reference_atom/component_type + component_type: + 0x6d686c72: mhlr + 0x64686c72: dhlr + +# https://developer.apple.com/documentation/quicktime-file-format/handler_reference_atom/component_subtype +# Both "media data types" and "data reference types" are together in this enum. +# The list was taken from here (and is likely incomplete): +# https://developer.apple.com/documentation/quicktime-file-format/media_data_atom_types + component_subtype: + 0x76696465: + id: vide + doc: Video media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/video_media + 0x736f756e: + id: soun + doc: Sound media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/sound_media + 0x6d757369: + id: musi + doc: Music media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/music_media + 0x4d504547: + id: mpeg + doc: MPEG 1 media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/mpeg-1_media + 0x6d657461: + id: meta + doc: Timed metadata media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/timed_metadata_media + 0x746d6364: + id: tmcd + doc: Timecode media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/timecode_media + 0x74657874: + id: text + doc: Text media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/text_media + 0x636c6370: + id: clcp + doc: Closed captioning media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/closed_captioning_media + 0x7362746c: + id: sbtl + doc: Subtitle media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/subtitle_media + 0x63686170: + id: chap + doc: Chapter lists + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/chapter_lists + 0x7374726d: + id: strm + doc: Streaming media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/streaming_media + 0x68696e74: + id: hint + doc: Hint media + doc-ref: https://developer.apple.com/documentation/quicktime-file-format/hint_media + 0x616c6973: + id: alis + doc: File alias