Author: ivo Date: Fri Nov 24 17:31:48 2006 New Revision: 21191 Modified: trunk/DOCS/tech/nut.txt Log: specify, where possible, the type of the tags in the tag description section Modified: trunk/DOCS/tech/nut.txt ============================================================================== --- trunk/DOCS/tech/nut.txt (original) +++ trunk/DOCS/tech/nut.txt Fri Nov 24 17:31:48 2006 @@ -410,42 +410,42 @@ the very first thing in every nut file, useful for identifying nut files -*_startcode +*_startcode (f(64)) all startcodes start with 'N' -main_startcode +main_startcode (f(64)) 0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48) -stream_startcode +stream_startcode (f(64)) 0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48) -syncpoint_startcode +syncpoint_startcode (f(64)) 0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48) -index_startcode +index_startcode (f(64)) 0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48) -info_startcode +info_startcode (f(64)) 0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48) -version +version (v) NUT version. The current value is 3. All lower values are pre-freeze -stream_count +stream_count (v) number of streams in this file -time_base_count +time_base_count (v) number of different time bases in this file this MUST NOT be 0 -forward_ptr +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 +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 @@ -466,7 +466,7 @@ frameheader. -max_pts_distance +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 @@ -475,11 +475,11 @@ on the same stream, as it is altered by syncpoint timestamps. SHOULD NOT be higher than 1/timebase -stream_id +stream_id (v) Stream identifier stream_id MUST be < stream_count -stream_class +stream_class (v) 0 video 1 audio 2 subtitles @@ -487,7 +487,7 @@ Note: the remaining values are reserved and MUST NOT be used a demuxer MUST ignore streams with reserved classes -fourcc +fourcc (vb) identification for the codec example: "H264" MUST contain 2 or 4 bytes, note, this might be increased in the future @@ -495,7 +495,7 @@ 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 +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 @@ -509,7 +509,7 @@ There MUST NOT be 2 identical timebases in a file. There SHOULD NOT be more timebases than streams. -time_base_id +time_base_id (v) index into the time_base table MUST be < time_base_count @@ -543,11 +543,11 @@ if (convert_ts(b, b_timebase, a_timebase) < a) return 1; return 0; -msb_pts_shift +msb_pts_shift (v) amount of bits in lsb_pts MUST be <16 -decode_delay +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 @@ -557,11 +557,11 @@ 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 +stream_flags (v) Bit Name Description 1 FLAG_FIXED_FPS indicates that the fps is fixed -codec_specific_data +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 @@ -576,7 +576,7 @@ the encoder name and version, shall be considered essential as it is very usefull to workaround possible encoder bugs -frame_code +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 @@ -587,7 +587,7 @@ a muxer SHOULD mark 0x00 and 0xFF as invalid to improve error detection -flags[frame_code], frame_flags +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 @@ -616,39 +616,39 @@ 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] +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] +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] +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] +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] +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 +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: @@ -689,29 +689,29 @@ Dts of all frames MUST be bigger or equal to dts of all previous frames in the same stream -width/height +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/sample_height (aspect ratio) +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 +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 / samplerate_denom = samplerate +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 +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 @@ -719,13 +719,13 @@ for frame headers the checksum contains the framecode byte and all following bytes up to the checksum itself -header_checksum +header_checksum (u(32)) checksum over the startcode and forward pointer Syncpoint tags: --------------- -back_ptr_div16 +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 @@ -734,7 +734,7 @@ A stream where EOR is set is to be ignored for back_ptr. -global_key_pts +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]) @@ -744,10 +744,10 @@ Index tags: ----------- -max_pts +max_pts (t) The highest pts in the entire file -syncpoint_pos_div16 +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. @@ -764,7 +764,7 @@ 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 +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 @@ -775,11 +775,11 @@ Info tags: ---------- -stream_id_plus1 +stream_id_plus1 (v) Stream this info packet applies to. If zero, packet applies to whole file. -chapter_id +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 @@ -787,10 +787,10 @@ chapter_id n MUST not be used unless there are at least n chapters in the file -chapter_start +chapter_start (t) timestamp of start of chapter -chapter_len +chapter_len (v) Length of chapter in same timebase of chapter_start. type