GARbro-mirror/packages/NVorbis.0.8.4.0/README

NVorbis
-------

NVorbis is a .Net library for decoding Xiph.org Vorbis files.  It is purely
managed code, and should run correctly in partial-trust environments.

This implementation is based on the Vorbis specification found on xiph.org.
The MDCT and Huffman codeword generator were borrowed from public domain
implementations at http://nothings.org/stb_vorbis/.

Currently the only container supported is Xiph.org Ogg.  Matroska and RTP
are planned.

To use:

- Create an instance of NVorbis.VorbisReader (pass the Ogg Vorbis filename in)
- Use these properties to gather data about the logical stream:
    - Channels
    - SampleRate
    - TotalTime		- A TimeSpan indicating the total length of the audio data
    - DecodedTime	- A TimeSpan indicating the last returned sample's timestamp
    - NominalBitrate, UpperBitrate, and LowerBitrate
        - These are the encoder's reported bitrates
    - Vendor	- The encoder's vendor string
    - Comments	- An array of comments in the file (usually tags)
- Call "int ReadSamples(float[], int, int)" to retrieve the next batch of
  samples.  It will return 0 when the logical Vorbis stream is done.


- For NAudio support:
    - Reference NVorbis.NAudioSupport.dll
    - Create an instance of NVorbis.NAudioSupport.VorbisWaveReader
    - VorbisWaveReader implements NAudio.Wave.WaveStream.

History
-------
0.1	- 08/03/2012
    * Initial Release
0.2 - 08/07/2012
    * Swapped out LGPL code for public domain implementations
    * Relicensed under Ms-PL
    * Added NAudio support project
    * Added test files & app
    * Performance improvements
0.3 - 08/08/2012
    * Fixed Page / Packet decode (packets overlapping 2 pages)
    * Fixed "no energy" packet handling
    * Fixed packet reader not merging when unsolicited packets are added
    * Added .gitignore
    * Added initial multi-stream support
    * Added statistics (see VorbisReader.Stats)
0.4 - 08/14/2012
    * Refactoring to clean up code and make room for later improvements
    * Changed lapping algorithm to be simpler
    * Switched to higher-performance clipping algorithm
    * Some cleanup
0.4.1 - 09/11/2012
    * Fixed a couple Ogg container bugs
    * Optimized memory allocations for better performance / memory usage
0.5 - 09/20/2012
    * Added seeking support
    * Changed OggPacketReader to use a doubly-linked list for the packet queue / history
    * Changed OggPacketReader.GetTotalPageCount() to count pages directly instead of making .AddPacket(...) keep a list
    * Fixed a few bugs (mostly race conditions in multi-threaded playback scenarios)
    * Added multi-stream support to VorbisWaveReader
    * Added several info properties to VorbisWaveReader
0.5.5 - 11/15/2012
    * Added OpenTK support
    * Added makefiles for Mono
    * Added constructor to NAudioSupport for already opened Stream instances
    * Made Ogg container logic thread-safe
    * Cleanup & Optimization
0.6.0 - 06/27/2013
    * Remove ACache from project
    * Make clipping optional (default: on)
    * Set clipping to clamp at +/-.99999994 instead of +/-1 as a courtesy to those not outputing float samples
    * Performance improvements for RingBuffer
    * Performance improvements in ThreadSafeStream
0.7.0 - 07/15/2013
    * Rewrite Ogg Reader buffering logic to vastly improve memory usage
    * Reorganize to more easily support other container types / work with other Ogg stream decoders
    * Exposed Ogg reading types
    * Performance improvements
    * Bugfix: Don't throw on Vorbis streams that only have a single mode
0.7.1 - 07/18/2013
    * Removed use of generics & lambda from Huffman decoder
    * Reduced computation by only processing samples that are required for output
    * Bugfix: Seeking now works again
    * Bugfix: OpenTKSupport.OggStream now only queues as many source buffers as it filled
0.7.2 - 07/22/2013
    * Bugfix: Floor 0 implementation is now correct
    * Bugfix: Residue 0 & 1 implementation is now correct
    * Bugfix: Seeking back less than the current buffer size no longer corrupts the read buffer
0.7.3 - 08/02/2013
    * Bugfix: Fix residue 1
0.7.4 - 09/16/2013
    * Bugfix: Some stereo files with sound on only one channel decoded noise on the silent channel.
0.8.0test1 - 09/16/2013
    * Rebuilt container reading infrastructure so it is properly decoupled from the decoder
    * Added unit tests for the packet reader, Ogg container reader
0.8.0 - 01/16/2014
    * Minor bugfixing to test1
    * Replaces 0.7.4 as recommended release
0.8.1 - 02/24/2014
    * Bugfix: Threading issues in Ogg reader
    * Rewrite StreamReadBuffer (again) for simplicity and correctness
    * Add "saved buffer" concept to StreamReadBuffer for multi-threaded performance
    * Reduce Ogg reader memory usage
    * Add locking for multi-threading support in Ogg reader
    * Remove exception-based logic where possible for better performance
0.8.2 - 03/19/2014
    * BugFix: Don't try to copy StreamReadBuffer data when offset is bigger than source
    * Add parameter change event to packet provider interface
    * Refactored decoder setup so parameter change can be handled
    * Rewrote packet peek / get logic for simplicity
    * Refactored locking in OggPacketReader / OggContainerReader
    * Improved Ogg end of stream handling
    * Changed container seek API to use packets instead of indexes to reduce linked list traversals
0.8.3 - 04/29/2014
    * BugFix: Don't set the end of stream flag until the last packet of the page