Author: ods15 Date: Sat Oct 28 19:35:27 2006 New Revision: 160 Added: trunk/docs/nut-english.txt Log: add nut-english.txt as stated by Rich - a very quick draft, too over-propogated and needs a major revision :) Added: trunk/docs/nut-english.txt ============================================================================== --- (empty file) +++ trunk/docs/nut-english.txt Sat Oct 28 19:35:27 2006 @@ -0,0 +1,196 @@ + + +!!! DRAFT DRAFT DRAFT !!! + +DRAFT USAGE / SEMANTICS / RATIONALE SECTIONS FOR NUT SPEC + + +Overview of NUT + +Unlike many popular containers, a NUT file can largely be viewed as a +byte stream, as opposed to having a global block structure. NUT files +consist of a sequence of packets, which can contain global headers, +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 +'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 +structure that enables a process reading the file both to verify +packet contents and to bypass uninteresting packets without having to +be aware of the specific packet type. + +In order to facilitate identification and playback of NUT files, +strict rules are imposed on the location and order of packets and +streams. Streams can be of class video, audio, subtitle, or +user-defined data. Additional classes may be added in a later version +of the NUT specification. Streams must be numbered consecutively +beginning from 0. This allows simple and compact reference to streams +in packet types where overhead must be kept to a minimum. + +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 +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 +backup headers beginning at each power-of-two byte offset in the file. +Simple stop conditions are provided to ensure that this search +algorithm is bounded logarithmically in file length. + +Metadata - Info Packets + +The NUT main header and stream headers may be followed by metadata +"info" packets, which contain (mostly textual, but other formats are +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 not that info packets may occur at +other locations in a file, particulatly 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 +that processes presenting the contents of a NUT file will make +automated responses to information stored in these packets, e.g. +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 +important that info packets be stored in the correct locations, so +that processes making automated responses to these packets can operate +correctly. + +Index + +An index packet to facilitate O(1) seek-to-time operations may follow +the headers. If an index packet does exist here, it should be placed +after info packets, rather than before. Since the contents of the +index depend on knowing the complete contents of the file, most +processes generating NUT files are not expected to store an index with +the headers. This option is merely provided for applications where it +makes sense, to allow the index to be read without any seek operations +on the underlying media when it is available. + +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 32-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 +resorting to unreliable heuristics. + +Streams + +A NUT file consists of one or more streams, intended to be presented +simultaneously in synchronization with one another. Use of streams as +independent entities is discouraged, and the nature of NUT's ordering +requirements on frames makes it highly disadvantageous to store +anything except the audio/video/subtitle/etc. components of a single +presentation together in a single NUT file. Nonlinear playback order, +scripting, and such are topics outside the scope of NUT, and should be +handled at a higher protocol layer should they be desired (for +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 +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 +object in a codec-specific format, containing global parameters for +the stream such as codebooks. Both the compression format and whatever +parameters are stored in the stream header (including NUT fields and +the opaque global header object) are constant for the duration of the +stream. + +Frames + +NUT is built on the model that video, audio, and subtitle streams all +consist of a sequence of "frames", where the specific definition of +frame is left partly to the codec, but should be roughly interpreted +as the smallest unit of data which can be decoded (not necessarily +independently; it may depend on previously-decoded frames) to a +complete presentation unit occupying an interval of time. In +particular, video frames correspond to the usual idea of a frame as a +picture that is displayed beginning at its assigned timestamp until it +is replaced by a subsequent picture with a later timestamp. Subtitle +frames should be thought of as individual subtitles in the case of +simple text-only streams, or as events that alter the presentation in +the case of more advanced subtitle formats. Audio frames are merely +intervals of samples; their length is determined by the compression +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" +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 +streams, should a subtitle format choose to make use of such a +capability. + +Central to NUT is the notion that EVERY frame has a timestamp. This +differs from other major container formats which allow timestamps to +be omitted for some or even most frames. The decision to explicitly +timestamp each frame allows for powerful high-level seeking and +editing in applications without any interaction with the codec level. +This makes it possible to develop applications which are completely +unaware of the codecs used, and allows applications which do need to +perform decoding to be more properly factored. + +Keyframes + +NUT defines a "key frame" 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 +be the targets of the seek-to-time operation. + +Representation of Time + +NUT represents all timestamps as exact integer multiples of a rational +number "time base". Files can have multiple time bases in order to +accurately represent the time units of each stream. The set of +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 +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 +to fixed-framerate 25 fps content or present it faithfully on a PAL +display. + +The scope of the media contained in a NUT file is a single contiguous +interval of time. Timestamps need not begin at zero, but they may not +jump backwards. Any large forward jump in timestamps must be +interpreted as a frame with a large presentation interval, not as a +discontinuity in the presentation. Without conditions such as these, +NUT could not guarantee correct seeking in efficient time bounds. + +Aside from provisions made for out-of-order decoding, all frames in a +NUT file must be strictly ordered by timestamp. For the purpose of +sorting frames, all timestamps are treated as rational numbers derived +from a coded integer timestamp and the associated time base, and +compared under the standard ordering on the rational numbers. + +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 +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 +than 2 bytes per frame can be achieved for single-stream files at low +bitrates. + +Syncpoints + +...