2006-07-13 10:26:33 +00:00
|
|
|
==================================
|
2006-11-15 00:12:39 +00:00
|
|
|
NUT Open Container Format 20061104
|
2006-07-13 10:26:33 +00:00
|
|
|
==================================
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Intro:
|
|
|
|
======
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2006-11-04 13:33:35 +00:00
|
|
|
NUT is a Free multimedia container format for storeage of audio, video,
|
|
|
|
subtitles and related user defined streams, it provides exact timestamps for
|
|
|
|
synchronization and seeking, is simple, has low overhead and can recover
|
|
|
|
in case of errors in the stream
|
|
|
|
|
|
|
|
other common multimedia container formats are AVI, OGG, Matroska, MP4, MOV
|
|
|
|
ASF, MPEG-PS, MPEG-TS
|
|
|
|
|
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
Features / goals:
|
|
|
|
(supported by the format, not necessarily by a specific implementation)
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
Simple
|
2005-10-06 11:08:43 +00:00
|
|
|
use the same encoding for nearly all fields
|
|
|
|
simple decoding, so slow CPUs (and embedded systems) can handle it
|
|
|
|
|
2003-02-06 15:33:02 +00:00
|
|
|
Extendible
|
2005-10-06 11:08:43 +00:00
|
|
|
no limit for the possible values of all fields (using universal vlc)
|
|
|
|
allow adding of new headers in the future
|
|
|
|
allow adding more fields at the end of headers
|
|
|
|
|
2003-02-06 15:33:02 +00:00
|
|
|
Compact
|
2005-10-06 11:08:43 +00:00
|
|
|
~0.2% overhead, for normal bitrates
|
2006-01-20 19:10:55 +00:00
|
|
|
index is <100kb per hour
|
2005-10-06 11:08:43 +00:00
|
|
|
a usual header for a file is about 100 bytes (audio + video headers together)
|
2006-01-06 02:05:34 +00:00
|
|
|
a packet header is about ~1-5 bytes
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2003-02-06 15:33:02 +00:00
|
|
|
Error resistant
|
2005-10-06 11:08:43 +00:00
|
|
|
seeking / playback without an index
|
|
|
|
headers & index can be repeated
|
|
|
|
damaged files can be played back with minimal data loss and fast
|
|
|
|
resync times
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-07-13 10:26:33 +00:00
|
|
|
The spec is frozen. All files following spec will be compatible unless the
|
|
|
|
spec is unfrozen.
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
Definitions:
|
|
|
|
============
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
MUST the specific part must be done to conform to this standard
|
|
|
|
SHOULD it is recommended to be done that way, but not strictly required
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-11-03 14:10:58 +00:00
|
|
|
keyframe
|
2006-11-08 18:32:54 +00:00
|
|
|
A keyframe is a frame from which you can start decoding, a more
|
|
|
|
exact definition is below
|
2006-11-03 21:13:50 +00:00
|
|
|
The nth frame is a keyframe if and only if frames n, n+1, ... in
|
|
|
|
presentation order (that are all frames with a pts >= frame[n].pts) can
|
|
|
|
be decoded successfully without reference to frames prior n in storeage
|
|
|
|
order (that are all frames with a dts < frame[n].dts)
|
|
|
|
if no such frames exist (for example due to use of overlapped transforms
|
|
|
|
like the MDCT in an audio codec) then the definition shall be extended
|
|
|
|
by droping n out of the set of frames which must be decodable, if this
|
|
|
|
is still insufficient then n+1 shall be droped, and so on until there is
|
|
|
|
a keyframe
|
2006-11-03 21:40:13 +00:00
|
|
|
every frame which is marked as a keyframe MUST be a keyframe according to
|
|
|
|
the defintion above, a muxer MUST mark every frame it knows is a keyframe
|
|
|
|
as such, a muxer SHOULD NOT analyze future frames to determine the
|
|
|
|
keyframe status of the current frame but instead just set the frame as
|
|
|
|
non keyframe
|
2006-11-03 14:10:58 +00:00
|
|
|
(FIXME maybe move somewhere else?)
|
2006-11-13 15:23:45 +00:00
|
|
|
pts
|
|
|
|
presentation time of the first frame/sample that is completed by decoding
|
|
|
|
the coded frame.
|
|
|
|
dts
|
|
|
|
of a frame is the time when it is input into the decoder
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Syntax:
|
|
|
|
=======
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-09-09 09:25:07 +00:00
|
|
|
Since NUT heavily uses variable length fields, the simplest way to describe it
|
2005-03-01 00:16:44 +00:00
|
|
|
is using a pseudocode approach.
|
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
Conventions:
|
|
|
|
============
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-03-25 12:37:18 +00:00
|
|
|
The data types have a name, used in the bitstream syntax description, a short
|
2005-03-01 00:16:44 +00:00
|
|
|
text description and a pseudocode (functional) definition, optional notes may
|
|
|
|
follow:
|
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
name (text description)
|
|
|
|
functional definition
|
|
|
|
[Optional notes]
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
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
|
2005-03-25 12:37:18 +00:00
|
|
|
are reproduced in the tag description:
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
name: (optional note)
|
|
|
|
functional definition
|
|
|
|
[Optional notes]
|
2005-03-01 00:16:44 +00:00
|
|
|
|
|
|
|
The in-depth tag description follows the bitstream syntax.
|
2005-09-09 09:25:07 +00:00
|
|
|
The functional definition has a C-like syntax.
|
2005-03-01 00:16:44 +00:00
|
|
|
|
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Type definitions:
|
|
|
|
=================
|
2004-04-14 23:11:45 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
f(n) (n fixed bits in big-endian order)
|
|
|
|
u(n) (unsigned number encoded in n bits in MSB-first order)
|
2004-04-14 23:11:45 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
v (variable length value, unsigned)
|
|
|
|
value=0
|
|
|
|
do{
|
|
|
|
more_data u(1)
|
|
|
|
data u(7)
|
|
|
|
value= 128*value + data
|
|
|
|
}while(more_data)
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
s (variable length value, signed)
|
|
|
|
temp v
|
|
|
|
temp++
|
|
|
|
if(temp&1) value= -(temp>>1)
|
|
|
|
else value= (temp>>1)
|
2003-02-07 21:35:39 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
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 UTF-8]
|
2006-03-12 20:44:22 +00:00
|
|
|
[Note: the character NUL (U+0000) is not legal within
|
|
|
|
or at the end of a string.]
|
2003-02-06 17:19:09 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
vb (variable length binary data or string)
|
|
|
|
length v
|
|
|
|
value b
|
2004-04-04 22:40:48 +00:00
|
|
|
|
2006-03-10 14:10:07 +00:00
|
|
|
t (v coded universal timestamp)
|
|
|
|
tmp v
|
2006-03-15 16:24:24 +00:00
|
|
|
id= tmp % time_base_count
|
|
|
|
value= (tmp / time_base_count) * time_base[id]
|
2003-02-06 17:19:09 +00:00
|
|
|
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Bitstream syntax:
|
|
|
|
=================
|
|
|
|
|
2006-11-03 13:52:12 +00:00
|
|
|
file:
|
|
|
|
file_id_string
|
|
|
|
while(!eof){
|
|
|
|
if(next_byte == 'N'){
|
|
|
|
packet_header
|
|
|
|
switch(startcode){
|
|
|
|
case main_startcode: main_header; break;
|
|
|
|
case stream_startcode:stream_header; break;
|
|
|
|
case info_startcode: info_packet; break;
|
|
|
|
case index_startcode: index; break;
|
|
|
|
case syncpoint_startcode: syncpoint; break;
|
|
|
|
}
|
|
|
|
packet_footer
|
|
|
|
}else
|
|
|
|
frame
|
|
|
|
}
|
|
|
|
|
|
|
|
the structure of a undamaged file should look like the following, but
|
|
|
|
demuxers should be flexible and be able to deal with damaged headers so the
|
|
|
|
above is a better loop in practice (not to mention its simpler)
|
|
|
|
note, demuxers MUST be able to deal with new and unknown headers
|
|
|
|
|
|
|
|
file:
|
|
|
|
file_id_string
|
|
|
|
while(!eof){
|
|
|
|
packet_header, main_header, packet_footer
|
|
|
|
reserved_headers
|
|
|
|
for(i=0; i<stream_count; i++){
|
|
|
|
packet_header, stream_header, packet_footer
|
|
|
|
reserved_headers
|
|
|
|
}
|
|
|
|
while(next_code == info_startcode){
|
|
|
|
packet_header, info_packet, packet_footer
|
|
|
|
reserved_headers
|
|
|
|
}
|
|
|
|
if(next_code == index_startcode){
|
|
|
|
packet_header, index_packet, packet_footer
|
|
|
|
}
|
|
|
|
if (!eof) while(next_code != main_startcode){
|
2006-11-15 00:12:39 +00:00
|
|
|
if(next_code == syncpoint_startcode){
|
|
|
|
packet_header, syncpoint, packet_footer
|
2006-11-14 17:03:33 +00:00
|
|
|
}
|
2006-11-15 00:12:39 +00:00
|
|
|
frame
|
|
|
|
reserved_headers
|
2006-11-03 13:52:12 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Common elements:
|
|
|
|
----------------
|
2005-03-01 00:16:44 +00:00
|
|
|
|
|
|
|
reserved_bytes:
|
2005-10-06 11:08:43 +00:00
|
|
|
for(i=0; i<forward_ptr - length_of_non_reserved; i++)
|
|
|
|
reserved u(8)
|
|
|
|
[a demuxer MUST ignore any reserved bytes
|
|
|
|
a muxer MUST NOT write any reserved bytes, as this would make it
|
|
|
|
impossible to add new fields at the end of packets in the future
|
|
|
|
in a compatible way]
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2006-03-13 06:50:55 +00:00
|
|
|
packet_header
|
|
|
|
startcode f(64)
|
|
|
|
forward_ptr v
|
|
|
|
if(forward_ptr > 4096)
|
|
|
|
header_checksum u(32)
|
|
|
|
|
|
|
|
packet_footer
|
|
|
|
reserved_bytes
|
|
|
|
checksum u(32)
|
2006-03-15 16:28:31 +00:00
|
|
|
[Note: in index packet, reserved_bytes comes before index_ptr]
|
2006-03-13 06:50:55 +00:00
|
|
|
|
|
|
|
reserved_headers
|
|
|
|
while(next_byte == 'N' && next_code != main_startcode
|
|
|
|
&& next_code != stream_startcode
|
|
|
|
&& next_code != info_startcode
|
|
|
|
&& next_code != index_startcode
|
|
|
|
&& next_code != syncpoint_startcode){
|
|
|
|
packet_header
|
|
|
|
packet_footer
|
|
|
|
}
|
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
Headers:
|
2003-09-06 13:21:08 +00:00
|
|
|
|
2006-11-03 13:53:29 +00:00
|
|
|
main_header:
|
2005-10-06 11:08:43 +00:00
|
|
|
version v
|
|
|
|
stream_count v
|
|
|
|
max_distance v
|
2006-03-15 16:24:24 +00:00
|
|
|
time_base_count v
|
|
|
|
for(i=0; i<time_base_count; i++)
|
|
|
|
time_base_nom v
|
|
|
|
time_base_denom v
|
|
|
|
time_base[i]= time_base_nom/time_base_denom
|
2006-01-20 19:06:28 +00:00
|
|
|
tmp_pts=0
|
|
|
|
tmp_mul=1
|
|
|
|
tmp_stream=0
|
2005-10-06 11:08:43 +00:00
|
|
|
for(i=0; i<256; ){
|
|
|
|
tmp_flag v
|
|
|
|
tmp_fields v
|
2006-03-03 22:31:46 +00:00
|
|
|
if(tmp_fields>0) tmp_pts s
|
|
|
|
if(tmp_fields>1) tmp_mul v
|
|
|
|
if(tmp_fields>2) tmp_stream v
|
|
|
|
if(tmp_fields>3) tmp_size v
|
2005-10-06 11:08:43 +00:00
|
|
|
else tmp_size=0
|
2006-03-03 22:31:46 +00:00
|
|
|
if(tmp_fields>4) tmp_res v
|
2005-10-06 11:08:43 +00:00
|
|
|
else tmp_res=0
|
2006-03-03 22:31:46 +00:00
|
|
|
if(tmp_fields>5) count v
|
2005-10-06 11:08:43 +00:00
|
|
|
else count= tmp_mul - tmp_size
|
2006-03-03 22:31:46 +00:00
|
|
|
for(j=6; j<tmp_fields; j++){
|
2005-10-06 11:08:43 +00:00
|
|
|
tmp_reserved[i] v
|
|
|
|
}
|
|
|
|
for(j=0; j<count && i<256; j++, i++){
|
2006-02-12 17:40:02 +00:00
|
|
|
if (i == 'N') {
|
2006-03-03 22:30:17 +00:00
|
|
|
flags[i]= FLAG_INVALID;
|
2006-02-12 17:40:02 +00:00
|
|
|
j--;
|
|
|
|
continue;
|
|
|
|
}
|
2005-10-06 11:08:43 +00:00
|
|
|
flags[i]= tmp_flag;
|
2006-03-18 12:13:48 +00:00
|
|
|
stream_id[i]= tmp_stream;
|
2005-10-06 11:08:43 +00:00
|
|
|
data_size_mul[i]= tmp_mul;
|
|
|
|
data_size_lsb[i]= tmp_size + j;
|
|
|
|
pts_delta[i]= tmp_pts;
|
|
|
|
reserved_count[i]= tmp_res;
|
|
|
|
}
|
|
|
|
}
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
stream_header:
|
2005-10-06 11:08:43 +00:00
|
|
|
stream_id v
|
|
|
|
stream_class v
|
|
|
|
fourcc vb
|
2006-03-15 16:24:24 +00:00
|
|
|
time_base_id v
|
2005-10-06 11:08:43 +00:00
|
|
|
msb_pts_shift v
|
2006-02-10 10:42:40 +00:00
|
|
|
max_pts_distance v
|
2005-10-06 11:08:43 +00:00
|
|
|
decode_delay v
|
2006-03-25 07:58:07 +00:00
|
|
|
stream_flags v
|
2005-10-06 11:08:43 +00:00
|
|
|
codec_specific_data vb
|
2006-02-17 20:05:25 +00:00
|
|
|
if(stream_class == video){
|
|
|
|
width v
|
|
|
|
height v
|
|
|
|
sample_width v
|
|
|
|
sample_height v
|
|
|
|
colorspace_type v
|
|
|
|
}else if(stream_class == audio){
|
|
|
|
samplerate_nom v
|
|
|
|
samplerate_denom v
|
|
|
|
channel_count v
|
|
|
|
}
|
2005-10-06 11:08:43 +00:00
|
|
|
|
|
|
|
Basic Packets:
|
2005-09-09 10:26:21 +00:00
|
|
|
|
2005-03-01 00:16:44 +00:00
|
|
|
frame:
|
2005-10-06 11:08:43 +00:00
|
|
|
frame_code f(8)
|
2006-03-03 22:30:17 +00:00
|
|
|
frame_flags= flags[frame_code]
|
|
|
|
if(frame_flags&FLAG_CODED){
|
|
|
|
coded_flags v
|
|
|
|
frame_flags ^= coded_flags
|
2005-10-06 11:08:43 +00:00
|
|
|
}
|
2006-03-18 12:13:48 +00:00
|
|
|
if(frame_flags&FLAG_STREAM_ID){
|
|
|
|
stream_id v
|
|
|
|
}
|
|
|
|
if(frame_flags&FLAG_CODED_PTS){
|
|
|
|
coded_pts v
|
|
|
|
}
|
2006-03-03 22:30:17 +00:00
|
|
|
if(frame_flags&FLAG_SIZE_MSB){
|
|
|
|
data_size_msb v
|
2006-01-20 19:06:28 +00:00
|
|
|
}
|
2006-03-18 12:13:48 +00:00
|
|
|
if(frame_flags&FLAG_RESERVED)
|
|
|
|
reserved_count[frame_code] v
|
2005-10-06 11:08:43 +00:00
|
|
|
for(i=0; i<reserved_count[frame_code]; i++)
|
|
|
|
reserved v
|
2006-03-04 10:26:46 +00:00
|
|
|
if(frame_flags&FLAG_CHECKSUM){
|
2006-03-01 14:19:37 +00:00
|
|
|
checksum u(32)
|
2006-02-11 09:51:08 +00:00
|
|
|
}
|
2005-10-06 11:08:43 +00:00
|
|
|
data
|
|
|
|
|
2005-03-01 00:16:44 +00:00
|
|
|
index:
|
2006-03-10 14:10:07 +00:00
|
|
|
max_pts t
|
2006-01-20 19:10:55 +00:00
|
|
|
syncpoints v
|
2006-03-03 22:33:30 +00:00
|
|
|
for(i=0; i<syncpoints; i++){
|
2006-03-10 14:34:30 +00:00
|
|
|
syncpoint_pos_div16 v
|
2006-01-20 19:10:55 +00:00
|
|
|
}
|
|
|
|
for(i=0; i<stream_count; i++){
|
2006-02-13 07:29:11 +00:00
|
|
|
last_pts= -1
|
2006-03-03 22:33:30 +00:00
|
|
|
for(j=0; j<syncpoints; ){
|
2006-01-20 19:10:55 +00:00
|
|
|
x v
|
|
|
|
type= x & 1
|
|
|
|
x>>=1
|
2006-01-22 05:57:46 +00:00
|
|
|
n=j
|
2006-01-20 19:10:55 +00:00
|
|
|
if(type){
|
|
|
|
flag= x & 1
|
|
|
|
x>>=1
|
|
|
|
while(x--)
|
2006-01-22 05:57:46 +00:00
|
|
|
has_keyframe[n++][i]=flag
|
|
|
|
has_keyframe[n++][i]=!flag;
|
2006-01-20 19:10:55 +00:00
|
|
|
}else{
|
|
|
|
while(x != 1){
|
2006-01-22 05:57:46 +00:00
|
|
|
has_keyframe[n++][i]=x&1;
|
2006-01-20 19:10:55 +00:00
|
|
|
x>>=1;
|
|
|
|
}
|
|
|
|
}
|
2006-01-22 05:57:46 +00:00
|
|
|
for(; j<n && j<syncpoints; j++){
|
|
|
|
if (!has_keyframe[j][i]) continue
|
|
|
|
A v
|
2006-02-04 08:52:35 +00:00
|
|
|
if(!A){
|
|
|
|
A v
|
|
|
|
B v
|
|
|
|
eor_pts[j][i] = last_pts + A + B
|
|
|
|
}else
|
|
|
|
B=0
|
|
|
|
keyframe_pts[j][i] = last_pts + A
|
|
|
|
last_pts += A + B
|
2006-01-22 05:57:46 +00:00
|
|
|
}
|
2006-01-20 19:10:55 +00:00
|
|
|
}
|
2005-10-06 11:08:43 +00:00
|
|
|
}
|
2006-03-15 16:28:31 +00:00
|
|
|
reserved_bytes
|
2006-03-04 16:30:25 +00:00
|
|
|
index_ptr u(64)
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-03-01 14:19:37 +00:00
|
|
|
info_packet:
|
2006-02-24 05:41:35 +00:00
|
|
|
stream_id_plus1 v
|
2006-11-04 22:01:51 +00:00
|
|
|
chapter_id s (Note due to a typo this was v
|
|
|
|
until 2006-11-04)
|
2006-03-10 14:10:07 +00:00
|
|
|
chapter_start t
|
2006-03-01 13:35:09 +00:00
|
|
|
chapter_len v
|
2006-02-24 05:41:35 +00:00
|
|
|
count v
|
|
|
|
for(i=0; i<count; i++){
|
|
|
|
name vb
|
|
|
|
value s
|
|
|
|
if (value==-1){
|
|
|
|
type= "UTF-8"
|
|
|
|
value vb
|
|
|
|
}else if (value==-2){
|
2005-10-06 11:08:43 +00:00
|
|
|
type vb
|
|
|
|
value vb
|
2006-02-24 05:41:35 +00:00
|
|
|
}else if (value==-3){
|
2006-02-25 18:51:46 +00:00
|
|
|
type= "s"
|
2006-02-24 05:41:35 +00:00
|
|
|
value s
|
2006-03-10 14:10:07 +00:00
|
|
|
}else if (value==-4){
|
|
|
|
type= "t"
|
|
|
|
value t
|
|
|
|
}else if (value<-4){
|
2006-02-25 18:51:46 +00:00
|
|
|
type= "r"
|
2006-03-10 14:10:07 +00:00
|
|
|
value.den= -value-4
|
2006-02-24 05:41:35 +00:00
|
|
|
value.num s
|
|
|
|
}else{
|
2006-02-25 18:51:46 +00:00
|
|
|
type= "v"
|
2006-02-24 05:41:35 +00:00
|
|
|
}
|
2005-10-06 11:08:43 +00:00
|
|
|
}
|
2005-09-17 19:27:39 +00:00
|
|
|
|
2006-01-06 02:05:34 +00:00
|
|
|
syncpoint:
|
2006-03-10 14:10:07 +00:00
|
|
|
global_key_pts t
|
2006-03-10 14:34:30 +00:00
|
|
|
back_ptr_div16 v
|
2004-05-04 01:29:17 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
Complete definition:
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
Tag description:
|
|
|
|
----------------
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2004-04-20 23:00:28 +00:00
|
|
|
file_id_string
|
2005-10-06 11:08:43 +00:00
|
|
|
"nut/multimedia container\0"
|
2006-11-10 17:47:01 +00:00
|
|
|
the very first thing in every nut file, usefull for identifying nut
|
|
|
|
files
|
2003-02-07 21:35:39 +00:00
|
|
|
|
|
|
|
*_startcode
|
2006-10-28 10:06:11 +00:00
|
|
|
all startcodes start with 'N'
|
2004-04-09 18:40:48 +00:00
|
|
|
|
|
|
|
main_startcode
|
2005-10-06 11:08:43 +00:00
|
|
|
0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48)
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2004-04-09 18:40:48 +00:00
|
|
|
stream_starcode
|
2005-10-06 11:08:43 +00:00
|
|
|
0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48)
|
2005-03-01 00:16:44 +00:00
|
|
|
|
2006-01-06 02:05:34 +00:00
|
|
|
syncpoint_startcode
|
2005-10-06 11:08:43 +00:00
|
|
|
0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)
|
|
|
|
|
2004-04-09 18:40:48 +00:00
|
|
|
index_startcode
|
2005-10-06 11:08:43 +00:00
|
|
|
0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48)
|
|
|
|
|
2004-04-09 18:40:48 +00:00
|
|
|
info_startcode
|
2005-10-06 11:08:43 +00:00
|
|
|
0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48)
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
version
|
2006-07-13 10:26:33 +00:00
|
|
|
NUT version. The current value is 3. All lower values are pre-freeze
|
2004-04-20 17:58:24 +00:00
|
|
|
|
2006-11-10 17:47:01 +00:00
|
|
|
stream_count
|
|
|
|
number of streams in this file
|
|
|
|
|
2006-11-10 17:51:44 +00:00
|
|
|
time_base_count
|
|
|
|
number of different time bases in this file
|
|
|
|
this MUST NOT be 0
|
|
|
|
|
2006-01-20 19:12:22 +00:00
|
|
|
forward_ptr
|
|
|
|
size of the packet data (exactly the distance from the first byte
|
2006-03-11 10:19:02 +00:00
|
|
|
after the packet_header to the first byte of the next packet)
|
2006-11-10 17:47:01 +00:00
|
|
|
every nut packet contains a forward_ptr immedeatly 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
|
2006-01-20 19:12:22 +00:00
|
|
|
|
2004-04-28 03:19:35 +00:00
|
|
|
max_distance
|
2006-03-25 13:39:47 +00:00
|
|
|
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
|
|
|
|
bounds on seek operations and allows for the detection of damaged
|
|
|
|
frame headers, should a chain of frame headers pass max_distance
|
|
|
|
without encountering any startcode.
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2006-01-20 19:12:22 +00:00
|
|
|
syncpoints SHOULD be placed immediately before a keyframe if the
|
|
|
|
previous frame of the same stream was a non-keyframe, unless such
|
|
|
|
non-keyframe - keyframe transitions are very frequent
|
|
|
|
|
2006-03-03 22:43:49 +00:00
|
|
|
SHOULD be set to <=32768
|
2006-03-12 13:08:10 +00:00
|
|
|
if the stored value is >65536 then max_distance MUST be set to 65536
|
2004-05-25 20:42:22 +00:00
|
|
|
|
2006-03-12 13:08:10 +00:00
|
|
|
This is also half the max frame size without a checksum after the
|
|
|
|
frameheader.
|
2006-03-10 14:28:11 +00:00
|
|
|
|
|
|
|
|
2006-02-10 10:42:40 +00:00
|
|
|
max_pts_distance
|
|
|
|
max absoloute difference of pts of new frame from last_pts in the
|
2006-03-25 13:39:47 +00:00
|
|
|
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.
|
2006-03-01 14:19:37 +00:00
|
|
|
Note that last_pts is not necessarily the pts of the last frame
|
2006-02-10 10:42:40 +00:00
|
|
|
on the same stream, as it is altered by syncpoint timestamps.
|
2006-03-10 14:44:31 +00:00
|
|
|
SHOULD NOT be higher than 1/timebase
|
2006-02-10 10:42:40 +00:00
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
stream_id
|
2005-10-06 11:08:43 +00:00
|
|
|
Stream identifier
|
|
|
|
stream_id MUST be < stream_count
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
stream_class
|
2005-10-06 11:08:43 +00:00
|
|
|
0 video
|
|
|
|
1 audio
|
|
|
|
2 subtiles
|
2006-03-10 11:52:58 +00:00
|
|
|
3 userdata
|
2005-10-06 11:08:43 +00:00
|
|
|
Note: the remaining values are reserved and MUST NOT be used
|
|
|
|
a demuxer MUST ignore streams with reserved classes
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
fourcc
|
2005-10-06 11:08:43 +00:00
|
|
|
identification for the codec
|
|
|
|
example: "H264"
|
|
|
|
MUST contain 2 or 4 bytes, note, this might be increased in the future
|
|
|
|
if needed
|
2006-07-04 21:14:55 +00:00
|
|
|
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
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2003-02-06 18:03:11 +00:00
|
|
|
time_base_nom / time_base_denom = time_base
|
2005-10-06 11:08:43 +00:00
|
|
|
the length of a timer tick in seconds, this MUST be equal to the 1/fps
|
2006-03-25 07:58:07 +00:00
|
|
|
if FLAG_FIXED_FPS is set
|
2005-10-06 11:08:43 +00:00
|
|
|
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
|
|
|
|
examples:
|
|
|
|
fps time_base_nom time_base_denom
|
|
|
|
30 1 30
|
|
|
|
29.97 1001 30000
|
|
|
|
23.976 1001 24000
|
2006-03-17 13:26:40 +00:00
|
|
|
There MUST NOT be 2 identical timebases in a file.
|
|
|
|
There SHOULD NOT be more timebases than streams.
|
2003-03-13 15:32:48 +00:00
|
|
|
|
2006-03-15 16:24:24 +00:00
|
|
|
time_base_id
|
2006-11-10 18:45:10 +00:00
|
|
|
index into the time_base table
|
2006-11-11 02:04:02 +00:00
|
|
|
MUST be < time_base_count
|
2006-03-15 16:24:24 +00:00
|
|
|
|
2006-01-06 02:06:22 +00:00
|
|
|
convert_ts
|
|
|
|
To switch from 2 different timebases, the following calculation is
|
|
|
|
defined:
|
|
|
|
|
|
|
|
ln = from_time_base_nom*to_time_base_denom
|
|
|
|
sn = from_timestamp
|
|
|
|
d1 = from_time_base_denom
|
|
|
|
d2 = to_time_base_nom
|
|
|
|
timestamp = (ln/d1*sn + ln%d1*sn/d1)/d2
|
2005-10-06 11:08:43 +00:00
|
|
|
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
|
2004-05-04 01:29:17 +00:00
|
|
|
|
2006-02-04 08:53:43 +00:00
|
|
|
compare_ts
|
|
|
|
Compares timestamps from 2 different timebases,
|
|
|
|
if a is before b then compare_ts(a, b) = -1
|
|
|
|
if a is after b then compare_ts(a, b) = 1
|
|
|
|
else compare_ts(a, b) = 0
|
|
|
|
|
|
|
|
Care must be taken that this is done exactly with no rounding errors,
|
|
|
|
simply casting to float or double and doing the obvious
|
|
|
|
a*timebase > b*timebase is not compliant or correct, neither is the
|
|
|
|
same with integers, and
|
|
|
|
a*a_timebase.num*b_timebase.den > b*b_timebase.num*a_timebase.den
|
|
|
|
will overflow. One possible implementation which shouldn't overflow
|
|
|
|
within the range of legal timestamps and timebases 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;
|
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
msb_pts_shift
|
2005-10-06 11:08:43 +00:00
|
|
|
amount of bits in lsb_pts
|
|
|
|
MUST be <16
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2004-04-28 03:19:35 +00:00
|
|
|
decode_delay
|
2006-11-13 15:23:45 +00:00
|
|
|
size of the reordering buffer used to convert pts to dts
|
|
|
|
codecs which dont support b frames normaly 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 arent aware of any which doesnt
|
|
|
|
but its theoretically possible that one exists which needs it >0)
|
2006-02-17 19:45:35 +00:00
|
|
|
decode_delay MUST NOT be set higher than necessary for a codec.
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2006-03-25 07:58:07 +00:00
|
|
|
stream_flags
|
|
|
|
Bit Name Description
|
|
|
|
1 FLAG_FIXED_FPS indicates that the fps is fixed
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2003-02-09 00:11:18 +00:00
|
|
|
codec_specific_data
|
2005-10-06 11:08:43 +00:00
|
|
|
private global data for a codec (could be huffman tables or ...)
|
2006-07-15 21:49:47 +00:00
|
|
|
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
|
2006-07-16 23:47:12 +00:00
|
|
|
for H.264 the NAL units MUST be formated as in a bytestream
|
|
|
|
(with 00 00 01 prefixes)
|
2004-03-30 01:05:51 +00:00
|
|
|
|
|
|
|
frame_code
|
2006-11-08 18:40:08 +00:00
|
|
|
frame_code is a 8bit field which exists before every frame, it can
|
|
|
|
store part of the size of the frame, the stream number, the timestamp
|
|
|
|
and some flags amongth other things, what is not directly stored
|
|
|
|
in it but is needed is stored in various fields immedeatly after it
|
|
|
|
the values stored in it can be found in the main header
|
2005-10-06 11:08:43 +00:00
|
|
|
the value 78 ('N') is forbidden to ensure that the byte is always
|
|
|
|
different from the first byte of any startcode
|
2006-03-10 13:50:35 +00:00
|
|
|
a muxer SHOULD mark 0x00 and 0xFF as invalid to improve error
|
|
|
|
detection
|
2004-03-30 01:05:51 +00:00
|
|
|
|
2006-03-03 22:30:17 +00:00
|
|
|
flags[frame_code], frame_flags
|
2006-03-25 07:58:34 +00:00
|
|
|
Bit Name Description
|
2006-03-11 15:26:39 +00:00
|
|
|
1 FLAG_KEY if set, frame is keyframe
|
|
|
|
2 FLAG_EOR if set, stream has no relevance on
|
2006-03-12 13:21:04 +00:00
|
|
|
presentation. (EOR)
|
2006-03-18 12:13:48 +00:00
|
|
|
8 FLAG_CODED_PTS if set, coded_pts is in the frame header
|
|
|
|
16 FLAG_STREAM_ID if set, stream_id is coded in the frame header
|
2006-03-11 15:26:39 +00:00
|
|
|
32 FLAG_SIZE_MSB if set, data_size_msb is at frame header,
|
|
|
|
otherwise data_size_msb is 0
|
|
|
|
64 FLAG_CHECKSUM if set then the frame header contains a checksum
|
2006-03-18 12:13:48 +00:00
|
|
|
128 FLAG_RESERVED if set, reserved_count is coded in the frame header
|
2006-03-11 15:26:39 +00:00
|
|
|
4096 FLAG_CODED if set, coded_flags are stored in the frame header.
|
|
|
|
8192 FLAG_INVALID if set, frame_code is invalid.
|
2006-01-20 19:06:28 +00:00
|
|
|
|
|
|
|
EOR frames MUST be zero-length and must be set keyframe.
|
|
|
|
All streams SHOULD end with EOR, where the pts of the EOR indicates the
|
|
|
|
end presentation time of the final frame.
|
|
|
|
An EOR set stream is unset by the first content frames.
|
2006-02-07 16:52:05 +00:00
|
|
|
EOR can only be unset in streams with zero decode_delay .
|
2006-03-25 13:39:47 +00:00
|
|
|
FLAG_CHECKSUM MUST be set if the frame's data_size is strictly greater than
|
|
|
|
2*max_distance or the difference abs(pts-last_pts) is strictly greater than
|
|
|
|
max_pts_distance (where pts represents this frame's pts and last_pts is
|
|
|
|
defined as below).
|
2004-04-03 13:23:44 +00:00
|
|
|
|
2006-10-28 00:11:53 +00:00
|
|
|
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
|
|
|
|
|
2006-03-18 12:13:48 +00:00
|
|
|
stream_id[frame_code]
|
2006-11-08 18:50:58 +00:00
|
|
|
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
|
2006-03-12 17:35:51 +00:00
|
|
|
MUST be <250
|
2004-03-30 01:05:51 +00:00
|
|
|
|
|
|
|
data_size_mul[frame_code]
|
2006-11-08 18:50:58 +00:00
|
|
|
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
|
2006-03-12 17:35:51 +00:00
|
|
|
MUST be <16384
|
2004-03-30 01:05:51 +00:00
|
|
|
|
|
|
|
data_size_lsb[frame_code]
|
2006-11-08 18:50:58 +00:00
|
|
|
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
|
2006-03-12 17:35:51 +00:00
|
|
|
MUST be <16384
|
2004-03-30 01:05:51 +00:00
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
pts_delta[frame_code]
|
2006-03-12 17:35:51 +00:00
|
|
|
MUST be <16384 and >-16384
|
2006-10-28 00:11:53 +00:00
|
|
|
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
|
2004-05-04 01:29:17 +00:00
|
|
|
|
2006-02-17 20:05:25 +00:00
|
|
|
reserved_count[frame_code]
|
2006-03-12 13:30:45 +00:00
|
|
|
MUST be <256
|
2006-02-17 20:05:25 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
data_size
|
2006-11-08 18:50:58 +00:00
|
|
|
the size of the following frame
|
2005-10-06 11:08:43 +00:00
|
|
|
data_size= data_size_lsb + data_size_msb*data_size_mul;
|
2004-04-23 15:48:17 +00:00
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
coded_pts
|
2005-10-06 11:08:43 +00:00
|
|
|
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
|
|
|
|
pts = ((pts_lsb-delta)&mask) + delta
|
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
lsb_pts
|
2005-10-06 11:08:43 +00:00
|
|
|
least significant bits of the pts in time_base precision
|
2003-02-06 15:33:02 +00:00
|
|
|
Example: IBBP display order
|
2005-10-06 11:08:43 +00:00
|
|
|
keyframe pts=0 -> pts=0
|
|
|
|
frame lsb_pts=3 -> pts=3
|
|
|
|
frame lsb_pts=1 -> pts=1
|
|
|
|
frame lsb_pts=2 -> pts=2
|
|
|
|
...
|
|
|
|
keyframe msb_pts=257 -> pts=257
|
|
|
|
frame lsb_pts=255 -> pts=255
|
|
|
|
frame lsb_pts=0 -> pts=256
|
|
|
|
frame lsb_pts=4 -> pts=260
|
|
|
|
frame lsb_pts=2 -> pts=258
|
|
|
|
frame lsb_pts=3 -> pts=259
|
|
|
|
all pts's of keyframes of a single stream MUST be monotone
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2004-04-28 03:19:35 +00:00
|
|
|
dts
|
2006-11-08 19:04:48 +00:00
|
|
|
decoding timestamp
|
|
|
|
the dts of a frame is the timestamp of the first sample which is
|
|
|
|
output by a decoder when it is feeded with the frame, note that the
|
|
|
|
data output is not neccesarily what is coded in the frame, but may
|
|
|
|
be data from previous frames
|
2005-10-06 11:08:43 +00:00
|
|
|
dts is 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
|
2006-01-06 02:05:57 +00:00
|
|
|
|
|
|
|
Pts of all frames in all streams MUST be bigger or equal to dts of all
|
2006-01-20 19:06:28 +00:00
|
|
|
previous frames in all streams, compared in common timebase. (EOR
|
|
|
|
frames are NOT exempt from this rule)
|
2006-11-12 12:24:57 +00:00
|
|
|
Dts of all frames MUST be bigger or equal to dts of all previous frames
|
|
|
|
in the same stream
|
2004-04-28 03:19:35 +00:00
|
|
|
|
2003-02-06 15:33:02 +00:00
|
|
|
width/height
|
2006-11-08 19:04:48 +00:00
|
|
|
width and height of the video in pixels
|
2006-03-05 07:06:34 +00:00
|
|
|
MUST be set to the coded width/height, MUST NOT be 0
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
sample_width/sample_height (aspect ratio)
|
2005-10-06 11:08:43 +00:00
|
|
|
sample_width is the horizontal distance between samples
|
|
|
|
sample_width and sample_height MUST be relatively prime if not zero
|
2006-03-10 13:54:39 +00:00
|
|
|
both MUST be 0 if unknown otherwise both MUST be non zero
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2003-05-23 12:17:36 +00:00
|
|
|
colorspace_type
|
2005-10-06 11:08:43 +00:00
|
|
|
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
|
2003-05-23 14:38:59 +00:00
|
|
|
|
2004-04-28 03:19:35 +00:00
|
|
|
samplerate_nom / samplerate_denom = samplerate
|
2006-03-05 07:06:34 +00:00
|
|
|
the number of samples per second, MUST NOT be 0
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-02-25 16:16:47 +00:00
|
|
|
crc32 checksum
|
2006-03-01 13:37:09 +00:00
|
|
|
Generator polynomial is 0x104C11DB7. Starting value is zero.
|
2006-02-25 16:16:47 +00:00
|
|
|
|
2003-02-06 15:33:02 +00:00
|
|
|
checksum
|
2006-02-10 10:42:40 +00:00
|
|
|
crc32 checksum
|
2005-10-06 11:08:43 +00:00
|
|
|
checksum is calculated for the area pointed to by forward_ptr not
|
|
|
|
including the checksum itself (from first byte after the
|
2006-03-11 10:19:02 +00:00
|
|
|
packet_header until last byte before the checksum).
|
2006-03-01 14:19:37 +00:00
|
|
|
for frame headers the checksum contains the framecode byte and all
|
|
|
|
following bytes upto the checksum itself
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-03-10 02:49:29 +00:00
|
|
|
header_checksum
|
|
|
|
checksum over the startcode and forward pointer
|
|
|
|
|
2006-02-17 20:05:25 +00:00
|
|
|
Syncpoint tags:
|
|
|
|
---------------
|
|
|
|
|
2006-03-10 14:34:30 +00:00
|
|
|
back_ptr_div16
|
|
|
|
back_ptr = back_ptr_div16 * 16 + 15
|
|
|
|
back_ptr must point to a position within 16 bytes of a syncpoint
|
2006-01-20 19:12:22 +00:00
|
|
|
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:
|
2006-03-15 16:24:24 +00:00
|
|
|
last_pts[i] = convert_ts(global_key_pts, time_base[id], time_base[i])
|
2006-01-20 19:12:22 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2006-02-17 20:05:25 +00:00
|
|
|
Index tags:
|
|
|
|
-----------
|
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
max_pts
|
2006-03-10 14:10:07 +00:00
|
|
|
The highest pts in the entire file
|
2006-01-20 19:10:55 +00:00
|
|
|
|
2006-03-10 14:34:30 +00:00
|
|
|
syncpoint_pos_div16
|
|
|
|
offset from begginning of file to up to 15 bytes before the syncpoint
|
2006-01-20 19:10:55 +00:00
|
|
|
referred to in this index entry. Relative to position of last
|
|
|
|
syncpoint.
|
2005-09-09 10:26:21 +00:00
|
|
|
|
2006-01-20 19:10:55 +00:00
|
|
|
has_keyframe
|
|
|
|
indicates whether this stream has a keyframe between this syncpoint and
|
|
|
|
the last syncpoint.
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-01-20 19:10:55 +00:00
|
|
|
keyframe_pts
|
|
|
|
The pts of the first keyframe for this stream in the region between the
|
2006-02-04 08:52:35 +00:00
|
|
|
2 syncpoints, in the stream's timebase. (EOR frames are also keyframes)
|
|
|
|
|
|
|
|
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.
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
index_ptr
|
2006-03-04 16:30:25 +00:00
|
|
|
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.
|
|
|
|
|
2005-09-09 10:26:21 +00:00
|
|
|
|
2006-02-17 20:05:25 +00:00
|
|
|
Info tags:
|
|
|
|
----------
|
|
|
|
|
2006-02-24 05:41:35 +00:00
|
|
|
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.
|
2006-03-01 14:19:37 +00:00
|
|
|
chapter_id n MUST not be used unless there are at least n chapters in the
|
|
|
|
file
|
2006-02-24 05:41:35 +00:00
|
|
|
|
|
|
|
chapter_start
|
2006-03-10 14:10:07 +00:00
|
|
|
timestamp of start of chapter
|
2006-02-24 05:41:35 +00:00
|
|
|
|
|
|
|
chapter_len
|
|
|
|
Length of chapter in same timebase of chapter_start.
|
2005-10-06 11:08:43 +00:00
|
|
|
|
2003-02-07 21:35:39 +00:00
|
|
|
type
|
2005-10-06 11:08:43 +00:00
|
|
|
for example: "UTF8" -> string or "JPEG" -> JPEG image
|
2006-02-25 18:51:46 +00:00
|
|
|
"v" -> unsigned integer
|
|
|
|
"s" -> signed integer
|
|
|
|
"r" -> rational
|
2005-10-06 11:08:43 +00:00
|
|
|
Note: nonstandard fields should be prefixed by "X-"
|
|
|
|
Note: MUST be less than 6 byte long (might be increased to 64 later)
|
2003-02-07 21:35:39 +00:00
|
|
|
|
2004-09-11 09:18:07 +00:00
|
|
|
info packet types
|
2005-10-06 11:08:43 +00:00
|
|
|
the name of the info entry, valid names are
|
|
|
|
"Author"
|
|
|
|
"Description"
|
|
|
|
"Copyright"
|
|
|
|
"Encoder"
|
|
|
|
the name & version of the software used for encoding
|
|
|
|
"Title"
|
2006-02-24 05:41:35 +00:00
|
|
|
"Cover" (allowed types are "PNG" and "JPEG")
|
2005-10-06 11:08:43 +00:00
|
|
|
image of the (CD, DVD, VHS, ..) cover (preferably PNG or JPEG)
|
|
|
|
"Source"
|
|
|
|
"DVD", "VCD", "CD", "MD", "FM radio", "VHS", "TV", "LD"
|
|
|
|
Optional: appended PAL, NTSC, SECAM, ... in parentheses
|
2006-07-04 21:14:55 +00:00
|
|
|
"SourceContainer"
|
|
|
|
"nut", "mkv", "mov", "avi", "ogg", "rm", "mpeg-ps", "mpeg-ts", "raw"
|
|
|
|
"SourceCodecTag"
|
|
|
|
the source codec id like a fourcc which was used to store a specific
|
|
|
|
stream in its SourceContainer
|
2005-10-06 11:08:43 +00:00
|
|
|
"CaptureDevice"
|
|
|
|
"BT878", "BT848", "webcam", ... (more exact names are fine too)
|
|
|
|
"CreationTime"
|
|
|
|
"2003-01-20 20:13:15Z", ...
|
|
|
|
(ISO 8601 format, see http://www.cl.cam.ac.uk/~mgk25/iso-time.html)
|
|
|
|
Note: do not forget the timezone
|
|
|
|
"Keywords"
|
|
|
|
"Language"
|
|
|
|
ISO 639 and ISO 3166 for language/country code
|
|
|
|
something like "eng" (US english), can be 0 if unknown
|
|
|
|
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 add them to the official standard (if they are sane)
|
|
|
|
Note: nonstandard fields should be prefixed by "X-"
|
2006-02-25 20:06:21 +00:00
|
|
|
Note: names of fields SHOULD be in English if a word with the same
|
2006-02-20 04:49:06 +00:00
|
|
|
meaning exists in English
|
2005-10-06 11:08:43 +00:00
|
|
|
Note: MUST be less than 64 bytes long
|
2003-02-06 17:19:09 +00:00
|
|
|
|
|
|
|
value
|
2005-10-06 11:08:43 +00:00
|
|
|
value of this name/type pair
|
|
|
|
|
2003-02-07 09:48:06 +00:00
|
|
|
stuffing
|
2005-10-06 11:08:43 +00:00
|
|
|
0x80 can be placed in front of any type v entry for stuffing purposes
|
2006-03-10 14:18:59 +00:00
|
|
|
except the forward_ptr and all fields in the frame header where a
|
|
|
|
maximum of 8 stuffing bytes per field are allowed
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
Structure:
|
|
|
|
----------
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
the headers MUST be in exactly the following order (to simplify demuxer design)
|
|
|
|
main header
|
|
|
|
stream_header (id=0)
|
|
|
|
stream_header (id=1)
|
|
|
|
...
|
|
|
|
stream_header (id=n)
|
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
headers may be repeated, but if they are, then they MUST all be repeated
|
2005-03-25 12:37:18 +00:00
|
|
|
together and repeated headers MUST be identical
|
2006-02-07 04:03:11 +00:00
|
|
|
|
|
|
|
Each set of repeated headers not at the beginning or end of the file SHOULD
|
|
|
|
be stored at the earliest possible position after 2^x where x is
|
2005-03-25 12:37:18 +00:00
|
|
|
an integer and the file end, so the headers may be repeated at 4102 if that is
|
|
|
|
the closest position after 2^12=4096 at which the headers can be placed
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2006-02-07 04:03:11 +00:00
|
|
|
Note: this allows an implementation reading the file to locate backup
|
|
|
|
headers in O(log filesize) time as opposed to O(filesize)
|
|
|
|
|
2005-03-25 12:37:18 +00:00
|
|
|
headers MUST be placed at least at the start of the file and immediately before
|
2004-05-25 20:42:22 +00:00
|
|
|
the index or at the file end if there is no index
|
2005-09-09 09:25:07 +00:00
|
|
|
headers MUST be repeated at least twice (so they exist three times in a file)
|
2003-02-07 09:48:06 +00:00
|
|
|
|
2005-10-06 11:07:12 +00:00
|
|
|
there MUST be a sync point immediately before the first frame after any headers
|
2004-05-25 21:46:20 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
Index:
|
|
|
|
------
|
|
|
|
|
2005-03-25 12:37:18 +00:00
|
|
|
Note: with realtime streaming, there is no end, so no index there either
|
2006-02-04 08:54:31 +00:00
|
|
|
Index MAY only be repeated after main headers.
|
2006-03-04 16:30:25 +00:00
|
|
|
If an index is written anywhere in the file, it MUST be written at end of
|
|
|
|
file as well.
|
2003-02-07 09:48:06 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
2006-02-24 05:41:35 +00:00
|
|
|
Info:
|
|
|
|
-----
|
|
|
|
|
2006-11-15 00:12:39 +00:00
|
|
|
If a info packet is stored anywhere then a muxer MUST also store an identical
|
2006-03-08 12:37:10 +00:00
|
|
|
info packet after every main-stream-header set
|
2006-02-24 05:41:35 +00:00
|
|
|
|
2006-03-08 12:37:10 +00:00
|
|
|
If a demuxer has seen several info packets with the same chapter_id and
|
|
|
|
stream_id then it MUST ignore all but the one with the highest position in
|
|
|
|
the file
|
2006-03-01 14:19:37 +00:00
|
|
|
|
2006-11-04 13:56:55 +00:00
|
|
|
demxuxers SHOULD NOT search the whole file for info packets
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
demuxer (non-normative):
|
|
|
|
------------------------
|
2004-05-25 20:42:22 +00:00
|
|
|
|
2005-09-09 09:25:07 +00:00
|
|
|
in the absence of a valid header at the beginning, players SHOULD search for
|
|
|
|
backup headers starting at offset 2^x; for each x players SHOULD end their
|
|
|
|
search at a particular offset when any startcode is found (including syncpoint)
|
2004-05-25 20:42:22 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
Semantic requirements:
|
|
|
|
======================
|
2005-09-09 10:26:21 +00:00
|
|
|
|
2005-11-18 16:28:26 +00:00
|
|
|
If more than one stream of a given stream class is present, each one SHOULD
|
2005-09-09 10:26:21 +00:00
|
|
|
have info tags specifying disposition, and if applicable, language.
|
2005-11-18 16:28:26 +00:00
|
|
|
It often highly improves usability and is therefore strongly encouraged.
|
2005-09-09 10:26:21 +00:00
|
|
|
|
|
|
|
A demuxer MUST NOT 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.
|
2006-03-10 14:23:22 +00:00
|
|
|
for example vorbis in ogg in nut is invalid, as is
|
|
|
|
mpegvideo+mpegaudio in mpeg-ps/ts in nut or dvvideo + dvaudio in dv in nut
|
2005-09-09 10:26:21 +00:00
|
|
|
|
2004-05-25 20:42:22 +00:00
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
Sample code (Public Domain, & untested):
|
|
|
|
========================================
|
2003-02-06 15:33:02 +00:00
|
|
|
|
|
|
|
typedef BufferContext{
|
2005-10-06 11:08:43 +00:00
|
|
|
uint8_t *buf;
|
|
|
|
uint8_t *buf_ptr;
|
2003-02-06 15:33:02 +00:00
|
|
|
}BufferContext;
|
|
|
|
|
|
|
|
static inline uint64_t get_bytes(BufferContext *bc, int count){
|
2005-10-06 11:08:43 +00:00
|
|
|
uint64_t val=0;
|
|
|
|
|
|
|
|
assert(count>0 && count<9);
|
|
|
|
|
|
|
|
for(i=0; i<count; i++){
|
|
|
|
val <<=8;
|
|
|
|
val += *(bc->buf_ptr++);
|
|
|
|
}
|
|
|
|
|
|
|
|
return val;
|
2003-02-06 15:33:02 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
static inline void put_bytes(BufferContext *bc, int count, uint64_t val){
|
2005-10-06 11:08:43 +00:00
|
|
|
uint64_t val=0;
|
|
|
|
|
|
|
|
assert(count>0 && count<9);
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
for(i=count-1; i>=0; i--){
|
|
|
|
*(bc->buf_ptr++)= val >> (8*i);
|
|
|
|
}
|
2003-02-06 15:33:02 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
return val;
|
2003-02-06 15:33:02 +00:00
|
|
|
}
|
|
|
|
|
2003-05-04 18:57:39 +00:00
|
|
|
static inline uint64_t get_v(BufferContext *bc){
|
2005-10-06 11:08:43 +00:00
|
|
|
uint64_t val= 0;
|
|
|
|
|
|
|
|
for(; space_left(bc) > 0; ){
|
|
|
|
int tmp= *(bc->buf_ptr++);
|
|
|
|
if(tmp&0x80)
|
|
|
|
val= (val<<7) + tmp - 0x80;
|
|
|
|
else
|
|
|
|
return (val<<7) + tmp;
|
|
|
|
}
|
|
|
|
|
|
|
|
return -1;
|
2003-02-06 15:33:02 +00:00
|
|
|
}
|
|
|
|
|
2003-05-04 18:57:39 +00:00
|
|
|
static inline int put_v(BufferContext *bc, uint64_t val){
|
2005-10-06 11:08:43 +00:00
|
|
|
int i;
|
|
|
|
|
|
|
|
if(space_left(bc) < 9) return -1;
|
|
|
|
|
|
|
|
val &= 0x7FFFFFFFFFFFFFFFULL; // FIXME can only encode upto 63 bits currently
|
|
|
|
for(i=7; ; i+=7){
|
|
|
|
if(val>>i == 0) break;
|
|
|
|
}
|
|
|
|
|
|
|
|
for(i-=7; i>0; i-=7){
|
|
|
|
*(bc->buf_ptr++)= 0x80 | (val>>i);
|
|
|
|
}
|
|
|
|
*(bc->buf_ptr++)= val&0x7F;
|
|
|
|
|
|
|
|
return 0;
|
2003-03-13 15:32:48 +00:00
|
|
|
}
|
|
|
|
|
2004-04-28 03:19:35 +00:00
|
|
|
static int64_t get_dts(int64_t pts, int64_t *pts_cache, int delay, int reset){
|
2005-10-06 11:08:43 +00:00
|
|
|
if(reset) memset(pts_cache, -1, delay*sizeof(int64_t));
|
2004-04-28 03:19:35 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
while(delay--){
|
|
|
|
int64_t t= pts_cache[delay];
|
|
|
|
if(t < pts){
|
|
|
|
pts_cache[delay]= pts;
|
|
|
|
pts= t;
|
|
|
|
}
|
|
|
|
}
|
2004-04-28 03:19:35 +00:00
|
|
|
|
2005-10-06 11:08:43 +00:00
|
|
|
return pts;
|
2004-04-28 03:19:35 +00:00
|
|
|
}
|
|
|
|
|
2005-10-23 16:49:56 +00:00
|
|
|
|
|
|
|
|
|
|
|
Authors:
|
|
|
|
========
|
2003-05-23 12:17:36 +00:00
|
|
|
|
2005-09-09 09:25:07 +00:00
|
|
|
Folks from the MPlayer developers mailing list (http://www.mplayerhq.hu/).
|
|
|
|
Authors in alphabetical order: (FIXME! Tell us if we left you out)
|
2005-10-23 16:50:27 +00:00
|
|
|
Beregszaszi, Alex (alex@fsn.hu)
|
|
|
|
Bunkus, Moritz (moritz@bunkus.org)
|
|
|
|
Diedrich, Tobias (ranma+mplayer@tdiedrich.de)
|
|
|
|
Felker, Rich (dalias@aerifal.cx)
|
|
|
|
Franz, Fabian (FabianFranz@gmx.de)
|
|
|
|
Gereoffy, Arpad (arpi@thot.banki.hu)
|
|
|
|
Hess, Andreas (jaska@gmx.net)
|
|
|
|
Niedermayer, Michael (michaelni@gmx.at)
|
|
|
|
Shimon, Oded (ods15@ods15.dyndns.org)
|