Mercurial > mplayer.hg
annotate DOCS/tech/mpcf.txt @ 14561:a226d301eec1
Handle missing palettes in the info part of VobSubs in Matroska files correctly by giving mplayer a NULL pointer. This way it will use a default palette instead of black only. Patch by Csillag Kristof (fenwick () freemail ! hu)
author | mosu |
---|---|
date | Fri, 21 Jan 2005 18:25:44 +0000 |
parents | 6cdd5669e930 |
children | ebc5136f2a56 |
rev | line source |
---|---|
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
1 NUT Open Container Format DRAFT 20050111 |
10817 | 2 ---------------------------------------- |
9294 | 3 |
4 | |
5 | |
6 Intro: | |
7 | |
8 Features / goals: | |
9 (supported by the format, not necessary by a specific implementation) | |
10 | |
11 Simple | |
12 use the same encoding for nearly all fields | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
13 simple decoding, so slow cpus (and embedded systems) can handle it |
9294 | 14 Extendible |
15 no limit for the possible values for all fields (using universal vlc) | |
16 allow adding of new headers in the future | |
17 allow adding more fields at the end of headers | |
18 Compact | |
19 ~0.2% overhead, for normal bitrates | |
20 index is <10kb per hour (1 keyframe every 3sec) | |
10831 | 21 a usual header for a file is about 100bytes (audio + video headers together) |
12082 | 22 a packet header is about ~1-8 bytes |
9294 | 23 Error resistant |
24 seeking / playback without an index | |
25 headers & index can be repeated | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
26 damaged files can be played back with minimal data lost and fast |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
27 resyncing times |
9294 | 28 |
29 | |
30 | |
31 Definitions: | |
32 | |
33 MUST the specific part must be done to conform to this standard | |
34 SHOULD its recommanded to be done that way but its not strictly required | |
35 | |
36 | |
37 | |
38 Syntax: | |
39 | |
9295 | 40 Type definitions: |
12209 | 41 |
13047 | 42 f(x) n fixed bits in big-endian order |
12209 | 43 u(x) unsigned number encoded in x bits in MSB first order |
44 | |
9295 | 45 v |
46 value=0 | |
47 do{ | |
48 more_data u(1) | |
49 data u(7) | |
50 value= 128*value + data | |
51 }while(more_data) | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
52 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
53 s |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
54 temp v |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
55 temp++ |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
56 if(temp&1) value= -(temp>>1) |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
57 else value= (temp>>1) |
9323 | 58 |
59 b (binary data or string) | |
60 for(i=0; i<length; i++){ | |
61 data[i] u(8) | |
9295 | 62 } |
9335
de287fe94511
lang & country codes from ISO & utf8 requirement (ideas from Tobias Diedrich <td at sim dot uni-hannover dot de>
michael
parents:
9325
diff
changeset
|
63 Note: strings MUST be encoded in utf8 |
9295 | 64 |
12117 | 65 vb |
66 length v | |
67 value b | |
68 | |
9295 | 69 |
70 Bitstream syntax: | |
9294 | 71 packet header |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
72 forward ptr v |
9294 | 73 |
74 align_byte | |
75 while(not byte aligned) | |
76 one f(1) | |
77 | |
78 reserved_bytes | |
79 for(i=0; i<forward_ptr - length_of_non_reserved; i++) | |
80 reserved u(8) | |
12184 | 81 a demuxer MUST ignore any reserved bytes |
82 a muxer MUST NOT write any reserved bytes, as this would make it | |
10824 | 83 inpossible to add new fields at the end of packets in the future in |
84 a compatible way | |
85 | |
9294 | 86 main header: |
10831 | 87 main_startcode f(64) |
9294 | 88 packet header |
89 version v | |
90 stream_count v | |
12333 | 91 max_distance v |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
92 max_index_distance v |
12413 | 93 global_time_base_nom v |
94 global_time_base_denom v | |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
95 for(i=0; i<256; ){ |
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
96 tmp_flag v |
12428 | 97 tmp_fields v |
98 if(tmp_fields>0) tmp_timestamp s | |
99 if(tmp_fields>1) tmp_mul v | |
100 if(tmp_fields>2) tmp_stream v | |
101 if(tmp_fields>3) tmp_size v | |
102 else tmp_size=0 | |
103 if(tmp_fields>4) tmp_res v | |
104 else tmp_res=0 | |
105 if(tmp_fields>5) count v | |
106 else count= tmp_mul - tmp_size | |
107 for(j=6; j<tmp_fields; j++){ | |
108 tmp_reserved[i] v | |
109 } | |
110 for(j=0; j<count && i<256; j++, i++){ | |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
111 flags[i]= tmp_flag; |
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
112 stream_id_plus1[i]= tmp_stream; |
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
113 data_size_mul[i]= tmp_mul; |
12428 | 114 data_size_lsb[i]= tmp_size + j; |
12413 | 115 timestamp_delta[i]= tmp_timestamp; |
12501 | 116 reserved_count[i]= tmp_res; |
12082 | 117 } |
118 } | |
9294 | 119 reserved_bytes |
120 checksum u(32) | |
121 | |
122 stream_header: | |
10831 | 123 stream_startcode f(64) |
9294 | 124 packet_header |
125 stream_id v | |
126 stream_class v | |
12150 | 127 fourcc vb |
9294 | 128 average_bitrate v |
9297 | 129 time_base_nom v |
130 time_base_denom v | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
131 msb_timestamp_shift v |
12333 | 132 decode_delay v |
9294 | 133 fixed_fps u(1) |
9356 | 134 reserved u(6) |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
135 codec_specific_data vb |
9294 | 136 |
137 video_stream_header: | |
138 stream_header | |
139 width v | |
140 height v | |
141 sample_width v | |
142 sample_height v | |
143 colorspace_type v | |
144 reserved_bytes | |
145 checksum u(32) | |
146 | |
147 audio_stream_header: | |
148 stream_header | |
12333 | 149 samplerate_nom v |
150 samplerate_denom v | |
9294 | 151 channel_count v |
152 reserved_bytes | |
153 checksum u(32) | |
9420 | 154 |
12082 | 155 |
9294 | 156 frame |
12082 | 157 frame_code f(8) |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
158 if(stream_id_plus1[frame_code]==0){ |
12082 | 159 stream_id v |
160 } | |
12413 | 161 if(timestamp_delta[frame_code]==0){ |
12261 | 162 coded_timestamp v |
163 } | |
12413 | 164 if(flags[frame_code]&1){ |
12082 | 165 data_size_msb v |
166 } | |
12501 | 167 for(i=0; i<reserved_count[frame_code]; i++) |
12413 | 168 reserved v |
12082 | 169 data |
170 | |
9294 | 171 Index: |
10831 | 172 index_startcode f(64) |
9294 | 173 packet header |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
174 stream_id v |
9294 | 175 index_length v |
176 for(i=0; i<index_length; i++){ | |
177 index_timestamp v | |
178 index_position v | |
179 } | |
9310 | 180 reserved_bytes |
9294 | 181 checksum u(32) |
182 | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
183 info_packet: (optional) |
10831 | 184 info_startcode f(64) |
9294 | 185 packet header |
9323 | 186 for(;;){ |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
187 id v |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
188 if(id==0) break |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
189 name= info_table[id][0] |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
190 type= info_table[id][1] |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
191 if(type==NULL) |
12117 | 192 type vb |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
193 if(name==NULL) |
12117 | 194 name vb |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
195 if(type=="v") |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
196 value v |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
197 else |
12117 | 198 value vb |
9323 | 199 } |
9310 | 200 reserved_bytes |
9294 | 201 checksum u(32) |
9323 | 202 |
12413 | 203 sync_point |
204 frame_startcode f(64) | |
205 global_timestamp v | |
206 | |
12242 | 207 file |
208 file_id_string | |
12502 | 209 while(!eof && next_code != index_startcode){ |
12242 | 210 main_header |
211 for(i=0; i<stream_count; i++){ | |
212 if(next_packet==video_stream_header) | |
213 video_stream_header | |
214 else | |
215 audio_stream_header | |
216 } | |
12413 | 217 while(next_code != main_startcode){ |
218 if(next_code == info_startcode) | |
12242 | 219 info_packet |
12368 | 220 else{ |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
221 if(next_code == frame_startcode) |
12413 | 222 sync_point |
12242 | 223 frame |
12368 | 224 } |
12242 | 225 } |
226 } | |
12502 | 227 index |
9323 | 228 |
9294 | 229 forward_ptr |
12238 | 230 size of the packet (exactly the distance from the first byte of the |
231 startcode of the current packet to the first byte of the following packet | |
12242 | 232 |
233 file_id_string | |
234 "nut/multimedia container\0" | |
9323 | 235 |
236 *_startcode | |
12162 | 237 all startcodes start with 'N' |
238 | |
239 main_startcode | |
240 0x7A561F5F04ADULL + (((uint64_t)('N'<<8) + 'M')<<48) | |
241 stream_starcode | |
242 0x11405BF2F9DBULL + (((uint64_t)('N'<<8) + 'S')<<48) | |
12333 | 243 frame_startcode |
12162 | 244 0xE4ADEECA4569ULL + (((uint64_t)('N'<<8) + 'K')<<48) |
12392 | 245 frame_startcodes SHOULD be placed immedeatly before a keyframe if the |
246 previous frame of the same stream was a non-keyframe, unless such | |
247 non-keyframe - keyframe tansitions are very frequent | |
12365
dc05db3f172f
additional start_code rule (implemenattion does this since a long time already)
michael
parents:
12333
diff
changeset
|
248 |
12162 | 249 index_startcode |
250 0xDD672F23E64EULL + (((uint64_t)('N'<<8) + 'X')<<48) | |
251 info_startcode | |
252 0xAB68B596BA78ULL + (((uint64_t)('N'<<8) + 'I')<<48) | |
9294 | 253 |
254 version | |
12238 | 255 2 for now |
256 | |
12333 | 257 max_distance |
258 max distance of frame_startcodes, the distance may only be larger if | |
259 there is only a single frame between the 2 frame_startcodes | |
260 this can be used by the demuxer to detect damaged frame headers if the | |
261 damage results in a too long chain | |
12501 | 262 SHOULD be set to <=32768 or at least <=65536 unless there is a very good |
263 reason to set it higher otherwise reasonable error recovery will be | |
264 impossible | |
265 | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
266 max_index_distance |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
267 max distance of keyframes which are represented in the index, the |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
268 distance between consecutive entries A and B may only be larger if |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
269 there are no keyframes within this stream between A and B |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
270 SHOULD be set to <=32768 or at least <=65536 unless there is a very good |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
271 reason to set it higher |
12501 | 272 |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
273 stream_id[FIXME] |
9294 | 274 Note: streams with a lower relative class MUST have a lower relative id |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
275 so a stream with class 0 MUST always have a id which is lower then any |
9294 | 276 stream with class > 0 |
12150 | 277 stream_id MUST be < stream_count |
9294 | 278 |
279 stream_class | |
280 0 video | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
281 1 audio |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
282 2 subtiles |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
283 3 metadata |
9294 | 284 Note the remaining values are reserved and MUST NOT be used |
12184 | 285 a demuxer MUST ignore streams with reserved classes |
9294 | 286 |
287 fourcc | |
288 identification for the codec | |
9323 | 289 example: "H264" |
10817 | 290 MUST contain 2 or 4 bytes, note, this might be increased in the future |
291 if needed | |
9294 | 292 |
9297 | 293 time_base_nom / time_base_denom = time_base |
9294 | 294 the number of timer ticks per second, this MUST be equal to the fps |
295 if the fixed_fps is 1 | |
9297 | 296 time_base_denom MUST not be 0 |
297 time_base_nom and time_base_denom MUST be relative prime | |
12254 | 298 time_base_nom MUST be < 2^31 |
9297 | 299 examples: |
300 fps time_base_nom time_base_denom | |
301 30 30 1 | |
302 29.97 30000 1001 | |
303 23.976 24000 1001 | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
304 sample_rate sample_rate_mul time_base_nom time_base_denom |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
305 44100 1 44100 1 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
306 44100 64 11025 16 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
307 48000 1024 375 8 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
308 Note: the advantage to using a large sample_rate_mul is that the |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
309 timestamps need fewer bits |
9294 | 310 |
12413 | 311 global_time_base_nom / global_time_base_denom = global_time_base |
312 the number of timer ticks per second | |
313 global_time_base_denom MUST not be 0 | |
314 global_time_base_nom and global_time_base_denom MUST be relative prime | |
315 global_time_base_nom MUST be < 2^31 | |
316 | |
317 global_timestamp | |
318 timestamp in global_time_base units | |
319 when a global_timestamp is encountered the last_timestamp of all streams | |
320 is set to the following: | |
321 ln= global_time_base_denom*time_base_nom | |
322 sn= global_timestamp | |
323 d1= global_time_base_nom | |
324 d2= time_base_denom | |
325 last_timestamp= (ln/d1*sn + ln%d1*sn/d1)/d2 | |
326 Note, this calculation MUST be done with unsigned 64 bit integers, and | |
327 is equivalent to (ln*sn)/(d1*d2) but this would require a 96bit integer | |
328 | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
329 msb_timestamp_shift |
12261 | 330 amount of bits in lsb_timestamp |
9294 | 331 MUST be <16 |
332 | |
12333 | 333 decode_delay |
334 maximum time between input and output for a codec, used to generate dts | |
335 from pts | |
336 is 0 for streams without b frames, and 1 for streams with b frames, may | |
337 be larger for future codecs | |
338 | |
9294 | 339 fixed_fps |
340 1 indicates that the fps is fixed | |
341 | |
9356 | 342 codec_specific_data |
343 private global data for a codec (could be huffman tables or ...) | |
12082 | 344 |
345 frame_code | |
346 the meaning of this byte is stored in the main header | |
347 the value 78 ('N') is forbidden to ensure that the byte is always | |
348 different from the first byte of any startcode | |
9420 | 349 |
12082 | 350 flags[frame_code] |
12413 | 351 the bits of the flags from MSB to LSB are KD |
12261 | 352 if D is 1 then data_size_msb is coded, otherwise data_size_msb is 0 |
12238 | 353 K is the keyframe_type |
354 0-> no keyframe, | |
355 1-> keyframe, | |
12413 | 356 flags=4 can be used to mark illegal frame_code bytes |
357 frame_code=78 must have flags=4 | |
12333 | 358 * frames MUST not depend(1) upon frames prior to the last |
359 frame_startcode | |
12110
a34dc5a369ca
restrictions to ensure that O(log n) seeking and error recovery is possible
michael
parents:
12084
diff
changeset
|
360 depend(1) means dependancy on the container level (NUT) not dependancy |
a34dc5a369ca
restrictions to ensure that O(log n) seeking and error recovery is possible
michael
parents:
12084
diff
changeset
|
361 on the codec level |
a34dc5a369ca
restrictions to ensure that O(log n) seeking and error recovery is possible
michael
parents:
12084
diff
changeset
|
362 |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
363 stream_id_plus1[frame_code] |
12082 | 364 must be <250 |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
365 if its 0 then the stream_id is coded in the frame |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
366 |
12082 | 367 data_size_mul[frame_code] |
12379
4100528fadf1
limits too small, my CBR mp3 samples have 2x overhead after removial of size prediction
michael
parents:
12368
diff
changeset
|
368 must be <16384 |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
369 |
12082 | 370 data_size_lsb[frame_code] |
12379
4100528fadf1
limits too small, my CBR mp3 samples have 2x overhead after removial of size prediction
michael
parents:
12368
diff
changeset
|
371 must be <16384 |
12082 | 372 |
12413 | 373 timestamp_delta[frame_code] |
374 must be <16384 and >-16384 | |
375 | |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
376 data_size |
12261 | 377 data_size= data_size_lsb + data_size_msb*data_size_mul; |
12082 | 378 |
12261 | 379 coded_timestamp |
380 if coded_timestamp < (1<<msb_timestamp_shift) then its a | |
381 lsb timestamp, otherwise its a full timestamp + (1<<msb_timestamp_shift) | |
382 lsb timestamps are converted to full timesamps by: | |
383 mask = (1<<msb_timestamp_shift)-1; | |
384 delta= last_timestamp - mask/2 | |
385 timestamp= ((timestamp_lsb-delta)&mask) + delta | |
12333 | 386 a full timestamp must be used if there is no reference timestamp |
387 available after the last frame_startcode with the current stream_id | |
12261 | 388 |
9294 | 389 lsb_timestamp |
12082 | 390 least significant bits of the timestamp in time_base precission |
9294 | 391 Example: IBBP display order |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
392 keyframe timestamp=0 -> timestamp=0 |
9294 | 393 frame lsb_timestamp=3 -> timestamp=3 |
394 frame lsb_timestamp=1 -> timestamp=1 | |
395 frame lsb_timestamp=2 -> timestamp=2 | |
396 ... | |
12084
68baf8877c07
reversing the change to the forw/backw pointers, its somewhat simpler to update it if the forward pointer is first
michael
parents:
12082
diff
changeset
|
397 keyframe msb_timestamp=257 -> timestamp=257 |
12082 | 398 frame lsb_timestamp=255->timestamp=255 |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
399 frame lsb_timestamp=0 -> timestamp=256 |
9294 | 400 frame lsb_timestamp=4 -> timestamp=260 |
401 frame lsb_timestamp=2 -> timestamp=258 | |
402 frame lsb_timestamp=3 -> timestamp=259 | |
12110
a34dc5a369ca
restrictions to ensure that O(log n) seeking and error recovery is possible
michael
parents:
12084
diff
changeset
|
403 all timestamps of keyframes of a single stream MUST be monotone |
9294 | 404 |
12333 | 405 dts |
406 dts are calculated by using a decode_delay+1 sized buffer for each | |
407 stream, into which the current pts is inserted and the element with | |
408 the smallest value is removed, this is then the current dts | |
409 this buffer is initalized with decode_delay -1 elements | |
410 all frames with dts == timestamp must be monotone, that means a frame | |
411 which occures later in the stream must have a larger or equal dts | |
412 then an earlier frame | |
413 FIXME rename timestamp* to pts* ? | |
414 | |
9294 | 415 width/height |
416 MUST be set to the coded width/height | |
417 | |
418 sample_width/sample_height (aspect ratio) | |
419 sample_width is the horizontal distance between samples | |
420 sample_width and sample_height MUST be relative prime if not zero | |
421 MUST be 0 if unknown | |
422 | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
423 colorspace_type |
10166 | 424 0 unknown |
425 1 ITU Rec 624 / ITU Rec 601 Y range: 16..235 Cb/Cr range: 16..240 | |
426 2 ITU Rec 709 Y range: 16..235 Cb/Cr range: 16..240 | |
427 17 ITU Rec 624 / ITU Rec 601 Y range: 0..255 Cb/Cr range: 0..255 | |
428 18 ITU Rec 709 Y range: 0..255 Cb/Cr range: 0..255 | |
429 | |
12333 | 430 samplerate_nom / samplerate_denom = samplerate |
431 the number of samples per second | |
9294 | 432 |
433 checksum | |
12118
b8fea9441d02
switching from crc32 to adler32 checksums, cuz they are faster and simpler
michael
parents:
12117
diff
changeset
|
434 adler32 checksum |
9294 | 435 |
436 index_timestamp | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
437 value of the timetamp of a keyframe relative to the last keyframe |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
438 stored in this index |
9294 | 439 |
440 index_position | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
441 position in bytes of the first byte of a keyframe, relative to the |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
442 last keyframe stored in this index |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
443 there MUST be no keyframe with the same stream_id as this index between |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
444 2 consecutive index entries if they are more then max_index_distance |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
445 appart |
9294 | 446 |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
447 id |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
448 the id of the type/name pair, so its more compact |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
449 0 means end |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
450 |
9323 | 451 type |
9347
97888c25ae60
changing name to "nut" for now, we can change it again if we agree on something else
michael
parents:
9335
diff
changeset
|
452 for example: "UTF8" -> String or "JPEG" -> jpeg image |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
453 Note: nonstandard fields should be prefixed by "X-" |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
454 Note: MUST be less than 6 byte long (might be increased to 64 later) |
9323 | 455 |
13308
8ff17d153414
info packet is now file global, while meta pakcet is stream specific, as discussed with Rich
alex
parents:
13047
diff
changeset
|
456 info packet types |
9295 | 457 the name of the info entry, valid names are |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
458 "StreamId" the stream(s) to which the info packet applies |
13308
8ff17d153414
info packet is now file global, while meta pakcet is stream specific, as discussed with Rich
alex
parents:
13047
diff
changeset
|
459 |
9347
97888c25ae60
changing name to "nut" for now, we can change it again if we agree on something else
michael
parents:
9335
diff
changeset
|
460 "Author" |
97888c25ae60
changing name to "nut" for now, we can change it again if we agree on something else
michael
parents:
9335
diff
changeset
|
461 "Description" |
97888c25ae60
changing name to "nut" for now, we can change it again if we agree on something else
michael
parents:
9335
diff
changeset
|
462 "Copyright" |
9369 | 463 "Encoder" the name & version of the software used for encoding |
9347
97888c25ae60
changing name to "nut" for now, we can change it again if we agree on something else
michael
parents:
9335
diff
changeset
|
464 "Title" |
9373 | 465 "Cover" an image of the (cd,dvd,vhs,..) cover (preferable PNG or JPEG) |
9350 | 466 "Source" "DVD", "VCD", "CD", "MD", "FM radio", "VHS", "TV", |
467 "LD" | |
9373 | 468 Optional: appended PAL,NTSC,SECAM, ... in parentheses |
9350 | 469 "CaptureDevice" "BT878", "BT848", "webcam", ... (more exact names are fine too) |
470 "CreationTime" "2003-01-20 20:13:15Z", ... | |
471 (ISO 8601 format, see http://www.cl.cam.ac.uk/~mgk25/iso-time.html) | |
472 Note: dont forget the timezone | |
13308
8ff17d153414
info packet is now file global, while meta pakcet is stream specific, as discussed with Rich
alex
parents:
13047
diff
changeset
|
473 "Keywords" |
8ff17d153414
info packet is now file global, while meta pakcet is stream specific, as discussed with Rich
alex
parents:
13047
diff
changeset
|
474 "TotalTime" total length of the stream in msecs |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
475 "Language" ISO 639 and ISO 3166 for language/country code |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
476 something like "eng" (US english), can be 0 if unknown |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
477 and "multi" if several languages |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
478 see http://www.loc.gov/standards/iso639-2/englangn.html |
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
479 and http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.htmlthe language code |
12503 | 480 "Disposition" "original", "dub" (translated), "comment", "lyrics", "karaoke" |
9295 | 481 Note: if someone needs some others, please tell us about them, so we can |
482 add them to the official standard (if they are sane) | |
9360
add934b25d6d
"X-" prefix for nonstd fields & "keywords" idea by (Andreas Hess <jaska at gmx dot net>)
michael
parents:
9357
diff
changeset
|
483 Note: nonstandard fields should be prefixed by "X-" |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
484 Note: MUST be less than 64 bytes long |
9295 | 485 |
486 value | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
487 value of this name/type pair |
9295 | 488 |
9310 | 489 stuffing |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
490 0x80 can be placed infront of any type v entry for stuffing |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
491 purposes |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
492 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
493 info_table[][2]={ |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
494 {NULL , NULL }, // end |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
495 {NULL , NULL }, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
496 {NULL , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
497 {NULL , "v"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
498 {NULL , "s"}, |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
499 {"StreamId" , "v"}, |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
500 {"Author" , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
501 {"Titel" , "UTF8"}, |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
502 {"Language" , "UTF8"}, |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
503 {"Description" , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
504 {"Copyright" , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
505 {"Encoder" , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
506 {"Keyword" , "UTF8"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
507 {"Cover" , "JPEG"}, |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
508 {"Cover" , "PNG"}, |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
509 {"Disposition" , "UTF8"}, |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
510 }; |
9294 | 511 |
512 Structure: | |
513 | |
514 the headers MUST be in exactly the following order (to simplify demuxer design) | |
515 main header | |
516 stream_header (id=0) | |
517 stream_header (id=1) | |
518 ... | |
519 stream_header (id=n) | |
520 | |
521 headers may be repated, but if they are then they MUST all be repeated together | |
522 and repeated headers MUST be identical | |
12501 | 523 headers MAY only repeated at the closest possible positions after 2^x where x is |
524 an integer and the file end, so the headers may be repeated at 4102 if thats the | |
525 closest possition after 2^12=4096 at which the headers can be placed | |
9294 | 526 |
12501 | 527 headers MUST be placed at least at the begin of the file and immedeatly before |
528 the index or at the file end if there is no index | |
9310 | 529 headers MUST be repeated at least twice (so they exist 3 times in a file) |
9295 | 530 |
12501 | 531 a demuxer MUST not demux a stream which contains more than one stream, or which |
532 is wrapped in a structure to facilitate more than one stream or otherwise | |
533 duplicate the role of a container. any such file is to be considered invalid | |
534 | |
12503 | 535 info packets which describe the whole file or individual streams/tracks must be |
536 placed before any video/audio/... frames | |
537 | |
9310 | 538 Index |
12502 | 539 every sync-point must be exacty once in the index |
9311
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
540 Note: in case of realtime streaming there is no end, so no index there either |
9310 | 541 |
542 Info packets | |
543 the info_packet can be repeated, it can also contain different names & values | |
14471
6cdd5669e930
Here is an updated draft with the bits discussed previously merged:
michael
parents:
13308
diff
changeset
|
544 each time but only if also the time is different |
9310 | 545 Info packets can be used to describe the file or some part of it (chapters) |
546 | |
547 info packets, SHOULD be placed at the begin of the file at least | |
548 for realtime streaming info packets will normally be transmitted when they apply | |
549 for example, the current song title & artist of the currently shown music video | |
550 | |
551 Unknown packets | |
12184 | 552 MUST be ignored by the demuxer |
9310 | 553 |
12501 | 554 demuxer (non-normative) |
555 | |
556 in the absence of valid header at beginning, players SHOULD search for backup | |
557 headers starting at offset 2^x for each x players SHOULD end their search from a | |
558 particular offset when any startcode is found (including syncpoint) | |
559 | |
560 | |
9294 | 561 Sample code (GPL, & untested) |
562 | |
563 typedef BufferContext{ | |
564 uint8_t *buf; | |
565 uint8_t *buf_ptr; | |
566 }BufferContext; | |
567 | |
568 static inline uint64_t get_bytes(BufferContext *bc, int count){ | |
569 uint64_t val=0; | |
570 | |
571 assert(count>0 && count<9) | |
572 | |
573 for(i=0; i<count; i++){ | |
574 val <<=8; | |
575 val += *(bc->buf_ptr++); | |
576 } | |
577 | |
578 return val; | |
579 } | |
580 | |
581 static inline void put_bytes(BufferContext *bc, int count, uint64_t val){ | |
582 uint64_t val=0; | |
583 | |
584 assert(count>0 && count<9) | |
585 | |
586 for(i=count-1; i>=0; i--){ | |
587 *(bc->buf_ptr++)= val >> (8*i); | |
588 } | |
589 | |
590 return val; | |
591 } | |
592 | |
10061 | 593 static inline uint64_t get_v(BufferContext *bc){ |
9294 | 594 uint64_t val= 0; |
595 | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
596 for(; space_left(bc) > 0; ){ |
9294 | 597 int tmp= *(bc->buf_ptr++); |
598 if(tmp&0x80) | |
599 val= (val<<7) + tmp - 0x80; | |
600 else | |
9299 | 601 return (val<<7) + tmp; |
9294 | 602 } |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
603 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
604 return -1; |
9294 | 605 } |
606 | |
10061 | 607 static inline int put_v(BufferContext *bc, uint64_t val){ |
9294 | 608 int i; |
609 | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
610 if(space_left(bc) < 9) return -1; |
9294 | 611 |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
612 val &= 0x7FFFFFFFFFFFFFFFULL; // FIXME can only encode upto 63 bits currently |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
613 for(i=7; ; i+=7){ |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
614 if(val>>i == 0) break; |
9294 | 615 } |
616 | |
10827 | 617 for(i-=7; i>0; i-=7){ |
9294 | 618 *(bc->buf_ptr++)= 0x80 | (val>>i); |
619 } | |
620 *(bc->buf_ptr++)= val&0x7F; | |
9579
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
621 |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
622 return 0; |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
623 } |
89d27a306886
*signed int vlc (needs only 5 lines of code so its no increase of complexity)
michael
parents:
9422
diff
changeset
|
624 |
12333 | 625 static int64_t get_dts(int64_t pts, int64_t *pts_cache, int delay, int reset){ |
626 if(reset) memset(pts_cache, -1, delay*sizeof(int64_t)); | |
627 | |
628 while(delay--){ | |
629 int64_t t= pts_cache[delay]; | |
630 if(t < pts){ | |
631 pts_cache[delay]= pts; | |
632 pts= t; | |
633 } | |
634 } | |
635 | |
636 return pts; | |
637 } | |
638 | |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
639 Authors |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
640 |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
641 Folks from MPlayer Developers Mailinglist (http://www.mplayehrq.hu/). |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
642 Authors in ABC-order: (FIXME! Tell us if we left you out) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
643 Beregszaszi, Alex (alex@fsn.hu) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
644 Bunkus, Moritz (moritz@bunkus.org) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
645 Diedrich, Tobias (td@sim.uni-hannover.de) |
12297 | 646 Felker, Rich (dalias@aerifal.cx) |
10158
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
647 Franz, Fabian (FabianFranz@gmx.de) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
648 Gereoffy, Arpad (arpi@thot.banki.hu) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
649 Hess, Andreas (jaska@gmx.net) |
93e5428d0b3e
some changes (michael: is the colorspace_type field needed?)
alex
parents:
10061
diff
changeset
|
650 Niedermayer, Michael (michaelni@gmx.at) |