mirror of https://github.com/mpv-player/mpv
599 lines
16 KiB
Plaintext
599 lines
16 KiB
Plaintext
NUT Open Container Format DRAFT 20040409
|
||
----------------------------------------
|
||
|
||
|
||
|
||
Intro:
|
||
|
||
Features / goals:
|
||
(supported by the format, not necessary by a specific implementation)
|
||
|
||
Simple
|
||
use the same encoding for nearly all fields
|
||
simple decoding, so slow cpus (and embedded systems) can handle it
|
||
Extendible
|
||
no limit for the possible values for all fields (using universal vlc)
|
||
allow adding of new headers in the future
|
||
allow adding more fields at the end of headers
|
||
Compact
|
||
~0.2% overhead, for normal bitrates
|
||
index is <10kb per hour (1 keyframe every 3sec)
|
||
a usual header for a file is about 100bytes (audio + video headers together)
|
||
a packet header is about ~1-8 bytes
|
||
Error resistant
|
||
seeking / playback without an index
|
||
headers & index can be repeated
|
||
damaged files can be played back with minimal data lost and fast
|
||
resyncing times
|
||
|
||
|
||
|
||
Definitions:
|
||
|
||
MUST the specific part must be done to conform to this standard
|
||
SHOULD its recommanded to be done that way but its not strictly required
|
||
|
||
|
||
|
||
Syntax:
|
||
|
||
Type definitions:
|
||
v
|
||
value=0
|
||
do{
|
||
more_data u(1)
|
||
data u(7)
|
||
value= 128*value + data
|
||
}while(more_data)
|
||
|
||
s
|
||
temp v
|
||
temp++
|
||
if(temp&1) value= -(temp>>1)
|
||
else value= (temp>>1)
|
||
|
||
b (binary data or string)
|
||
for(i=0; i<length; i++){
|
||
data[i] u(8)
|
||
}
|
||
Note: strings MUST be encoded in utf8
|
||
|
||
vb
|
||
length v
|
||
value b
|
||
|
||
f(x) n fixed bits in big endian order
|
||
u(x) unsigned number encoded in x bits in MSB first order
|
||
|
||
|
||
Bitstream syntax:
|
||
packet header
|
||
forward ptr v
|
||
backward ptr v
|
||
|
||
align_byte
|
||
while(not byte aligned)
|
||
one f(1)
|
||
|
||
reserved_bytes
|
||
for(i=0; i<forward_ptr - length_of_non_reserved; i++)
|
||
reserved u(8)
|
||
a decoder MUST ignore any reserved bytes
|
||
a encoder 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
|
||
|
||
main header:
|
||
main_startcode f(64)
|
||
packet header
|
||
version v
|
||
stream_count v
|
||
for(i=0; i<256; ){
|
||
tmp_flag v
|
||
tmp_stream v
|
||
tmp_mul v
|
||
tmp_size v
|
||
count v
|
||
for(j=0; j<count; j++, i++){
|
||
flags[i]= tmp_flag;
|
||
stream_id_plus1[i]= tmp_stream;
|
||
data_size_mul[i]= tmp_mul;
|
||
data_size_lsb[i]= tmp_size;
|
||
if(++tmp_size >= tmp_mul){
|
||
tmp_size=0;
|
||
tmp_stream++;
|
||
}
|
||
}
|
||
}
|
||
reserved_bytes
|
||
checksum u(32)
|
||
|
||
stream_header:
|
||
stream_startcode f(64)
|
||
packet_header
|
||
stream_id v
|
||
stream_class v
|
||
fourcc vb
|
||
average_bitrate v
|
||
language_code vb
|
||
time_base_nom v
|
||
time_base_denom v
|
||
msb_timestamp_shift v
|
||
initial_timestamp_predictor v(3)
|
||
initial_data_size_predictor v(2)
|
||
fixed_fps u(1)
|
||
index_flag u(1)
|
||
reserved u(6)
|
||
for(;;){
|
||
codec_specific_data_type v
|
||
if(codec_specific_data_type==0) break;
|
||
codec_specific_data vb
|
||
}
|
||
|
||
video_stream_header:
|
||
stream_header
|
||
width v
|
||
height v
|
||
sample_width v
|
||
sample_height v
|
||
colorspace_type v
|
||
reserved_bytes
|
||
checksum u(32)
|
||
|
||
audio_stream_header:
|
||
stream_header
|
||
samplerate_mul v
|
||
channel_count v
|
||
reserved_bytes
|
||
checksum u(32)
|
||
|
||
|
||
frame
|
||
if(frame_type == 2){
|
||
frame_type2_startcode f(64)
|
||
}
|
||
frame_code f(8)
|
||
if(flags[frame_code]&1){
|
||
packet header
|
||
}
|
||
if(stream_id_plus1[frame_code]==0){
|
||
stream_id v
|
||
}
|
||
if(flags[frame_code]&16){
|
||
if(flags[frame_code]&4){
|
||
timestamp v
|
||
}else{
|
||
lsb_timestamp v
|
||
}
|
||
}
|
||
if(flags[frame_code]&2){
|
||
data_size_msb v
|
||
}
|
||
data
|
||
|
||
Index:
|
||
index_startcode f(64)
|
||
packet header
|
||
stream_id v
|
||
index_length v
|
||
for(i=0; i<index_length; i++){
|
||
index_timestamp v
|
||
index_position v
|
||
}
|
||
reserved_bytes
|
||
checksum u(32)
|
||
|
||
info_packet: (optional)
|
||
info_startcode f(64)
|
||
packet header
|
||
for(;;){
|
||
id v
|
||
if(id==0) break
|
||
name= info_table[id][0]
|
||
type= info_table[id][1]
|
||
if(type==NULL)
|
||
type vb
|
||
if(name==NULL)
|
||
name vb
|
||
if(type=="v")
|
||
value v
|
||
else
|
||
value vb
|
||
}
|
||
reserved_bytes
|
||
checksum u(32)
|
||
|
||
|
||
forward_ptr
|
||
backward_ptr
|
||
pointer to the next / previous packet
|
||
pointers are relative and backward pointer is implicitelly negative
|
||
Note: a frame with 0 bytes means that its skiped
|
||
Note: the forward pointer is equal to the size of this packet including
|
||
the header
|
||
the backward pointer is equal to the size of the previous packet
|
||
Example:
|
||
0
|
||
size1 (size of frame1 including header)
|
||
frame1
|
||
|
||
size1
|
||
size2
|
||
frame2
|
||
|
||
size2
|
||
size3
|
||
frame3
|
||
|
||
|
||
*_startcode
|
||
all startcodes start with 'N'
|
||
|
||
main_startcode
|
||
0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48)
|
||
stream_starcode
|
||
0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48)
|
||
frame_type2_startcode
|
||
0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48)
|
||
index_startcode
|
||
0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48)
|
||
info_startcode
|
||
0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48)
|
||
|
||
version
|
||
1 for now
|
||
|
||
stream_id
|
||
Note: streams with a lower relative class MUST have a lower relative id
|
||
so a stream with class 0 MUST allways have a id which is lower then any
|
||
stream with class > 0
|
||
stream_id MUST be < stream_count
|
||
|
||
stream_class
|
||
0 video
|
||
32 audio
|
||
64 subtiles
|
||
Note the remaining values are reserved and MUST NOT be used
|
||
a decoder MUST ignore streams with reserved classes
|
||
|
||
fourcc
|
||
identification for the codec
|
||
example: "H264"
|
||
MUST contain 2 or 4 bytes, note, this might be increased in the future
|
||
if needed
|
||
|
||
language_code
|
||
ISO 639 and ISO 3166 for language/country code
|
||
something like "usen" (US english), can be 0
|
||
if unknown
|
||
see http://www.loc.gov/standards/iso639-2/englangn.html
|
||
and http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html
|
||
|
||
time_base_nom / time_base_denom = time_base
|
||
the number of timer ticks per second, this MUST be equal to the fps
|
||
if the fixed_fps is 1
|
||
time_base_denom MUST not be 0
|
||
time_base_nom and time_base_denom MUST be relative prime
|
||
time_base_nom MUST be < 2^16
|
||
examples:
|
||
fps time_base_nom time_base_denom
|
||
30 30 1
|
||
29.97 30000 1001
|
||
23.976 24000 1001
|
||
sample_rate sample_rate_mul time_base_nom time_base_denom
|
||
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
|
||
|
||
msb_timestamp_shift
|
||
amount of bits msb_timestamp is shifted left before adding lsb_timestamp
|
||
MUST be <16
|
||
|
||
fixed_fps
|
||
1 indicates that the fps is fixed
|
||
|
||
index_flag
|
||
1 indicates that this file has an index
|
||
Note, all files SHOULD have an index at the end except, (realtime) streams
|
||
Note, all streams SHOULD have an index
|
||
|
||
codec_specific_data_type
|
||
0 none/end
|
||
1 native
|
||
2 bitmapinfoheader
|
||
3 waveformatex
|
||
4 imagedesc
|
||
5 sounddesc
|
||
"native", means a simple api & container independanet storage form,
|
||
for example some mpeg4-es headers
|
||
|
||
codec_specific_data
|
||
private global data for a codec (could be huffman tables or ...)
|
||
|
||
frame_code
|
||
the meaning of this byte is stored in the main header
|
||
the value 78 ('N') is forbidden to ensure that the byte is always
|
||
different from the first byte of any startcode
|
||
|
||
flags[frame_code]
|
||
the bits of the flags from MSB to LSB are KKTTTDP
|
||
P is 1 for type 1 and 2 packets, 0 for type 0 packets
|
||
TTT is the timestamp_code, 000,001,010 use the last timestamp + the
|
||
first, second and third last unique timestamp difference, so if
|
||
the timestamp differences, are +3,+1,+2,+2,+1 then last diff is
|
||
+1, second is +2 and third is +3
|
||
100,101 mean that the lsb or full timestamp is coded
|
||
if TTT is 100, then the timestamp is calculated by
|
||
mask = (1<<msb_timestamp_shift)-1;
|
||
delta= last_timestamp - mask/2
|
||
timestamp= ((timestamp_lsb-delta)&mask) + delta
|
||
TTT must be 100 or 101 if the packet_type is not 0
|
||
the last timestamp differences are reset to the default values
|
||
from the stream header if a packet of type not 0 in encountered
|
||
if D is 1 then data_size_msb is coded, otherwise its 0
|
||
KK is the keyframe_type
|
||
00-> no keyframe,
|
||
01-> keyframe,
|
||
flags=1 can be used to mark illegal frame_code bytes
|
||
frame_code=78 must have flags=1
|
||
|
||
frame_type
|
||
0<><30><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>is indicated by (flags[frame_code]&1)==0
|
||
1<><31><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>is indicated by (flags[frame_code]&1)==1 && !startcode
|
||
2<><32><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>is indicated by (flags[frame_code]&1)==1 && startcode
|
||
there SHOULD not be more then 0.5 seconds or 16kbyte of type 0 frames
|
||
wihout a intervening frame of different frame_type
|
||
* type 2 frames MUST be decodeable independantly of any other frames
|
||
this means they MUST be keyframes and they MUST use a full timestamp
|
||
* type 1 frames MUST not depend(1) upon any other frames, this means,
|
||
they MUST use a full timestamp
|
||
* type 0 frames MUST not depend(1) upon frames prior to the last type
|
||
1/2 frames
|
||
depend(1) means dependancy on the container level (NUT) not dependancy
|
||
on the codec level
|
||
|
||
stream_id_plus1[frame_code]
|
||
must be <250
|
||
if its 0 then the stream_id is coded in the frame
|
||
|
||
data_size_mul[frame_code]
|
||
must be <250
|
||
|
||
data_size_lsb[frame_code]
|
||
must be <250
|
||
|
||
data_size
|
||
if(data_size_lsb == data_size_mul)
|
||
data_size= last;
|
||
else if(data_size_lsb == data_size_mul+1)
|
||
data_size= next last;
|
||
else if(data_size_lsb < data_size_mul)
|
||
data_size= data_size_lsb + data_size_msb*data_size_mul;
|
||
else reserved
|
||
last and next last are reset to the values stored in the stream header
|
||
if an frame with type > 0 is encountered
|
||
|
||
lsb_timestamp
|
||
least significant bits of the timestamp in time_base precission
|
||
Example: IBBP display order
|
||
keyframe timestamp=0 -> timestamp=0
|
||
frame lsb_timestamp=3 -> timestamp=3
|
||
frame lsb_timestamp=1 -> timestamp=1
|
||
frame lsb_timestamp=2 -> timestamp=2
|
||
...
|
||
keyframe msb_timestamp=257 -> timestamp=257
|
||
frame lsb_timestamp=255->timestamp=255
|
||
frame lsb_timestamp=0 -> timestamp=256
|
||
frame lsb_timestamp=4 -> timestamp=260
|
||
frame lsb_timestamp=2 -> timestamp=258
|
||
frame lsb_timestamp=3 -> timestamp=259
|
||
all timestamps of keyframes of a single stream MUST be monotone
|
||
|
||
width/height
|
||
MUST be set to the coded width/height
|
||
|
||
sample_width/sample_height (aspect ratio)
|
||
sample_width is the horizontal distance between samples
|
||
sample_width and sample_height MUST be relative prime if not zero
|
||
MUST be 0 if unknown
|
||
|
||
colorspace_type
|
||
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_mul
|
||
the number of samples per second in one time_base unit
|
||
samplerate = time_base*samplerate_mul
|
||
|
||
zero_bit
|
||
MUST be 0, its there to distinguish non keyframes from other packets,
|
||
Note: all packets have a 64-bit startcode except non-keyframes to reduce
|
||
their size, and all startcodes start with a 1 bit
|
||
|
||
checksum
|
||
adler32 checksum
|
||
|
||
index_timestamp
|
||
value in time_base precission, relative to the last index_timestamp
|
||
|
||
index_position
|
||
position in bytes of the first byte of the keyframe header, relative
|
||
to the last index_position
|
||
|
||
id
|
||
the id of the type/name pair, so its more compact
|
||
0 means end
|
||
|
||
type
|
||
for example: "UTF8" -> String or "JPEG" -> jpeg image
|
||
Note: nonstandard fields should be prefixed by "X-"
|
||
Note: MUST be less than 6 byte long (might be increased to 64 later)
|
||
|
||
name
|
||
the name of the info entry, valid names are
|
||
"TotalTime" total length of the stream in msecs
|
||
"StreamId" the stream(s) to which the info packet applies
|
||
"StartTimestamp"
|
||
"EndTimestamp" the time range in msecs to which the info applies
|
||
"SegmentId" a unique id for the streams + time specified
|
||
"Author"
|
||
"Description"
|
||
"Copyright"
|
||
"Encoder" the name & version of the software used for encoding
|
||
"Title"
|
||
"Cover" an image of the (cd,dvd,vhs,..) cover (preferable PNG or JPEG)
|
||
"Source" "DVD", "VCD", "CD", "MD", "FM radio", "VHS", "TV",
|
||
"LD"
|
||
Optional: appended PAL,NTSC,SECAM, ... in parentheses
|
||
"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: dont forget the timezone
|
||
"ReplayGain"
|
||
"Keywords"
|
||
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-"
|
||
Note: MUST be less than 64 bytes long
|
||
|
||
value
|
||
value of this name/type pair
|
||
|
||
stuffing
|
||
0x80 can be placed infront of any type v entry for stuffing
|
||
purposes
|
||
|
||
info_table[][2]={
|
||
{NULL , NULL }, // end
|
||
{NULL , NULL },
|
||
{NULL , "UTF8"},
|
||
{NULL , "v"},
|
||
{NULL , "s"},
|
||
{"StreamId" , "v"},
|
||
{"SegmentId" , "v"},
|
||
{"StartTimestamp" , "v"},
|
||
{"EndTimestamp" , "v"},
|
||
{"Author" , "UTF8"},
|
||
{"Titel" , "UTF8"},
|
||
{"Description" , "UTF8"},
|
||
{"Copyright" , "UTF8"},
|
||
{"Encoder" , "UTF8"},
|
||
{"Keyword" , "UTF8"},
|
||
{"Cover" , "JPEG"},
|
||
{"Cover" , "PNG"},
|
||
};
|
||
|
||
Structure:
|
||
|
||
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)
|
||
|
||
headers may be repated, but if they are then they MUST all be repeated together
|
||
and repeated headers MUST be identical
|
||
|
||
headers MUST be repeated every 10sec at least ? FIXME
|
||
headers MUST be repeated BEFORE keyframes
|
||
headers MUST be repeated at least twice (so they exist 3 times in a file)
|
||
|
||
Index
|
||
the index can be repeated but there SHOULD be at least one for each stream at
|
||
the end
|
||
Note: in case of realtime streaming there is no end, so no index there either
|
||
|
||
Info packets
|
||
the info_packet can be repeated, it can also contain different names & values
|
||
each time but only if allso 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
|
||
|
||
Unknown packets
|
||
MUST be ignored by the decoder
|
||
|
||
Sample code (GPL, & untested)
|
||
|
||
typedef BufferContext{
|
||
uint8_t *buf;
|
||
uint8_t *buf_ptr;
|
||
}BufferContext;
|
||
|
||
static inline uint64_t get_bytes(BufferContext *bc, int count){
|
||
uint64_t val=0;
|
||
|
||
assert(count>0 && count<9)
|
||
|
||
for(i=0; i<count; i++){
|
||
val <<=8;
|
||
val += *(bc->buf_ptr++);
|
||
}
|
||
|
||
return val;
|
||
}
|
||
|
||
static inline void put_bytes(BufferContext *bc, int count, uint64_t val){
|
||
uint64_t val=0;
|
||
|
||
assert(count>0 && count<9)
|
||
|
||
for(i=count-1; i>=0; i--){
|
||
*(bc->buf_ptr++)= val >> (8*i);
|
||
}
|
||
|
||
return val;
|
||
}
|
||
|
||
static inline uint64_t get_v(BufferContext *bc){
|
||
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;
|
||
}
|
||
|
||
static inline int put_v(BufferContext *bc, uint64_t val){
|
||
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;
|
||
}
|
||
|
||
Authors
|
||
|
||
Folks from MPlayer Developers Mailinglist (http://www.mplayehrq.hu/).
|
||
Authors in ABC-order: (FIXME! Tell us if we left you out)
|
||
Beregszaszi, Alex (alex@fsn.hu)
|
||
Bunkus, Moritz (moritz@bunkus.org)
|
||
Diedrich, Tobias (td@sim.uni-hannover.de)
|
||
Franz, Fabian (FabianFranz@gmx.de)
|
||
Gereoffy, Arpad (arpi@thot.banki.hu)
|
||
Hess, Andreas (jaska@gmx.net)
|
||
Niedermayer, Michael (michaelni@gmx.at)
|