[MPlayer-dev-eng] [PATCH] less amateurish-looking mpcf.txt
Michael Niedermayer
michaelni at gmx.at
Fri Mar 25 13:50:56 CET 2005
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[32;4m'[0ms recomm[32;4me[0m[31;4ma[0mnded to be done that way[32;4m,[0m but it[32;4m'[0ms not strictly required
@@--
@@++
Syntax:
Since nut heav[32;4mi[0mly uses variable leng[32;4mth[0m[31;4mht[0m fields[32;4m,[0m the simplest way to describe it
is using a pseudocode approach.
@@--
@@++
Conventions:
The data t[32;4my[0m[31;4mi[0mpes 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 bit[32;4mst[0mream syntax element[32;4ms[0m have a tagname and a functional definition, they [32;4m
[0mare[32;4m [0m[31;4m
[0mpresented in a bottom up approach, again optional notes may follow and [32;4m
[0mare reproduced in the tag description:
name: (optional note)
@@--
@@++
[Note: strings MUST be encoded in utf8]
vb (variable leng[32;4mth[0m[31;4mht[0m binary data or string)
length v
value b
@@--
@@++
0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)
frame_startcodes SHOULD be placed immed[32;4miate[0m[31;4meat[0mly 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[32;4m. T[0m[31;4m, t[0mhe current value[31;4ms[0m is 2[32;4m.[0m
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[31;4m a[0m too long [32;4mof a [0mchain
SHOULD be set to <=32768 or at least <=65536 unless there is a very
good reason to set it higher[32;4m,[0m 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 a[32;4mn[0m id which is lower th[32;4ma[0m[31;4me[0mn 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 [32;4mNOT[0m[31;4mnot[0m be 0
time_base_nom and time_base_denom MUST be relative[32;4mly[0m 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 [32;4mNOT[0m[31;4mnot[0m be 0
global_time_base_nom and global_time_base_denom MUST be relative[32;4mly[0m 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 [32;4mNOT[0m[31;4mnot[0m depend(1) upon frames prior to the last
frame_startcode
Important: depend(1) means depend[32;4me[0m[31;4ma[0mncy on the container level (NUT) not
depend[32;4me[0m[31;4ma[0mncy on the codec level
stream_id_plus1[frame_code]
must be <250
if it[32;4m is 0,[0m[31;4ms 0[0m 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[32;4m is an[0m[31;4ms a[0m lsb
timestamp, otherwise it[32;4m i[0ms 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 [32;4mMUST[0m[31;4mmust[0m be used if there is no reference timestamp
available after the last frame_startcode with the current stream_id
@@--
@@++
dts
dts [32;4mis[0m[31;4mare[0m 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[32;4m
[0m[31;4m [0mthis[32;4m [0m[31;4m
[0mbuffer 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
th[32;4ma[0m[31;4me[0mn 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 relative[32;4mly[0m prime if not zero
MUST be 0 if unknown
@@--
@@++
index_timestamp
value of the time[32;4ms[0mtamp 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 th[32;4ma[0m[31;4me[0mn max_index_distance
ap[31;4mp[0mart
id
the id of the type/name pair, so it[32;4m'[0ms 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[32;4m'[0mt 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[32;4m [0mthe 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 rep[32;4me[0mated, but if they are[32;4m,[0m then they MUST all be repeated [32;4m
[0mtogether[32;4m [0m[31;4m
[0mand repeated headers MUST be identical
headers MAY only repeat[31;4med[0m at the closest possible positions after 2^x where x[32;4m [0m[31;4m
[0mis[32;4m
[0m[31;4m [0man integer and the file end, so the headers may be repeated at 4102 if that[32;4m [0m[31;4m
[0mis[32;4m
[0m[31;4m [0mthe closest pos[31;4ms[0mition after 2^12=4096 at which the headers can be placed
headers MUST be placed at least at the [32;4mstart[0m[31;4mbegin[0m of the file and immed[32;4miate[0m[31;4meat[0mly 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 [32;4mNOT[0m[31;4mnot[0m 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 [32;4mMUST[0m[31;4mmust[0m be
placed before any video/audio/... frames
Index
Note: [32;4mwith[0m[31;4min case of[0m realtime streaming[32;4m,[0m there is no end, so no index there either
Info packets
the info_packet can be repeated, [32;4mand[0m[31;4mit[0m can also contain different names & values
each time[32;4m,[0m but only if [31;4malso [0mthe time is different
Info packets can be used to describe the file or some part of it (chapters)
info packets[31;4m,[0m SHOULD be placed at the [32;4mstart[0m[31;4mbegin[0m 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)[32;4m;
[0m[31;4m
[0m
for(i=0; i<count; i++){
val <<=8;
@@--
@@++
uint64_t val=0;
assert(count>0 && count<9)[32;4m;[0m
for(i=count-1; i>=0; i--){
@@--
@@++
More information about the MPlayer-dev-eng
mailing list