[MPlayer-dev-eng] [PATCH] less amateurish-looking mpcf.txt

[Michael Niedermayer]

Hi

On Friday 25 March 2005 04:35, Jeff wrote:
> First thing I'd like to clear up is that I'm very excited about NUT, I'm
> impressed with the results given by the current preliminary
> implementation in ffmpeg, and I have only respect for the people who
> contributed to the development. So, understand that I mean no offense.
>
> Someone less familiar with NUT could perhaps be forgiven for losing
> interest after trying to read the first few pages of mpcf.txt. The
> quantity and severity of the grammar and spelling errors is so bad,
> it gives the impression of a project that's dead or hopeless.
>
> I don't intend to make the text into perfect proper english writing,
> but reducing the number of highly egregious errors may help to make
> better first impressions.
>
> There are also some sentences that I find simply unparseable (maybe I
> should post examples if there's interest) but I wasn't completely sure how
> to fix them. I want to start only with no-brainer changes.

applied

btw, nice ansi colorized mndiff attached, which while its just in early 
development and theres no patch tool for it yet, its IMHO quite usefull for 
reviewing such changes

-- 
Michael

"nothing is evil in the beginning. Even Sauron was not so." -- Elrond
-------------- next part --------------
@@++

MUST	the specific part must be done to conform to this standard
SHOULD	it's recommeanded to be done that way, but it's not strictly required


@@--
@@++
			Syntax:

Since nut heavily uses variable lengthht fields, the simplest way to describe it
is using a pseudocode approach.

@@--
@@++
			Conventions:

The data tyipes have a name, used in the bitstream syntax description, a short
text description and a pseudocode (functional) definition, optional notes may
follow:
@@--
@@++
	[Optional notes]

The bitstream syntax elements 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)
@@--
@@++
	[Note: strings MUST be encoded in utf8]

vb	(variable lengthht binary data or string)
	length					v
	value					b
@@--
@@++
	0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)
	
	frame_startcodes SHOULD be placed immediateeatly before a keyframe if the
	previous frame of the same stream was a non-keyframe, unless such
	non-keyframe - keyframe transitions are very frequent
@@--
@@++

version
	NUT version. T, the current values is 2.

max_distance
@@--
@@++
	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 of a 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

@@--
@@++
	Stream identifier
	Note: streams with a lower relative class MUST have a lower relative id
	so a stream with class 0 MUST always have an id which is lower thaen any
	stream with class > 0
	stream_id MUST be < stream_count
@@--
@@++
	the number of timer ticks per second, this MUST be equal to the fps
	if the fixed_fps is 1
	time_base_denom MUST NOTnot be 0
	time_base_nom and time_base_denom MUST be relatively prime
	time_base_nom MUST be < 2^31
	examples:
@@--
@@++
global_time_base_nom / global_time_base_denom = global_time_base
	the number of timer ticks per second
	global_time_base_denom MUST NOTnot be 0
	global_time_base_nom and global_time_base_denom MUST be relatively prime
	global_time_base_nom MUST be < 2^31

@@--
@@++
	flags=4 can be used to mark illegal frame_code bytes
	frame_code=78 must have flags=4
	Note: frames MUST NOTnot depend(1) upon frames prior to the last 
	  frame_startcode
	Important: depend(1) means dependeancy on the container level (NUT) not
	dependeancy on the codec level

stream_id_plus1[frame_code]
	must be <250
	if it is 0,s 0 then the stream_id is coded in the frame

data_size_mul[frame_code]
@@--
@@++

coded_timestamp
	if coded_timestamp < (1<<msb_timestamp_shift) then it is ans a lsb
	timestamp, otherwise it is 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
	timestamp= ((timestamp_lsb-delta)&mask) + delta
	a full timestamp MUSTmust be used if there is no reference timestamp
	available after the last frame_startcode with the current stream_id
        
@@--
@@++

dts
	dts isare 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
	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
	thaen an earlier frame
	FIXME rename timestamp* to pts* ?

@@--
@@++
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
	MUST be 0 if unknown
        
@@--
@@++

index_timestamp
	value of the timestamp of a keyframe relative to the last keyframe
	stored in this index

@@--
@@++
	last keyframe stored in this index
	there MUST be no keyframe with the same stream_id as this index between
	2 consecutive index entries if they are more thaen max_index_distance
	appart

id
	the id of the type/name pair, so it's more compact
	0 means end
                
@@--
@@++
	"CreationTime"	"2003-01-20 20:13:15Z", ... 
			(ISO 8601 format, see http://www.cl.cam.ac.uk/~mgk25/iso-time.html)
			Note: don't forget the timezone
	"Keywords"
	"TotalTime"	total length of the stream in msecs
@@--
@@++
			and "multi" if several languages
			see http://www.loc.gov/standards/iso639-2/englangn.html
			and http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html the language code
	"Disposition"	"original", "dub" (translated), "comment", "lyrics", "karaoke"
	Note: if someone needs some others, please tell us about them, so we can
@@--
@@++
stream_header (id=n)

headers may be repeated, 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 that 
is
 the closest possition after 2^12=4096 at which the headers can be placed

headers MUST be placed at least at the startbegin of the file and immediateeatly before
the index or at the file end if there is no index
headers MUST be repeated at least twice (so they exist 3 times in a file)

a demuxer MUST NOTnot demux a stream which contains more than one stream, or which
is wrapped in a structure to facilitate more than one stream or otherwise 
duplicate the role of a container. any such file is to be considered invalid

info packets which describe the whole file or individual streams/tracks MUSTmust be
placed before any video/audio/... frames

		Index
Note: within case of realtime streaming, there is no end, so no index there either

		Info packets
the info_packet can be repeated, andit can also contain different names & values
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 startbegin 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
@@--
@@++
	uint64_t val=0;

	assert(count>0 && count<9);

        
	for(i=0; i<count; i++){
		val <<=8;
@@--
@@++
	uint64_t val=0;

	assert(count>0 && count<9);

	for(i=count-1; i>=0; i--){
@@--
@@++