- NUT-devel - lists.mplayerhq.hu

[nut]: r602 - docs/nut-english.txt
by diego 10 Feb '08

10 Feb '08

Author: diego Date: Sun Feb 10 22:47:57 2008 New Revision: 602 Log: spelling/wording/grammar Modified: docs/nut-english.txt Modified: docs/nut-english.txt ============================================================================== --- docs/nut-english.txt (original) +++ docs/nut-english.txt Sun Feb 10 22:47:57 2008 @@ -2,7 +2,7 @@ !!! DRAFT DRAFT DRAFT !!! -DRAFT USAGE / SEMANTICS / RATIONALE SECTIONS FOR NUT SPEC +DRAFT USAGE / SEMANTICS / RATIONALE SECTIONS FOR THE NUT SPEC Overview of NUT @@ -13,7 +13,7 @@ consist of a sequence of packets, which file metadata, stream headers for the individual media streams, optional index data to accelerate seeking, and, of course, the actual encoded media frames. Aside from frames, all packets begin with a -64-bit startcode, the first byte of which is 0x4E, the ASCII character +64 bit startcode, the first byte of which is 0x4E, the ASCII character 'N'. In addition to identifying the type of packet to follow, these startcodes (combined with CRC) allow for reliable resynchronization when reading damaged or incomplete files. Packets have a common @@ -32,7 +32,7 @@ in packet types where overhead must be k Packet Structure Every NUT packet has a packet_header and a packet_footer. -The packet_header consists of a 64-bit startcode, a forward_ptr, and an +The packet_header consists of a 64 bit startcode, a forward_ptr, and an optional CRC on the packet header if the forward_ptr is larger than 4k. The forward_ptr gives the size of the packet from after the packet_header until the end of the packet_footer. The optional CRC is to prevent a @@ -46,22 +46,22 @@ the packet from after the packet_header Variable Length Coding Almost all fields in NUT are coded using VLCs. VLCs allow for compact -storage of small integers, while still being extendible to infinitely -large integers. The syntax is of a VLC is, per byte, a 1 bit flag stating +storage of small integers, while still being extensible to infinitely +large integers. The syntax of a VLC is, per byte, a 1 bit flag stating if there are more bits to the integer, and 7 bits to be prepended to the lsb of the integer, shifting the previous value to the left. Stuffing is allowed in VLCs by adding 0x80 bytes before the actual value, but a maximum of 8 bytes of stuffing is allowed in any VLC outside of a NUT packet. The only such fields are forward_ptr and fields in frame -headers. This is to prevent demuxers from looping on a large of amount of -damaged bytes of 0x80. Fields inside a NUT packet are protected by a CRC +headers. This is to prevent demuxers from looping on a large amount of +damaged 0x80 bytes. Fields inside a NUT packet are protected by a CRC which can be checked before decoding. Header Structure A NUT file must begin with a magic identification string, followed by the main header and a stream header for each stream, ordered by stream -id. No other packets may intervene between these header packets. For +ID. No other packets may intervene between these header packets. For robustness, a NUT file needs to include backup copies of the headers. In the absence of valid headers at the beginning of the file, processes attempting to read a NUT file are recommended to search for @@ -70,7 +70,7 @@ and before end of file. Simple stop conditions are provided to ensure that this search algorithm is bounded logarithmically in file length. This stop condition is finding any valid NUT packet (such as a syncpoint) during the search, -as no packets are allowed between a search start until a reapeted header +as no packets are allowed between a search start until a repeated header set. Metadata - Info Packets @@ -80,7 +80,7 @@ The NUT main header and stream headers m possible) information on the file, on particular streams, or on particular time intervals ("chapters") of the file, such as: title, author, language, etc. One should note that info packets may occur at -other locations in a file, particulatly in a file that is being +other locations in a file, particularly in a file that is being generated/transmitted in real time; however, a process interpreting a NUT file should not make any attempt to search for info packets except in their usual location, i.e. following the headers. It is intended @@ -89,8 +89,8 @@ automated responses to information store selecting a subtitle language based on the user's preferred list of languages, or providing a visual list of chapters to the user. Therefore, the format of info packets and the data they are to contain -has been carefully specified and is aligned with International -Standards for language codes and so forth. For this reason it is also +has been carefully specified and is aligned with international +standards for language codes and so forth. For this reason it is also important that info packets be stored in the correct locations, so that processes making automated responses to these packets can operate correctly. @@ -108,7 +108,7 @@ on the underlying media when it is avail On the other hand, all NUT files except live streams (which have no concept of "end of file") must include an index at the end of the -file, followed by a fixed-size 64-bit integer that is an offset +file, followed by a fixed-size 64 bit integer that is an offset backwards from end-of-file at which the final index packet begins. This is the only fixed-size field specified by NUT, and makes it possible to locate an index stored at the end of the file without @@ -127,7 +127,7 @@ handled at a higher protocol layer shoul example, using several NUT files with an external script file to control their playback in combination). -With each stream, a single media encoding format is associated. The +A single media encoding format is associated with each stream. The stream headers convey properties of the encoding, such as video frame dimensions, sample rates, and the compression standard ("codec") used (if any). Stream headers may also carry with them an opaque, binary @@ -139,7 +139,7 @@ stream. Each stream has a last_pts context. For compression, every frame's pts is coded relatively to the last_pts. In order for demuxing to resume -from arbitrary points in the file, all last_pts contexes are reset by +from arbitrary points in the file, all last_pts contexts are reset by syncpoints. Frames @@ -160,8 +160,8 @@ intervals of samples; their length is de format used. Frames need not be decoded in their presentation order. NUT allows for -arbitrary out-of-order frame systems, from classic MPEG-1-style B -frames to H.264 B pyramid and beyond, using a simple notion of "delay" +arbitrary out-of-order frame systems, from classic MPEG-1-style +B-frames to H.264 B-pyramid and beyond, using a simple notion of "delay" and an implicitly-determined "decode timestamp" (dts). Out-of-order decoding is not limited to video streams; it is available to audio streams as well, and, given the right conditions, even subtitle @@ -179,14 +179,14 @@ perform decoding to be more properly fac Keyframes -NUT defines a "key frame" as any frame such that the frame itself and +NUT defines a "keyframe" as any frame such that the frame itself and all subsequent (with regard to presentation time) frames of the stream can be decoded successfully without reference to prior (with regard to storage/decoding order) frames in the stream. This definition may sometimes be bent on a per-codec basis, particularly with audio formats where there is MDCT window overlap or similar. -The concept of key frames is central to seeking, and key frames will +The concept of keyframes is central to seeking, and keyframes will be the targets of the seek-to-time operation. Representation of Time @@ -197,7 +197,7 @@ accurately represent the time units of e available time bases is defined in the main header, while each stream header indicates which time base the corresponding stream will use. -Effective use of time bases both allows for compact representation of +Effective use of time bases allows for compact representation of timestamps, minimizing overhead, and enriches the information contained in the file. For example, a process interpreting a NUT file with a video time base of 1/25 second knows it can convert the video @@ -221,7 +221,7 @@ Frame Coding Each frame begins with a "framecode", a single byte which indexes a table in the main header. This table can associate properties such as -stream id, size, relative timestamp, keyframe flag, etc. with the +stream ID, size, relative timestamp, keyframe flag, etc. with the frame that follows, or allow the values to be explicitly coded following the framecode byte. By careful construction of the framecode table in the main header, an average overhead of significantly less @@ -229,17 +229,17 @@ than 2 bytes per frame can be achieved f bitrates. Framecodes can also be flagged as invalid, and seeing such a framecode indicates a damaged file. The frame code 0x4E ('N') is a special invalid -framecode which marks that the next packet is a NUT packet, and not a -frame. The following 7 bytes, combined with 'N', is the full startcode of +framecode which marks the next packet as a NUT packet, and not a frame. +The following 7 bytes, combined with 'N', are the full startcode of the NUT packet. Syncpoints -Syncpoints are mini-NUT packets, which serve for seeking, error recovery, +Syncpoints are mini NUT packets, which serve for seeking, error recovery and error checking. They contain a startcode like all NUT packets, a timestamp, a back_ptr, and a CRC on the packet itself. Syncpoints must be placed every 32kb (or whatever max_distance is set to in the main header, -64kb at most), unless between the 2 syncpoints is a single frame. +64kb at most), unless a single frame is between the 2 syncpoints. Syncpoints must be followed by a frame, and must be placed after headers (except those at end of file). The timestamp coded in the syncpoint is a global timestamp, which is used @@ -257,9 +257,9 @@ syncpoint is 16 bytes: End of Relevance EOR is a flag that can be attributed to a frame in any stream, and marks -the end of relavence of a stream on presentation, such as a subtitle +the end of relevance of a stream on presentation, such as a subtitle stream currently showing no subtitles on screen. EOR flag can only be -given to zero byte frames, and must be set as keyframe as well. Once EOR +given to zero byte frames, and must be set as keyframe. Once EOR is seen on such a stream, the stream is set EOR until the next keyframe on that stream. Streams which are set EOR are ignored by back_ptr in syncpoints until EOR is unset. The significance of EOR is to set the @@ -269,7 +269,7 @@ begin demuxing. Error Checking There are several ways to detect a damaged stream in NUT during demuxing: -1. Invalid framecode - If a framecode which has been marked as invalid in +1. Invalid framecode: If a framecode which has been marked as invalid in the main header is found as the framecode in a frame header, then the stream is damaged. For this reason, 0x00 and 0xFF are recommended to be set as invalid frame codes in NUT. @@ -284,7 +284,7 @@ There are several ways to detect a damag 6. A VLC is found with more than 8 bytes of stuffing in a frame header or forward_ptr. 7. Streams are found to not be strictly interleaved by comparing dts and - pts - a precise formula for this check can be found in the spec. + pts. A precise formula for this check can be found in the specification. All these conditions make it impossible for a demuxer to read, skip or buffer a large amount of data from a file because of damaged data. Also @@ -301,5 +301,5 @@ case a syncpoint was already skipped due Seeking -An in depth explanation of an optimal seeking algorithm can be found in +An in depth explanation of an optimal seeking algorithm can be found at http://wiki.multimedia.cx/index.php?title=NUT

1 0

[nut]: r601 - docs/nutissues.txt
by diego 10 Feb '08

10 Feb '08

Author: diego Date: Sun Feb 10 20:49:49 2008 New Revision: 601 Log: spelling/wording/grammar Modified: docs/nutissues.txt Modified: docs/nutissues.txt ============================================================================== --- docs/nutissues.txt (original) +++ docs/nutissues.txt Sun Feb 10 20:49:49 2008 @@ -6,8 +6,8 @@ in the decoder. Issue broadcast-preload-len --------------------------- -Problem: How long should the receiver preload the nut file before starting -playback and after seeking, so no buffer over/underflows happens. +Problem: How long should the receiver preload the NUT file before starting +playback and after seeking, so no buffer over/underflow happens. Solutions to the above 2 issues are for example storing one of the following A. preload time @@ -16,9 +16,9 @@ C. buffer fullness in seconds D. buffer fullness in bytes E. transmit time stamps -Values in bytes scale nicer with increased bandwidth, that is doubling the -bandwidth from the one assumed by the muxer halfs the needed preload. Time -based sync values dont naturally change the needed preload with increased +Values in bytes scale nicer with increased bandwidth, that is, doubling the +bandwidth from the one assumed by the muxer halves the needed preload. Time +based sync values do not naturally change the needed preload with increased bandwidth but instead increase the needed buffer size. These can be stored in one of the following @@ -33,22 +33,22 @@ without that being changed. Issue chapter-overlap/gap ------------------------- If one changes the timebase between chapters then overlaps (forbidden by the -spec) or gaps (problematic with split&merge) can happen. +spec) or gaps (problematic with split & merge) can happen. Solutions: -A. dont change the timebase -B. store start and end in seperate timebases (breaks compatibility) -C. add a field into the info packet overriding the chapter_end with a +A. Do not change the timebase. +B. Store start and end in separate timebases (breaks compatibility). +C. Add a field into the info packet overriding the chapter_end with a more accurate value. -D. use the chapter start of the next chapter (breaks compatibility and - error robustness) +D. Use the chapter start of the next chapter (breaks compatibility and + error robustness). -It seems the consensus is A +It seems the consensus is A. Issue stream-chapter-overlap ---------------------------- -It is possible especially in the light of the precission of the previous +It is possible especially in the light of the precision of the previous issue, that chapters might not end exactly at the same points in time in all streams. There could be a few samples difference. Do we care about this? @@ -63,47 +63,47 @@ duplicated for each stream it applies to Issue multiple-programs ----------------------- Multiple programs (that is several audio-video stream pairs for example) can -not be stored cleanly in nut. +not be stored cleanly in NUT. Solutions: A. one backptr per program + any solution for issue info-stream-subsets -B. Design a seperate layer for it -C. Dont support this +B. Design a separate layer for it. +C. Do not support this. Issue info-overhead ------------------- Info can be stored much more compactly by replacing common strings by -shorter represenstations. +shorter representations. Solutions: A. Change syntax so a v value which indexes into a fixed table can select info names. (breaks compatibility completely) B. Use/allow 1 char abbreviations (new demuxers could read old files, old - ones could read everything except the abbreviated fields) + ones could read everything except the abbreviated fields). C. Leave info as it is. Issue edit-lists ---------------- -For editing its very usefull to not rewrite the whole file after every step. +For editing it is very useful to not rewrite the whole file after every step. Solutions: -A. Store such edits in info packets -B. Store such edits in info packets but allow them only in "private" nut +A. Store such edits in info packets. +B. Store such edits in info packets but allow them only in "private" NUT files. That is files distributed must be remuxed. Players must reject files with edit lists. -C. Dont support this (this would mean no interoperability between video - editing programs using nut as they would use their own formats to store - edit lists) +C. Do not support this (this would mean no interoperability between video + editing programs using NUT as they would use their own formats to store + edit lists). Issue alternatives ------------------ Alternatives like a variant without some scenes or with a happy ending -instead of a tragic one cannot be stored in nut currently. +instead of a tragic one cannot be stored in NUT currently. Solutions: -A. Store such alterative play lists of scenes in info packets somehow -B. Design a seperate layer for it -C. Dont support this +A. Store such alternative playlists of scenes in info packets somehow. +B. Design a separate layer for it. +C. Do not support this.

1 0

[nut]: r600 - docs/nutissues.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 20:21:03 2008 New Revision: 600 Log: more cosmetics Modified: docs/nutissues.txt Modified: docs/nutissues.txt ============================================================================== --- docs/nutissues.txt (original) +++ docs/nutissues.txt Sun Feb 10 20:21:03 2008 @@ -17,7 +17,7 @@ D. buffer fullness in bytes E. transmit time stamps Values in bytes scale nicer with increased bandwidth, that is doubling the -bandwidth from the one assumed by the muxer halfs the needed preload. time +bandwidth from the one assumed by the muxer halfs the needed preload. Time based sync values dont naturally change the needed preload with increased bandwidth but instead increase the needed buffer size. @@ -36,12 +36,12 @@ If one changes the timebase between chap spec) or gaps (problematic with split&merge) can happen. Solutions: -A dont change the timebase -B store start and end in seperate timebases (breaks compatibility) -C add a field into the info packet overriding the chapter_end with a - more accurate value. -D use the chapter start of the next chapter (breaks compatibility and - error robustness) +A. dont change the timebase +B. store start and end in seperate timebases (breaks compatibility) +C. add a field into the info packet overriding the chapter_end with a + more accurate value. +D. use the chapter start of the next chapter (breaks compatibility and + error robustness) It seems the consensus is A

1 0

[nut]: r599 - docs/nutissues.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 20:18:12 2008 New Revision: 599 Log: little cosmetic cleanup Modified: docs/nutissues.txt Modified: docs/nutissues.txt ============================================================================== --- docs/nutissues.txt (original) +++ docs/nutissues.txt Sun Feb 10 20:18:12 2008 @@ -1,11 +1,11 @@ Issue broadcast-clock-sync ----------------- +-------------------------- Problem: Clock synchronization leading to buffer overflow and underflow in the decoder. Issue broadcast-preload-len ----------------- +--------------------------- Problem: How long should the receiver preload the nut file before starting playback and after seeking, so no buffer over/underflows happens. @@ -35,7 +35,7 @@ Issue chapter-overlap/gap If one changes the timebase between chapters then overlaps (forbidden by the spec) or gaps (problematic with split&merge) can happen. -Solutions +Solutions: A dont change the timebase B store start and end in seperate timebases (breaks compatibility) C add a field into the info packet overriding the chapter_end with a @@ -76,6 +76,7 @@ Issue info-overhead Info can be stored much more compactly by replacing common strings by shorter represenstations. +Solutions: A. Change syntax so a v value which indexes into a fixed table can select info names. (breaks compatibility completely) B. Use/allow 1 char abbreviations (new demuxers could read old files, old @@ -87,7 +88,7 @@ Issue edit-lists ---------------- For editing its very usefull to not rewrite the whole file after every step. -Solutions. +Solutions: A. Store such edits in info packets B. Store such edits in info packets but allow them only in "private" nut files. That is files distributed must be remuxed. Players must reject @@ -102,7 +103,7 @@ Issue alternatives Alternatives like a variant without some scenes or with a happy ending instead of a tragic one cannot be stored in nut currently. -Solutions +Solutions: A. Store such alterative play lists of scenes in info packets somehow B. Design a seperate layer for it C. Dont support this

1 0

[nut] [propchange]: r595 - svn:log
by diego 10 Feb '08

10 Feb '08

Author: diego Revision: 595 Property Name: svn:log Action: modified Property diff: --- old property value +++ new property value @@ -1,2 +1,2 @@ -Fix very bad wording. The original would have if taken litterally made +Fix very bad wording. The original would have if taken literally made it impossible to store any chapters.

1 0

[nut] [propchange]: r598 - svn:log
by diego 10 Feb '08

10 Feb '08

Author: diego Revision: 598 Property Name: svn:log Action: modified Property diff: --- old property value +++ new property value @@ -1 +1 @@ -clearer sentance +clearer sentence

1 0

[nut]: r598 - docs/nutissues.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 17:03:59 2008 New Revision: 598 Log: clearer sentance Modified: docs/nutissues.txt Modified: docs/nutissues.txt ============================================================================== --- docs/nutissues.txt (original) +++ docs/nutissues.txt Sun Feb 10 17:03:59 2008 @@ -93,7 +93,8 @@ B. Store such edits in info packets but files. That is files distributed must be remuxed. Players must reject files with edit lists. C. Dont support this (this would mean no interoperability between video - editing programs using nut as they would use their own formats) + editing programs using nut as they would use their own formats to store + edit lists) Issue alternatives

1 0

[nut]: r597 - docs/nutissues.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 16:16:26 2008 New Revision: 597 Log: chapter-overlap/gap consensus? Modified: docs/nutissues.txt Modified: docs/nutissues.txt ============================================================================== --- docs/nutissues.txt (original) +++ docs/nutissues.txt Sun Feb 10 16:16:26 2008 @@ -43,6 +43,8 @@ C add a field into the info packet overr D use the chapter start of the next chapter (breaks compatibility and error robustness) +It seems the consensus is A + Issue stream-chapter-overlap ----------------------------

1 0

[nut]: r596 - docs/nut.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 14:44:13 2008 New Revision: 596 Log: Same timebase for info packets suggestion. Modified: docs/nut.txt Modified: docs/nut.txt ============================================================================== --- docs/nut.txt (original) +++ docs/nut.txt Sun Feb 10 14:44:13 2008 @@ -828,6 +828,8 @@ chapter_id (s) chapter_start (t) timestamp of start of chapter + 2 info packets which apply to the same subset of streams SHOULD use the + same timebase. chapter_len (v) Length of chapter in the same timebase as chapter_start.

1 0

[nut]: r595 - docs/nut.txt
by michael 10 Feb '08

10 Feb '08

Author: michael Date: Sun Feb 10 14:36:55 2008 New Revision: 595 Log: Fix very bad wording. The original would have if taken litterally made it impossible to store any chapters. Modified: docs/nut.txt Modified: docs/nut.txt ============================================================================== --- docs/nut.txt (original) +++ docs/nut.txt Sun Feb 10 14:36:55 2008 @@ -814,8 +814,8 @@ Info tags: ---------- stream_id_plus1 (v) - Stream this info packet applies to. If zero, packet applies to the - whole file. + Stream this info packet applies to. If zero, packet applies to all + streams. chapter_id (s) The ID of the chapter this packet applies to. If zero, the packet applies

1 0