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