Mercurial > mplayer.hg
changeset 14854:ebc5136f2a56
some comments and whitespace changes by (Luca Barbato <lu_zero gentoo org>)
| author | michael |
|---|---|
| date | Tue, 01 Mar 2005 00:16:44 +0000 |
| parents | 7e2e8e1bab8d |
| children | 24d7981dec20 |
| files | DOCS/tech/mpcf.txt |
| diffstat | 1 files changed, 101 insertions(+), 57 deletions(-) [+] |
line wrap: on
line diff
--- a/DOCS/tech/mpcf.txt Mon Feb 28 14:08:07 2005 +0000 +++ b/DOCS/tech/mpcf.txt Tue Mar 01 00:16:44 2005 +0000 @@ -37,12 +37,37 @@ Syntax: +Since nut heavly uses variable lenght fields the simplest way to describe it +is using a pseudocode approach. + + Conventions: + +The data tipes have a name, used in the bitstream syntax description, a short +text description and a pseudocode (functional) definition, optional notes may +follow: + +name (text description) + functional definition + [Optional notes] + +The bitream syntax element have a tagname and a functional definition, they are +presented in a bottom up approach, again optional notes may follow and are reproduced in the tag description: + +name: (optional note) + functional definition + [Optional notes] + +The in-depth tag description follows the bitstream syntax. +The functional definition has a C like syntax. + + Type definitions: -f(x) n fixed bits in big-endian order -u(x) unsigned number encoded in x bits in MSB first order -v +f(n) (n fixed bits in big-endian order) +u(n) (unsigned number encoded in n bits in MSB first order) + +v (variable length value, unsigned) value=0 do{ more_data u(1) @@ -50,38 +75,43 @@ value= 128*value + data }while(more_data) -s +s (variable length value, signed) temp v temp++ if(temp&1) value= -(temp>>1) else value= (temp>>1) -b (binary data or string) +b (binary data or string, to be use in vb, see below) for(i=0; i<length; i++){ data[i] u(8) } - Note: strings MUST be encoded in utf8 + [Note: strings MUST be encoded in utf8] -vb +vb (variable lenght binary data or string) length v value b Bitstream syntax: -packet header + + Common elements: + +packet header: forward ptr v -align_byte +align_byte: while(not byte aligned) one f(1) -reserved_bytes +reserved_bytes: for(i=0; i<forward_ptr - length_of_non_reserved; i++) reserved u(8) - a demuxer MUST ignore any reserved bytes + [a demuxer MUST ignore any reserved bytes a muxer MUST NOT write any reserved bytes, as this would make it - inpossible to add new fields at the end of packets in the future in - a compatible way + impossible to add new fields at the end of packets in the future in + a compatible way] + + Headers: main header: main_startcode f(64) @@ -152,8 +182,9 @@ reserved_bytes checksum u(32) + Basic Packets: -frame +frame: frame_code f(8) if(stream_id_plus1[frame_code]==0){ stream_id v @@ -168,7 +199,7 @@ reserved v data -Index: +index: index_startcode f(64) packet header stream_id v @@ -200,11 +231,13 @@ reserved_bytes checksum u(32) -sync_point +sync_point: frame_startcode f(64) global_timestamp v -file + Complete definition: + +file: file_id_string while(!eof && next_code != index_startcode){ main_header @@ -226,9 +259,14 @@ } index + + + Tag description: + forward_ptr size of the packet (exactly the distance from the first byte of the - startcode of the current packet to the first byte of the following packet + startcode of the current packet to the first byte of the following + packet file_id_string "nut/multimedia container\0" @@ -238,13 +276,16 @@ main_startcode 0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48) + stream_starcode 0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48) + frame_startcode 0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48) + frame_startcodes SHOULD be placed immedeatly before a keyframe if the previous frame of the same stream was a non-keyframe, unless such - non-keyframe - keyframe tansitions are very frequent + non-keyframe - keyframe transitions are very frequent index_startcode 0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48) @@ -252,25 +293,27 @@ 0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48) version - 2 for now + NUT version, the current values is 2 max_distance max distance of frame_startcodes, the distance may only be larger if - there is only a single frame between the 2 frame_startcodes - this can be used by the demuxer to detect damaged frame headers if the - damage results in a too long chain - SHOULD be set to <=32768 or at least <=65536 unless there is a very good - reason to set it higher otherwise reasonable error recovery will be - impossible + there is only a single frame between the 2 frame_startcodes this can + be used by the demuxer to detect damaged frame headers if the damage + results in a too long chain + + SHOULD be set to <=32768 or at least <=65536 unless there is a very + good reason to set it higher otherwise reasonable error recovery will + be impossible max_index_distance max distance of keyframes which are represented in the index, the distance between consecutive entries A and B may only be larger if there are no keyframes within this stream between A and B - SHOULD be set to <=32768 or at least <=65536 unless there is a very good - reason to set it higher + SHOULD be set to <=32768 or at least <=65536 unless there is a very + good reason to set it higher stream_id[FIXME] + Stream identifier Note: streams with a lower relative class MUST have a lower relative id so a stream with class 0 MUST always have a id which is lower then any stream with class > 0 @@ -281,7 +324,7 @@ 1 audio 2 subtiles 3 metadata - Note the remaining values are reserved and MUST NOT be used + Note: the remaining values are reserved and MUST NOT be used a demuxer MUST ignore streams with reserved classes fourcc @@ -305,8 +348,9 @@ 44100 1 44100 1 44100 64 11025 16 48000 1024 375 8 - Note: the advantage to using a large sample_rate_mul is that the - timestamps need fewer bits + + Note: the advantage to using a large sample_rate_mul is that + the timestamps need fewer bits global_time_base_nom / global_time_base_denom = global_time_base the number of timer ticks per second @@ -316,14 +360,15 @@ global_timestamp timestamp in global_time_base units - when a global_timestamp is encountered the last_timestamp of all streams - is set to the following: + when a global_timestamp is encountered the last_timestamp of all + streams is set to the following: + ln= global_time_base_denom*time_base_nom sn= global_timestamp d1= global_time_base_nom d2= time_base_denom last_timestamp= (ln/d1*sn + ln%d1*sn/d1)/d2 - Note, this calculation MUST be done with unsigned 64 bit integers, and + Note: this calculation MUST be done with unsigned 64 bit integers, and is equivalent to (ln*sn)/(d1*d2) but this would require a 96bit integer msb_timestamp_shift @@ -331,10 +376,10 @@ MUST be <16 decode_delay - maximum time between input and output for a codec, used to generate dts - from pts - is 0 for streams without b frames, and 1 for streams with b frames, may - be larger for future codecs + maximum time between input and output for a codec, used to generate + dts from pts + is set to 0 for streams without b frames, and set to 1 for streams with + b frames, may be larger for future codecs fixed_fps 1 indicates that the fps is fixed @@ -348,17 +393,17 @@ different from the first byte of any startcode flags[frame_code] - the bits of the flags from MSB to LSB are KD + first of the flags from MSB to LSB are called KD if D is 1 then data_size_msb is coded, otherwise data_size_msb is 0 K is the keyframe_type 0-> no keyframe, 1-> keyframe, flags=4 can be used to mark illegal frame_code bytes frame_code=78 must have flags=4 - * frames MUST not depend(1) upon frames prior to the last + Note: frames MUST not depend(1) upon frames prior to the last frame_startcode - depend(1) means dependancy on the container level (NUT) not dependancy - on the codec level + Important: depend(1) means dependancy on the container level (NUT) not + dependancy on the codec level stream_id_plus1[frame_code] must be <250 @@ -377,8 +422,8 @@ data_size= data_size_lsb + data_size_msb*data_size_mul; coded_timestamp - if coded_timestamp < (1<<msb_timestamp_shift) then its a - lsb timestamp, otherwise its a full timestamp + (1<<msb_timestamp_shift) + if coded_timestamp < (1<<msb_timestamp_shift) then its a lsb + timestamp, otherwise its a full timestamp + (1<<msb_timestamp_shift) lsb timestamps are converted to full timesamps by: mask = (1<<msb_timestamp_shift)-1; delta= last_timestamp - mask/2 @@ -387,7 +432,7 @@ available after the last frame_startcode with the current stream_id lsb_timestamp - least significant bits of the timestamp in time_base precission + least significant bits of the timestamp in time_base precision Example: IBBP display order keyframe timestamp=0 -> timestamp=0 frame lsb_timestamp=3 -> timestamp=3 @@ -405,8 +450,8 @@ dts dts are calculated by using a decode_delay+1 sized buffer for each stream, into which the current pts is inserted and the element with - the smallest value is removed, this is then the current dts - this buffer is initalized with decode_delay -1 elements + the smallest value is removed, this is then the current dts this + buffer is initalized with decode_delay -1 elements all frames with dts == timestamp must be monotone, that means a frame which occures later in the stream must have a larger or equal dts then an earlier frame @@ -487,8 +532,7 @@ value of this name/type pair stuffing - 0x80 can be placed infront of any type v entry for stuffing - purposes + 0x80 can be placed in front of any type v entry for stuffing purposes info_table[][2]={ {NULL , NULL }, // end @@ -520,9 +564,9 @@ headers may be repated, but if they are then they MUST all be repeated together and repeated headers MUST be identical -headers MAY only repeated at the closest possible positions after 2^x where x is -an integer and the file end, so the headers may be repeated at 4102 if thats the -closest possition after 2^12=4096 at which the headers can be placed +headers MAY only repeated at the closest possible positions after 2^x where x +is an integer and the file end, so the headers may be repeated at 4102 if that +is the closest possition after 2^12=4096 at which the headers can be placed headers MUST be placed at least at the begin of the file and immedeatly before the index or at the file end if there is no index @@ -544,9 +588,9 @@ each time but only if also the time is different Info packets can be used to describe the file or some part of it (chapters) -info packets, SHOULD be placed at the begin of the file at least -for realtime streaming info packets will normally be transmitted when they apply -for example, the current song title & artist of the currently shown music video +info packets, SHOULD be placed at the begin of the file at least for realtime +streaming info packets will normally be transmitted when they apply for +example, the current song title & artist of the currently shown music video Unknown packets MUST be ignored by the demuxer @@ -554,8 +598,8 @@ demuxer (non-normative) in the absence of valid header at beginning, players SHOULD search for backup -headers starting at offset 2^x for each x players SHOULD end their search from a -particular offset when any startcode is found (including syncpoint) +headers starting at offset 2^x for each x players SHOULD end their search from +a particular offset when any startcode is found (including syncpoint) Sample code (GPL, & untested)