HTTPS SSH
libnogg: a decoder library for Ogg Vorbis streams
=================================================
Copyright (c) 2014-2016 Andrew Church <achurch@achurch.org>
See the file "COPYING" for conditions on use and redistribution.

Version: 1.11


Overview
--------
libnogg is a library for decoding Ogg Vorbis audio streams, written with
the aims of (1) improved code quality and robustness compared to the
reference libogg and libvorbis libraries, and (2) improved performance
compared to those libraries.

libnogg is based on the public domain stb_vorbis decoder implementation,
available as of this writing at <http://nothings.org/stb_vorbis/>.


Requirements
------------
libnogg is written in pure C99 (with some additional compiler- and
architecture-specific code used to improve performance) and should
compile with any standards-compliant compiler.  The included Makefile is
written for GNU Make and supports building on Linux and other Unix-like
systems, Mac OS X, or Windows (MinGW), using Clang, GCC, or the Intel C
compiler.


Building
--------
libnogg can be built by simply running the "make" command (or "gmake",
if GNU Make is installed under that name on your system) in the top
directory of the libnogg distribution.  This will create shared and
static library files in the top directory, which can then be installed
on the system with "make install".

Several configuration variables are available to control the build
process or specify nonstandard paths for dependent libraries.  These can
be set on the "make" command line; for example, "make ENABLE_ASSERT=1".
See the "Configuration" section at the top of the "Makefile" file for
details.


Using libnogg
-------------
The file "tools/nogg-decode.c" demonstrates how libnogg can be used to
decode audio data from an Ogg Vorbis stream.

See the documentation in include/nogg.h for further details.


Performance
-----------
The following table shows decoding performance measured by running the
nogg-benchmark tool on the files "tests/data/thingy.ogg" (monaural) and
"tests/data/sketch039.ogg" (stereo), scaled so that the time taken by
the reference decoder (libvorbis) is 1.0; thus, smaller values indicate
better performance.

                                 |    Time (monaural decode)
         Architecture (CPU)      | libvorbis | Tremor | libnogg
    -----------------------------+-----------+--------+---------
    x86_64 (Intel Core i7-4770S) |    1.000  |  1.206 |  0.546
    ARM 32-bit (TI OMAP4460)     |    1.000  |  0.700 |  0.608
    ARM 64-bit (Apple A7)        |    1.000  |  1.311 |  0.783

                                 |     Time (stereo decode)
         Architecture (CPU)      | libvorbis | Tremor | libnogg
    -----------------------------+-----------+--------+---------
    x86_64 (Intel Core i7-4770S) |    1.000  |  1.061 |  0.540
    ARM 32-bit (TI OMAP4460)     |    1.000  |  0.777 |  0.629
    ARM 64-bit (Apple A7)        |    1.000  |  1.164 |  0.609


Caveats
-------
libnogg only decodes the first Ogg bitstream found in the input data.
Interleaved and concatenated bitstreams with different bitstream IDs are
properly detected but will be ignored during decoding.

libnogg does not support lossless deletion of samples from the front of
the stream (negative initial sample position).


Reporting bugs
--------------
Please send any bug reports or suggestions directly to the author, or
report them at: <https://bitbucket.org/achurch_/libnogg/issues>