comparison DOCS/tech/nut.txt @ 21175:3cdb95ea504d

specify, where possible, the type of the tags in the tag description section

21174:364075c5bc6c

file_id_string
    "nut/multimedia container\0"
    the very first thing in every nut file, useful for identifying nut
    files

*_startcode
    all startcodes start with 'N'

main_startcode
    0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48)

stream_startcode
    0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48)

syncpoint_startcode
    0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)

index_startcode
    0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48)

info_startcode
    0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48)

version
    NUT version. The current value is 3. All lower values are pre-freeze

stream_count
    number of streams in this file

time_base_count
    number of different time bases in this file
    this MUST NOT be 0

forward_ptr
    size of the packet data (exactly the distance from the first byte
    after the packet_header to the first byte of the next packet)
    every nut packet contains a forward_ptr immediately after its startcode
    with the exception of frame_code based packets, the forward pointer
    can be used to skip over the packet without decoding its contents

max_distance
    max distance between startcodes. If p1 and p2 are the byte
    positions of the first byte of two consecutive startcodes, then
    p2-p1 MUST be less than or equal to max_distance unless the entire
    span from p1 to p2 comprises a single packet or a syncpoint
    followed by a single frame. This imposition places efficient upper

    This is also half the max frame size without a checksum after the
    frameheader.


max_pts_distance
    max absolute difference of pts of new frame from last_pts in the
    timebase of the stream, without a checksum after the frameheader.
    A frame header MUST include a checksum if abs(pts-last_pts) is
    strictly greater than max_pts_distance.
    Note that last_pts is not necessarily the pts of the last frame
    on the same stream, as it is altered by syncpoint timestamps.
    SHOULD NOT be higher than 1/timebase

stream_id
    Stream identifier
    stream_id MUST be < stream_count

stream_class
    0    video
    1    audio
    2    subtitles
    3    userdata
    Note: the remaining values are reserved and MUST NOT be used
          a demuxer MUST ignore streams with reserved classes

fourcc
    identification for the codec
    example: "H264"
    MUST contain 2 or 4 bytes, note, this might be increased in the future
    if needed
    the id values used are the same as in avi, so if a codec uses a specific
    fourcc in avi then the same fourcc MUST be used here

time_base_nom / time_base_denom = time_base
    the length of a timer tick in seconds, this MUST be equal to the 1/fps
    if FLAG_FIXED_FPS is set
    time_base_nom and time_base_denom MUST NOT be 0
    time_base_nom and time_base_denom MUST be relatively prime
    time_base_denom MUST be < 2^31

        29.97     1001             30000
        23.976    1001             24000
    There MUST NOT be 2 identical timebases in a file.
    There SHOULD NOT be more timebases than streams.

time_base_id
    index into the time_base table
    MUST be < time_base_count

convert_ts
    To switch from 2 different timebases, the following calculation is

    if (convert_ts(a, a_timebase, b_timebase) < b) return -1;
    if (convert_ts(b, b_timebase, a_timebase) < a) return  1;
    return 0;

msb_pts_shift
    amount of bits in lsb_pts
    MUST be <16

decode_delay
    size of the reordering buffer used to convert pts to dts
    codecs which don't support b frames normally use 0
    mpeg1/mpeg2 style codecs with b frames use 1
    h264 style b pyramid uses 2
    h264 and future codecs might need values >2
    audio codecs generally use 0 (we aren't aware of any which doesn't
    but its theoretically possible that one exists which needs it >0)
    decode_delay MUST NOT be set higher than necessary for a codec.

stream_flags
     Bit  Name            Description
       1  FLAG_FIXED_FPS  indicates that the fps is fixed

codec_specific_data
    private global data for a codec (could be huffman tables or ...)
    if a codec has a global header it SHOULD be placed in here instead of
    at the start of every keyframe
    the exact format is specified in the codec spec
    for H.264 the NAL units MUST be formatted as in a bytestream 

    it also MUST NOT contain normal packets which cause the reference decoder
    to generate any specific decoded samples
    the encoder name and version, shall be considered essential as it is very
    usefull to workaround possible encoder bugs

frame_code
    frame_code is an 8-bit field which exists before every frame, it can
    store part of the size of the frame, the stream number, the timestamp
    and some flags amongst other things, what is not directly stored
    in it but is needed is stored in various fields immediately after it
    the values stored in it can be found in the main header
    the value 78 ('N') is forbidden to ensure that the byte is always
    different from the first byte of any startcode
    a muxer SHOULD mark 0x00 and 0xFF as invalid to improve error
    detection

flags[frame_code], frame_flags
     Bit  Name             Description
       1  FLAG_KEY         if set, frame is keyframe
       2  FLAG_EOR         if set, stream has no relevance on
                           presentation. (EOR)
       8  FLAG_CODED_PTS   if set, coded_pts is in the frame header

last_pts
    the timestamp of the last frame with the same stream_id as the current
    if there is no such frame between the last syncpoint and the current
    frame then the syncpoint timestamp is used, see global_key_pts

stream_id[frame_code]
    if FLAG_STREAM_ID is not set then this is the stream number for the
    frame following this frame_code
    if FLAG_STREAM_ID is set then this value has no meaning
    MUST be <250

data_size_mul[frame_code]
    if FLAG_SIZE_MSB is set then data_size_msb which is stored after the
    frame code is multiplied with it and forms the more significant part
    of the size of the following frame
    if FLAG_SIZE_MSB is not set then this field has no meaning
    MUST be <16384

data_size_lsb[frame_code]
    the less significant part of the size of the following frame
    this added together with data_size_mul*data_size_msb is the size of
    the following frame
    MUST be <16384

pts_delta[frame_code]
    MUST be <16384 and >-16384
    if FLAG_CODED_PTS is set in the flags of the current frame then this
    value MUST be ignored, if FLAG_CODED_PTS is not set then pts_delta is the
    difference between the current pts and last_pts

reserved_count[frame_code]
    MUST be <256

data_size
    the size of the following frame
    data_size= data_size_lsb + data_size_msb*data_size_mul;

coded_pts
    if coded_pts < (1<<msb_pts_shift) then it is an lsb
    pts, otherwise it is a full pts + (1<<msb_pts_shift)
    lsb pts is converted to a full pts by:
    mask  = (1<<msb_pts_shift)-1;
    delta = last_pts - mask/2

    previous frames in all streams, compared in common timebase. (EOR
    frames are NOT exempt from this rule)
    Dts of all frames MUST be bigger or equal to dts of all previous frames
    in the same stream

width/height
    width and height of the video in pixels
    MUST be set to the coded width/height, MUST NOT be 0

sample_width/sample_height (aspect ratio)
    sample_width is the horizontal distance between samples
    sample_width and sample_height MUST be relatively prime if not zero
    both MUST be 0 if unknown otherwise both MUST be non zero

colorspace_type
     0    unknown
     1    ITU Rec 624 / ITU Rec 601 Y range: 16..235 Cb/Cr range: 16..240
     2    ITU Rec 709               Y range: 16..235 Cb/Cr range: 16..240
    17    ITU Rec 624 / ITU Rec 601 Y range:  0..255 Cb/Cr range:  0..255
    18    ITU Rec 709               Y range:  0..255 Cb/Cr range:  0..255

samplerate_nom / samplerate_denom = samplerate
    the number of samples per second, MUST NOT be 0

crc32 checksum
    Generator polynomial is 0x104C11DB7. Starting value is zero.

checksum
    crc32 checksum
    checksum is calculated for the area pointed to by forward_ptr not
    including the checksum itself (from first byte after the
    packet_header until last byte before the checksum).
    for frame headers the checksum contains the framecode byte and all
    following bytes up to the checksum itself

header_checksum
    checksum over the startcode and forward pointer

Syncpoint tags:
---------------

back_ptr_div16
    back_ptr = back_ptr_div16 * 16 + 15
    back_ptr must point to a position within 16 bytes of a syncpoint
    startcode. This syncpoint MUST be the closest syncpoint such that at
    least one keyframe with a pts lower or equal to the original syncpoint's
    global_key_pts for all streams lies between it and the current syncpoint.

    A stream where EOR is set is to be ignored for back_ptr.

global_key_pts
    After a syncpoint, last_pts of each stream is to be set to:
    last_pts[i] = convert_ts(global_key_pts, time_base[id], time_base[i])

    global_key_pts MUST be bigger or equal to dts of all past frames across
    all streams, and smaller or equal to pts of all future frames.

Index tags:
-----------

max_pts
    The highest pts in the entire file

syncpoint_pos_div16
    offset from beginning of file to up to 15 bytes before the syncpoint
    referred to in this index entry. Relative to position of last
    syncpoint.

has_keyframe

eor_pts
    Coded only if EOR is set at the position of the syncpoint. The pts of
    that EOR. EOR is unset by the first keyframe after it.

index_ptr
    Length in bytes of the entire index, from the first byte of the
    startcode until the last byte of the checksum.
    Note: A demuxer can use this to find the index when it is written at
    EOF, as index_ptr will always be 12 bytes before the end of file if
    there is an index at all.


Info tags:
----------

stream_id_plus1
    Stream this info packet applies to. If zero, packet applies to whole
    file.

chapter_id
    Id of chapter this packet applies to. If zero, packet applies to whole
    file. Positive chapter_id's are real chapters and MUST NOT overlap.
    Negative chapter_id indicate a sub region of file and not a real
    chapter. chapter_id MUST be unique to the region it represents.
    chapter_id n MUST not be used unless there are at least n chapters in the
    file

chapter_start
    timestamp of start of chapter

chapter_len
    Length of chapter in same timebase of chapter_start.

type
    for example: "UTF8" -> string or "JPEG" -> JPEG image
    "v" -> unsigned integer

21175:3cdb95ea504d

file_id_string
    "nut/multimedia container\0"
    the very first thing in every nut file, useful for identifying nut
    files

*_startcode (f(64))
    all startcodes start with 'N'

main_startcode (f(64))
    0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48)

stream_startcode (f(64))
    0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48)

syncpoint_startcode (f(64))
    0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)

index_startcode (f(64))
    0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48)

info_startcode (f(64))
    0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48)

version (v)
    NUT version. The current value is 3. All lower values are pre-freeze

stream_count (v)
    number of streams in this file

time_base_count (v)
    number of different time bases in this file
    this MUST NOT be 0

forward_ptr (v)
    size of the packet data (exactly the distance from the first byte
    after the packet_header to the first byte of the next packet)
    every nut packet contains a forward_ptr immediately after its startcode
    with the exception of frame_code based packets, the forward pointer
    can be used to skip over the packet without decoding its contents

max_distance (v)
    max distance between startcodes. If p1 and p2 are the byte
    positions of the first byte of two consecutive startcodes, then
    p2-p1 MUST be less than or equal to max_distance unless the entire
    span from p1 to p2 comprises a single packet or a syncpoint
    followed by a single frame. This imposition places efficient upper

    This is also half the max frame size without a checksum after the
    frameheader.


max_pts_distance (v)
    max absolute difference of pts of new frame from last_pts in the
    timebase of the stream, without a checksum after the frameheader.
    A frame header MUST include a checksum if abs(pts-last_pts) is
    strictly greater than max_pts_distance.
    Note that last_pts is not necessarily the pts of the last frame
    on the same stream, as it is altered by syncpoint timestamps.
    SHOULD NOT be higher than 1/timebase

stream_id (v)
    Stream identifier
    stream_id MUST be < stream_count

stream_class (v)
    0    video
    1    audio
    2    subtitles
    3    userdata
    Note: the remaining values are reserved and MUST NOT be used
          a demuxer MUST ignore streams with reserved classes

fourcc (vb)
    identification for the codec
    example: "H264"
    MUST contain 2 or 4 bytes, note, this might be increased in the future
    if needed
    the id values used are the same as in avi, so if a codec uses a specific
    fourcc in avi then the same fourcc MUST be used here

time_base_nom (v) / time_base_denom (v) = time_base
    the length of a timer tick in seconds, this MUST be equal to the 1/fps
    if FLAG_FIXED_FPS is set
    time_base_nom and time_base_denom MUST NOT be 0
    time_base_nom and time_base_denom MUST be relatively prime
    time_base_denom MUST be < 2^31

        29.97     1001             30000
        23.976    1001             24000
    There MUST NOT be 2 identical timebases in a file.
    There SHOULD NOT be more timebases than streams.

time_base_id (v)
    index into the time_base table
    MUST be < time_base_count

convert_ts
    To switch from 2 different timebases, the following calculation is

    if (convert_ts(a, a_timebase, b_timebase) < b) return -1;
    if (convert_ts(b, b_timebase, a_timebase) < a) return  1;
    return 0;

msb_pts_shift (v)
    amount of bits in lsb_pts
    MUST be <16

decode_delay (v)
    size of the reordering buffer used to convert pts to dts
    codecs which don't support b frames normally use 0
    mpeg1/mpeg2 style codecs with b frames use 1
    h264 style b pyramid uses 2
    h264 and future codecs might need values >2
    audio codecs generally use 0 (we aren't aware of any which doesn't
    but its theoretically possible that one exists which needs it >0)
    decode_delay MUST NOT be set higher than necessary for a codec.

stream_flags (v)
     Bit  Name            Description
       1  FLAG_FIXED_FPS  indicates that the fps is fixed

codec_specific_data (vb)
    private global data for a codec (could be huffman tables or ...)
    if a codec has a global header it SHOULD be placed in here instead of
    at the start of every keyframe
    the exact format is specified in the codec spec
    for H.264 the NAL units MUST be formatted as in a bytestream 

    it also MUST NOT contain normal packets which cause the reference decoder
    to generate any specific decoded samples
    the encoder name and version, shall be considered essential as it is very
    usefull to workaround possible encoder bugs

frame_code (f(8))
    frame_code is an 8-bit field which exists before every frame, it can
    store part of the size of the frame, the stream number, the timestamp
    and some flags amongst other things, what is not directly stored
    in it but is needed is stored in various fields immediately after it
    the values stored in it can be found in the main header
    the value 78 ('N') is forbidden to ensure that the byte is always
    different from the first byte of any startcode
    a muxer SHOULD mark 0x00 and 0xFF as invalid to improve error
    detection

flags[frame_code], frame_flags (v)
     Bit  Name             Description
       1  FLAG_KEY         if set, frame is keyframe
       2  FLAG_EOR         if set, stream has no relevance on
                           presentation. (EOR)
       8  FLAG_CODED_PTS   if set, coded_pts is in the frame header

last_pts
    the timestamp of the last frame with the same stream_id as the current
    if there is no such frame between the last syncpoint and the current
    frame then the syncpoint timestamp is used, see global_key_pts

stream_id[frame_code] (v)
    if FLAG_STREAM_ID is not set then this is the stream number for the
    frame following this frame_code
    if FLAG_STREAM_ID is set then this value has no meaning
    MUST be <250

data_size_mul[frame_code] (v)
    if FLAG_SIZE_MSB is set then data_size_msb which is stored after the
    frame code is multiplied with it and forms the more significant part
    of the size of the following frame
    if FLAG_SIZE_MSB is not set then this field has no meaning
    MUST be <16384

data_size_lsb[frame_code] (v)
    the less significant part of the size of the following frame
    this added together with data_size_mul*data_size_msb is the size of
    the following frame
    MUST be <16384

pts_delta[frame_code] (s)
    MUST be <16384 and >-16384
    if FLAG_CODED_PTS is set in the flags of the current frame then this
    value MUST be ignored, if FLAG_CODED_PTS is not set then pts_delta is the
    difference between the current pts and last_pts

reserved_count[frame_code] (v)
    MUST be <256

data_size
    the size of the following frame
    data_size= data_size_lsb + data_size_msb*data_size_mul;

coded_pts (v)
    if coded_pts < (1<<msb_pts_shift) then it is an lsb
    pts, otherwise it is a full pts + (1<<msb_pts_shift)
    lsb pts is converted to a full pts by:
    mask  = (1<<msb_pts_shift)-1;
    delta = last_pts - mask/2

    previous frames in all streams, compared in common timebase. (EOR
    frames are NOT exempt from this rule)
    Dts of all frames MUST be bigger or equal to dts of all previous frames
    in the same stream

width (v) / height (v)
    width and height of the video in pixels
    MUST be set to the coded width/height, MUST NOT be 0

sample_width (v) /sample_height (v) (aspect ratio)
    sample_width is the horizontal distance between samples
    sample_width and sample_height MUST be relatively prime if not zero
    both MUST be 0 if unknown otherwise both MUST be non zero

colorspace_type (v)
     0    unknown
     1    ITU Rec 624 / ITU Rec 601 Y range: 16..235 Cb/Cr range: 16..240
     2    ITU Rec 709               Y range: 16..235 Cb/Cr range: 16..240
    17    ITU Rec 624 / ITU Rec 601 Y range:  0..255 Cb/Cr range:  0..255
    18    ITU Rec 709               Y range:  0..255 Cb/Cr range:  0..255

samplerate_nom (v) / samplerate_denom (v) = samplerate
    the number of samples per second, MUST NOT be 0

crc32 checksum
    Generator polynomial is 0x104C11DB7. Starting value is zero.

checksum (u(32))
    crc32 checksum
    checksum is calculated for the area pointed to by forward_ptr not
    including the checksum itself (from first byte after the
    packet_header until last byte before the checksum).
    for frame headers the checksum contains the framecode byte and all
    following bytes up to the checksum itself

header_checksum (u(32))
    checksum over the startcode and forward pointer

Syncpoint tags:
---------------

back_ptr_div16 (v)
    back_ptr = back_ptr_div16 * 16 + 15
    back_ptr must point to a position within 16 bytes of a syncpoint
    startcode. This syncpoint MUST be the closest syncpoint such that at
    least one keyframe with a pts lower or equal to the original syncpoint's
    global_key_pts for all streams lies between it and the current syncpoint.

    A stream where EOR is set is to be ignored for back_ptr.

global_key_pts (t)
    After a syncpoint, last_pts of each stream is to be set to:
    last_pts[i] = convert_ts(global_key_pts, time_base[id], time_base[i])

    global_key_pts MUST be bigger or equal to dts of all past frames across
    all streams, and smaller or equal to pts of all future frames.

Index tags:
-----------

max_pts (t)
    The highest pts in the entire file

syncpoint_pos_div16 (v)
    offset from beginning of file to up to 15 bytes before the syncpoint
    referred to in this index entry. Relative to position of last
    syncpoint.

has_keyframe

eor_pts
    Coded only if EOR is set at the position of the syncpoint. The pts of
    that EOR. EOR is unset by the first keyframe after it.

index_ptr (u(64))
    Length in bytes of the entire index, from the first byte of the
    startcode until the last byte of the checksum.
    Note: A demuxer can use this to find the index when it is written at
    EOF, as index_ptr will always be 12 bytes before the end of file if
    there is an index at all.


Info tags:
----------

stream_id_plus1 (v)
    Stream this info packet applies to. If zero, packet applies to whole
    file.

chapter_id (s)
    Id of chapter this packet applies to. If zero, packet applies to whole
    file. Positive chapter_id's are real chapters and MUST NOT overlap.
    Negative chapter_id indicate a sub region of file and not a real
    chapter. chapter_id MUST be unique to the region it represents.
    chapter_id n MUST not be used unless there are at least n chapters in the
    file

chapter_start (t)
    timestamp of start of chapter

chapter_len (v)
    Length of chapter in same timebase of chapter_start.

type
    for example: "UTF8" -> string or "JPEG" -> JPEG image
    "v" -> unsigned integer