Short:        Ogg Opus decoder shared library
Author:       Xiph.Org Foundation (libopus/libogg/opusfile), Mattias Muench (Port)
Uploader:     opusfile amigaworld de (Matthias Muench)
Type:         util/libs
Version:      1.0
Requires:     AmigaOS 3.0+ (exec/dos V39), 68000 or better, no FPU
Architecture: m68k-amigaos >= 3.0.0
Distribution: Aminet

opusfile.library 1.0
====================

Plays Ogg Opus (.opus) files on classic AmigaOS. libopus 1.6.1 (decoder,
fixed point), libogg 1.3.6 and opusfile (master 2026-03-28) are linked
into one shared library that exports

  * the opusfile API: open files, memory blocks or your own streams
    (web radio), read 16-bit PCM, seek, tags, chained streams,
    ReplayGain-style gain, album art tag parsing
  * the raw libopus decoder API, single stream and multistream
    (5.1 / 7.1), for applications that do their own container parsing

74 functions. Output is always 48 kHz, 16-bit signed, big endian.

  * no FPU needed (integer-only codec)
  * no ixemul, no other libraries, no C library in the application
    required - only exec.library and dos.library
  * reentrant, any number of tasks may decode at the same time
  * brings its own decoding stack: the caller's 4 KB default stack is fine
  * one build per CPU: 68000, 68020, 68030, 68040, 68060
  * the 68020/030/040 builds use the 32x32->64 bit muls.l and have the
    FFT butterflies in assembly; their output is bit-identical to a
    64-bit PC build of libopus


Installation
------------

Copy the library for your CPU to LIBS:

  CPU                              copy
  68000 / 68010                    Libs/68000/opusfile.library
  68020 / 68030                    Libs/68020/opusfile.library
  68040                            Libs/68040/opusfile.library
  68060                            Libs/68060/opusfile.library
  68080 (Vampire)                  Libs/68040/opusfile.library

for example

  Copy opusfile/Libs/68040/opusfile.library LIBS:

Do not use the 68040 build on a 68060: the 060 does not implement the
64-bit muls.l and would trap into 68060.library on every multiply.


Tools (68020+)
--------------

  C/opus2raw file.opus [out.raw]
      Shows stream information and tags; with a second argument decodes
      to raw 16-bit big-endian stereo PCM, 48 kHz.

  C/opbench file.opus [out.raw]
      Decodes the file from memory and reports the speed as a real-time
      factor.


Speed
-----

Measured on a 68080 (Vampire A1200, Kickstart 3.2), 68040 build:

  CELT stereo 128 kbit/s       1.60x real time
  CELT mono 64 kbit/s          2.75x
  SILK (speech) 12 kbit/s      5.58x
  Hybrid stereo 40 kbit/s      2.02x
  5.1 surround 256 kbit/s      0.53x

Real 68020-68060 CPUs have not been measured. At their clock rates they
will not decode 48 kHz stereo music in real time; speech and low-rate
mono streams are more realistic there.


For programmers
---------------

SDK/ contains the include files (proto, clib, GCC inline, fd, lvo), the
SFD and the original opusfile.h/opus.h headers with
their documentation.

  #include <proto/exec.h>
  #include <proto/opusfile.h>

  struct Library *OpusFileBase = OpenLibrary("opusfile.library", 1);
  OggOpusFile *of = op_open_file("music.opus", &err);
  while ((n = op_read_stereo(of, pcm, 11520)) > 0) { ... }
  op_free(of);
  CloseLibrary(OpusFileBase);

Differences from the original API:

  * 64-bit values (op_pcm_total, op_pcm_seek, ...) are exported as _ptr
    functions; <libraries/opusfile_compat.h> maps the original names, so
    source code does not change
  * opus_decoder_ctl()/opus_multistream_decoder_ctl() are exported as
    ...ctlA(); the compat header maps the usual OPUS_SET_xxx() calls
  * op_fopen() reads through dos.library and returns an opaque stream
  * not available: op_fdopen, op_freopen, the URL/HTTP functions (do the
    networking yourself and use op_open_callbacks()), the float API, the
    encoder
  * callbacks (OpusFileCallbacks, decode callback) use the C calling
    convention with arguments on the stack; small-data programs must
    declare them __saveds, register-argument programs __stdargs

README.md has the details: callbacks and stacks, tasks vs. processes,
resource use, how the library was built and tested.

SDK/examples contains the sources of opus2raw and opbench.


Tested
------

  * A1200 with Vampire 68080, Kickstart 3.2 (47.13): 68020, 68040 and
    68060 builds load and expunge cleanly; six stream types incl. 5.1;
    tags; called with a 4 KB stack; two decoders in parallel; no memory
    leaks
  * Vampire V4 Standalone, 68080, Kickstart 3.2: 68040 build
  * decoder output compared bit by bit against PC builds of libopus

Not yet tested on real 68000-68060 hardware, with the 68000/68030 builds,
or on Kickstart 3.0/3.1.
Reports welcome.


History
-------

1.0 (11.10.2026)  first release


License
-------

3-clause BSD, see COPYING (libopus, libogg, opusfile (c) Xiph.Org
Foundation and contributors; Amiga glue (c) 2026 Matthias Muench).