[NUT-devel] NUT documentation

[Oded Shimon]

On Fri, Oct 27, 2006 at 03:08:49AM -0400, Rich Felker wrote:
> Attached is my attempts so far at documenting NUT in English as
> opposed to Lingua Dei Codicis. :) I'm told that, given good

BTW, what does "Lingua Dei Codicis" mean...

> documentation on NUT, Måns is possibly willing to update the lavf
> implementation. The intent of this document is not to replace the
> formal spec that already exists, but rather for it to be developed
> into the "informative" (as opposed to normative) parts of the spec,
> particularly what one might call a "Usage" section. Rationale and
> Examples might be other non-normative sections we should consider
> writing.
> 
> So far my writing has been somewhat disorganized. I think it could
> make a much better presentation if it used more itemized lists,
> tables, etc. Actually I'd be very happy if other people want to work
> on improving this; what I've set out is just the groundwork I think.
> 
> Comments? Revisions? Frames? (Pardon my Engrish. :) Ideas for merging
> this into a nice specification document?

I personally preffer to have a normative terse spec, and an informative 
explanation document seperate, no need to merge to them...


> 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

This is actually no longer true with michael's change to the spec... 
reserved_headers needs to be checked between stream headers.

> 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.

And end-of-file.

> Simple stop conditions are provided to ensure that this search
> algorithm is bounded logarithmically in file length.

Which is... seeing a syncpoint or any nut packet...

> 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

note* that

> 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

64-bit

> [...]

I like it...
You should note vlc's, and obviously a big issue is seeking. (Give a 
simple, non-optimal implementation for seeking with and without index..)

- ods15