Mercurial > mplayer.hg
annotate DOCS/tech/mpcf.txt @ 9311:4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
author | michael |
---|---|
date | Fri, 07 Feb 2003 11:20:35 +0000 |
parents | b16480522be9 |
children | c503636eaf5f |
rev | line source |
---|---|
9294 | 1 MPlayer container format draft 0.01 |
2 | |
3 | |
4 | |
5 Intro: | |
6 | |
7 Features / goals: | |
8 (supported by the format, not necessary by a specific implementation) | |
9 | |
10 Simple | |
11 use the same encoding for nearly all fields | |
9295 | 12 simple decoding, so slow cpus can handle it |
9294 | 13 Extendible |
14 no limit for the possible values for all fields (using universal vlc) | |
15 allow adding of new headers in the future | |
16 allow adding more fields at the end of headers | |
17 Compact | |
18 ~0.2% overhead, for normal bitrates | |
19 index is <10kb per hour (1 keyframe every 3sec) | |
20 Error resistant | |
21 seeking / playback without an index | |
22 headers & index can be repeated | |
23 audio packet reshuffle | |
24 checksums to allow quick redownloading of damaged parts | |
25 | |
26 | |
27 | |
28 Definitions: | |
29 | |
30 MUST the specific part must be done to conform to this standard | |
31 SHOULD its recommanded to be done that way but its not strictly required | |
32 | |
33 | |
34 | |
35 Syntax: | |
36 | |
9295 | 37 Type definitions: |
38 v | |
39 value=0 | |
40 do{ | |
41 more_data u(1) | |
42 data u(7) | |
43 value= 128*value + data | |
44 }while(more_data) | |
45 | |
46 sz (zero terminated string) | |
47 for(i=0; next_byte != 0; i++){ | |
48 string[i] u(8) | |
49 } | |
50 zero_byte f(8) | |
51 | |
52 f(x) n fixed bits | |
53 u(x) unsigned number encoded in x bits in MSB first order | |
54 | |
55 | |
56 Bitstream syntax: | |
9294 | 57 packet header |
58 forward ptr v | |
59 backward ptr v | |
60 | |
61 align_byte | |
62 while(not byte aligned) | |
63 one f(1) | |
64 | |
65 reserved_bytes | |
66 for(i=0; i<forward_ptr - length_of_non_reserved; i++) | |
67 reserved u(8) | |
68 | |
69 main header: | |
70 packet header | |
71 main_startcode f(64) | |
72 version v | |
73 stream_count v | |
74 file_size v | |
9310 | 75 length_in_msec v |
9294 | 76 reserved_bytes |
77 checksum u(32) | |
78 | |
79 stream_header: | |
80 packet_header | |
81 stream_startcode f(64) | |
82 stream_id v | |
83 stream_class v | |
84 fourcc v | |
85 average_bitrate v | |
86 language_code v | |
9297 | 87 time_base_nom v |
88 time_base_denom v | |
9294 | 89 lsb_timestamp_length v |
90 fixed_fps u(1) | |
91 codec_specific_header_flag u(1) | |
92 reserved u(6) | |
93 | |
94 video_stream_header: | |
95 stream_header | |
96 width v | |
97 height v | |
98 sample_width v | |
99 sample_height v | |
100 colorspace_type v | |
101 depth v | |
102 reserved_bytes | |
103 checksum u(32) | |
104 | |
105 audio_stream_header: | |
106 stream_header | |
107 samplerate v | |
108 channel_count v | |
109 sub_packet_size v | |
110 shuffle_type v | |
111 reserved_bytes | |
112 checksum u(32) | |
113 | |
114 codec_specific_header: | |
115 packet_header | |
116 codec_specific_startcode f(64) | |
117 stream_id v | |
118 codec_specific data | |
119 checksum | |
120 | |
121 frame | |
122 packet header | |
123 if(keyframe){ | |
124 keyframe_startcode f(64) | |
125 } | |
9311
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
126 zero_bit f(1) |
9294 | 127 priority u(2) |
128 checksum_flag u(1) | |
129 msb_timestamp_flag u(1) | |
9311
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
130 reserved u(3) |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
131 lsb_timestamp v |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
132 stream_id v |
9294 | 133 if(msb_timestamp_flag) |
134 msb_timestamp v | |
135 bitstream | |
136 if(checksum_flag) | |
137 checksum u(32) | |
138 | |
139 Index: | |
140 packet header | |
141 index_startcode f(64) | |
142 stream_id v | |
143 index_length v | |
144 for(i=0; i<index_length; i++){ | |
145 index_timestamp v | |
146 index_position v | |
147 } | |
9310 | 148 reserved_bytes |
9294 | 149 checksum u(32) |
150 | |
9310 | 151 info_packet: (optional) |
9294 | 152 packet header |
153 info_startcode f(64) | |
9310 | 154 start_time v |
155 end_time v | |
9295 | 156 entry_count v |
157 for(i=0; i<entry_count; i++){ | |
158 name sz | |
159 value sz | |
160 } | |
9310 | 161 reserved_bytes |
9294 | 162 checksum u(32) |
9310 | 163 |
164 stuffing_packet: (optional) | |
165 packet_header | |
166 stuffing_startcode f(64) | |
167 for(i=0; i<forward_ptr - length_of_non_reserved; i++) | |
168 stuffing f(8) | |
9294 | 169 |
170 forward_ptr | |
171 backward_ptr | |
172 pointer to the next / previous packet | |
173 Note: a frame with 0 bytes means that its skiped | |
174 | |
175 version | |
176 0 for now | |
177 | |
178 file_size | |
179 size in bytes, can be 0 if not meaningfull (realtime streams, ...) | |
180 | |
181 length_in_msec | |
182 length of the file in milli seconds (can be 0 if realtime or such) | |
183 | |
184 stream_id | |
185 Note: streams with a lower relative class MUST have a lower relative id | |
186 so a stream with class 0 MUST allways have a id which is lower then any | |
187 stream with class > 0 | |
9295 | 188 streams should use low ids |
9294 | 189 |
190 stream_class | |
191 0 video | |
192 32 audio | |
193 64 subtiles | |
194 Note the remaining values are reserved and MUST NOT be used | |
195 | |
196 fourcc | |
197 identification for the codec | |
198 example: 'h'<<24 + '2'<<16 + '6'<<8 + '4' | |
199 | |
200 language_code | |
201 something like 'u'<<24 + 's'<<16 + 'e'<<8 + 'n' (US english), can be 0 | |
202 if unknown | |
203 | |
9297 | 204 time_base_nom / time_base_denom = time_base |
9294 | 205 the number of timer ticks per second, this MUST be equal to the fps |
206 if the fixed_fps is 1 | |
9297 | 207 time_base_denom MUST not be 0 |
208 time_base_nom and time_base_denom MUST be relative prime | |
209 time_base_nom MUST be < 2^15 | |
210 examples: | |
211 fps time_base_nom time_base_denom | |
212 30 30 1 | |
213 29.97 30000 1001 | |
214 23.976 24000 1001 | |
9294 | 215 |
216 lsb_timestamp_length | |
217 length in bits of the lsb_timestamp | |
218 MUST be <16 | |
219 | |
220 fixed_fps | |
221 1 indicates that the fps is fixed | |
222 | |
223 codec_specific_header_flag | |
224 1 indicates that this stream has a codec specific header | |
225 | |
226 msb_timestamp_flag | |
227 indicates that the msb_timestamp is coded | |
228 MUST be 1 for keyframes | |
229 | |
230 msb_timestamp | |
231 most significant bits of the timestamp, SHOULD be 0 for the first frame | |
232 | |
233 lsb_timestamp | |
234 most significant bits of the timestamp in time_base precission, with | |
235 lsb_timestamp_length bits | |
236 Example: IBBP display order | |
237 keyframe msb_timestamp=0 lsb_timestamp=0 -> timestamp=0 | |
238 frame lsb_timestamp=3 -> timestamp=3 | |
239 frame lsb_timestamp=1 -> timestamp=1 | |
240 frame lsb_timestamp=2 -> timestamp=2 | |
241 ... | |
242 keyframe msb_timestamp=1 lsb_timestamp=1 -> timestamp=257 | |
243 frame msb_timestamp=0 lsb_timestamp=255->timestamp=255 | |
244 frame msb_timestamp=1 lsb_timestamp=0 -> timestamp=256 | |
245 frame lsb_timestamp=4 -> timestamp=260 | |
246 frame lsb_timestamp=2 -> timestamp=258 | |
247 frame lsb_timestamp=3 -> timestamp=259 | |
248 | |
249 width/height | |
250 MUST be set to the coded width/height | |
251 | |
252 sample_width/sample_height (aspect ratio) | |
253 sample_width is the horizontal distance between samples | |
254 sample_width and sample_height MUST be relative prime if not zero | |
255 MUST be 0 if unknown | |
256 | |
257 depth | |
258 for compatibility with some win32 codecs | |
259 | |
9311
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
260 zero_bit |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
261 MUST be 0, its there to distinguish non keyframes from other packets, |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
262 Note: all packets have a 64-bit startcode except non-keyframes to reduce |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
263 their size, and all startcodes start with a 1 bit |
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
264 |
9294 | 265 priority |
266 if 0 then the frame isnt used as reference (b frame) and can be droped | |
267 MUST be > 0 for keyframes | |
268 | |
269 sub_packet_size | |
270 size of an audio packet | |
271 Note a subpacket MUST be in exactly one packet, it cannot be split | |
272 | |
273 shuffle_type | |
274 audio is often encoded in small fixed size packets, and to increase the | |
275 error robustness these can be shuffled | |
276 0 -> no shuffle | |
277 1-16 -> interleave packets by 2^n | |
278 | |
279 checksum | |
9307
ec18ad315bbe
10l (copy & pasting the generator poly for crc32 from ogg was a bad idea...)
michael
parents:
9299
diff
changeset
|
280 crc32 checksum using the generator polynomial 0x104c11db7 (same as ogg) |
9294 | 281 |
282 checksum_flag | |
283 indicates that the frame_checksum is coded | |
284 must be 1 for the last non keyframe before a keyframe | |
285 | |
286 frame_checksum | |
287 identical to checksum, but instead of covering just the current | |
288 packet, it covers all frames of the same stream id since the last | |
289 checksum | |
290 this field is only coded if checksum_flag=1 | |
291 | |
292 index_timestamp | |
293 value in time_base precission, relative to the last index_timestamp | |
294 | |
295 index_position | |
296 position in bytes of the first byte of the keyframe header, relative | |
297 to the last index_position | |
298 | |
9310 | 299 start_time, stop_time |
300 the time range in msecs to which the info applies | |
301 Note: can be used to mark chapters | |
302 | |
9295 | 303 name |
304 the name of the info entry, valid names are | |
305 "Author","Description","Copyright","Encoder","Title" | |
306 Note: if someone needs some others, please tell us about them, so we can | |
307 add them to the official standard (if they are sane) | |
308 | |
309 value | |
310 | |
9310 | 311 stuffing |
312 0xFF | |
9294 | 313 |
314 Structure: | |
315 | |
316 the headers MUST be in exactly the following order (to simplify demuxer design) | |
317 main header | |
318 stream_header (id=0) | |
319 codec_specific_header (id=0) | |
320 stream_header (id=1) | |
321 codec_specific_header (id=1) | |
322 ... | |
323 stream_header (id=n) | |
324 codec_specific_header (id=n) | |
325 | |
326 headers may be repated, but if they are then they MUST all be repeated together | |
327 and repeated headers MUST be identical | |
328 | |
329 headers MUST be repeated every 10sec at least ? FIXME | |
9310 | 330 headers MUST be repeated at least twice (so they exist 3 times in a file) |
9295 | 331 |
9310 | 332 Index |
333 the index can be repeated but there MUST be at least one at the end | |
9311
4b04416ada91
zero_bit for normal frames, so we can distinguish them from other packets
michael
parents:
9310
diff
changeset
|
334 Note: in case of realtime streaming there is no end, so no index there either |
9310 | 335 |
336 Info packets | |
337 the info_packet can be repeated, it can also contain different names & values | |
338 each time but only if allso the time is different | |
339 Info packets can be used to describe the file or some part of it (chapters) | |
340 | |
341 info packets, SHOULD be placed at the begin of the file at least | |
342 for realtime streaming info packets will normally be transmitted when they apply | |
343 for example, the current song title & artist of the currently shown music video | |
344 | |
345 Stuffing packets | |
346 can be used as a filler, for example to leave some empty space at the begin for | |
347 a copy of the index | |
348 | |
349 Unknown packets | |
350 MUST be ignored by the decoder | |
351 | |
9294 | 352 Sample code (GPL, & untested) |
353 | |
354 typedef BufferContext{ | |
355 uint8_t *buf; | |
356 uint8_t *buf_ptr; | |
357 }BufferContext; | |
358 | |
359 static inline uint64_t get_bytes(BufferContext *bc, int count){ | |
360 uint64_t val=0; | |
361 | |
362 assert(count>0 && count<9) | |
363 | |
364 for(i=0; i<count; i++){ | |
365 val <<=8; | |
366 val += *(bc->buf_ptr++); | |
367 } | |
368 | |
369 return val; | |
370 } | |
371 | |
372 static inline void put_bytes(BufferContext *bc, int count, uint64_t val){ | |
373 uint64_t val=0; | |
374 | |
375 assert(count>0 && count<9) | |
376 | |
377 for(i=count-1; i>=0; i--){ | |
378 *(bc->buf_ptr++)= val >> (8*i); | |
379 } | |
380 | |
381 return val; | |
382 } | |
383 | |
384 static inline uint64_t get_v(BufferContext *bc){ | |
385 uint64_t val= 0; | |
386 | |
387 for(;;){ | |
388 int tmp= *(bc->buf_ptr++); | |
389 if(tmp&0x80) | |
390 val= (val<<7) + tmp - 0x80; | |
391 else | |
9299 | 392 return (val<<7) + tmp; |
9294 | 393 } |
394 } | |
395 | |
396 static inline void put_v(BufferContext *bc, uint64_t val){ | |
397 int i; | |
398 | |
399 assert(val); | |
400 | |
401 for(i=56;; i-=8){ | |
402 if(val>>i) break; | |
403 } | |
404 | |
405 for(;i>0; i-=8){ | |
406 *(bc->buf_ptr++)= 0x80 | (val>>i); | |
407 } | |
408 *(bc->buf_ptr++)= val&0x7F; | |
409 } | |
410 | |
411 | |
412 Example stream | |
413 | |
414 main header | |
415 video_stream_header (stream 0, video jpjp, timebase 30, lsb_timestamp_length=8) | |
416 codec_specific_header (stream 0) | |
417 video_stream_header (stream 1 subtitle usen, timebase 30, lsb_timestamp_length=8) | |
418 video_stream_header (stream 2 subtitle atde, timebase 30, lsb_timestamp_length=8) | |
419 audio_stream_header (stream 3, audio jpjp, timebase 1 , lsb_timestamp_length=8) | |
420 audio_stream_header (stream 4, audio usen, timebase 1 , lsb_timestamp_length=8) | |
421 index (stream 0) | |
422 keyframe (stream 0, msb_timestamp=0, lsb_timestamp=0) | |
423 keyframe (stream 1, msb_timestamp=0, lsb_timestamp=0) | |
424 keyframe (stream 2, msb_timestamp=0, lsb_timestamp=0) | |
425 keyframe (stream 3, msb_timestamp=0, lsb_timestamp=0) | |
426 keyframe (stream 4, msb_timestamp=0, lsb_timestamp=0) | |
427 frame (stream 0, lsb_timestamp=1) | |
428 frame (stream 0, lsb_timestamp=2) | |
429 ... | |
430 frame (stream 0, lsb_timestamp=30) | |
431 keyframe (stream 3, msb_timestamp=0, lsb_timestamp=1) | |
432 keyframe (stream 4, msb_timestamp=0, lsb_timestamp=1) | |
433 frame (stream 0, lsb_timestamp=31) | |
434 frame (stream 0, lsb_timestamp=32) | |
435 ... | |
436 frame (stream 0, lsb_timestamp=60) | |
437 frame (stream 1, lsb_timestamp=60) | |
438 frame (stream 2, lsb_timestamp=60) | |
439 keyframe (stream 3, msb_timestamp=0, lsb_timestamp=2) | |
440 keyframe (stream 4, msb_timestamp=0, lsb_timestamp=2) | |
441 frame (stream 0, lsb_timestamp=61) | |
442 frame (stream 0, lsb_timestamp=62) | |
443 ... | |
444 main header | |
445 video_stream_header (stream 0, video jpjp, timebase 30, lsb_timestamp_length=8) | |
446 codec_specific_header (stream 0) | |
447 video_stream_header (stream 1 subtitle usen, timebase 30, lsb_timestamp_length=8) | |
448 video_stream_header (stream 2 subtitle atde, timebase 30, lsb_timestamp_length=8) | |
449 audio_stream_header (stream 3, audio jpjp, timebase 1 , lsb_timestamp_length=8) | |
450 audio_stream_header (stream 4, audio usen, timebase 1 , lsb_timestamp_length=8) | |
451 frame (stream 0, lsb_timestamp=255) | |
452 frame (stream 0, msb_timestamp=1 lsb_timestamp=0) | |
453 frame (stream 0, lsb_timestamp=1) | |
454 frame (stream 0, lsb_timestamp=2) | |
455 frame (stream 1, msb_timestamp=1 lsb_timestamp=2) | |
456 frame (stream 2, msb_timestamp=1 lsb_timestamp=2) | |
457 frame (stream 0, lsb_timestamp=3) | |
458 frame (stream 0, lsb_timestamp=4) | |
459 ... | |
460 keyframe (stream 3, msb_timestamp=0, lsb_timestamp=9) | |
461 keyframe (stream 4, msb_timestamp=0, lsb_timestamp=9) | |
462 main header | |
463 video_stream_header (stream 0, video jpjp, timebase 30, lsb_timestamp_length=8) | |
464 codec_specific_header (stream 0) | |
465 video_stream_header (stream 1 subtitle usen, timebase 30, lsb_timestamp_length=8) | |
466 video_stream_header (stream 2 subtitle atde, timebase 30, lsb_timestamp_length=8) | |
467 audio_stream_header (stream 3, audio jpjp, timebase 1 , lsb_timestamp_length=8) | |
468 audio_stream_header (stream 4, audio usen, timebase 1 , lsb_timestamp_length=8) | |
469 index (stream 0) |