OAS Audio Core Playback Engine 
------------------------------

Release History:
----------------

0.00: Early sample release [CH Only]

0.10: Initial release (OAS Playout v2.0, A1)
- fix SEEK capability
- added MP3 codec error checks & notification

0.20: Bug fix update (OAS Playout v2.0, B1)
- fix VBR support
- export OASAudioGetMP3TrackLength 
- fix spurious dsound latency on track start (task switch)
- correct volume conversions from % to db (for dsound)

0.30: Bug fix update (OAS Playout v2.0, various betas)
- if a decoder failure occured, the API posted back a state
message of 'OAS_PLAYER_STATE_EOS' to terminate the stream
instead of 'OAS_ERROR_CODEC_FAILURE'. With this release if a
decode failure does occur, it attempts to re-sync to the next
valid frame and resume. If no valid frame is detected, 
EOS is posted as before. No error message is ever posted since
the failure may be caused by valid non-MPEG data such as ID3v1
tags or LYRICS tags at the end of the file.
- during testing of OAS Playout it was possible to force a
playback buffer into an endless loop requiring package shutdown
to resolve. This is believed to be due to a logic problem occuring
with the handling of the 'OAS_MSG_CMD_OUTPUT_DRAIN' message a
fix has been applied.
- If all DirectSound instances are closed & then re-opened the
initialisation will fail internally causing a GP fault & program
crash.

0.40: Functional & bug fix update:
- Added msg OAS_MSG_CMD_INPUT_CLOSE to force input file stream to
be closed. Playback is automatically stopped.
- Added msg OAS_MSG_CMD_SET_DURATION to force the stream duration
to a known value (a OAS_MSG_NTFY_STREAM_DURATION is then echoed 
back). This will support future implementations where VBR is handled
properly.
- Added msg OAS_MSG_CMD_SET_INPUT_TIME_INTERVAL to set interval at 
which OAS_MSG_NTFY_INPUT_TIME are generated
- OAS_MSG_CMD_OUTPUT_RESET msg improved to stop playback buffer as well
as clearing the buffer.
- correct rounding error in OAS_MSG_NTFY_INPUT_POSN processing
- added exception handler around mpglib decoder (inside DLL) to catch
fatal decoder failures

0.41: minor bug fix update (shipped with OAS Playout V2.0)
- post STOP message when 'OASAudioPlayerDestroy' called to ensure threads
close cleanly (possibility of GP fault if track playing when Destroy called)
- GP fault raised if output modules changed during playback.

0.50: minor functional update (shipped with OAS Playout v2.3)
- validate supported channels on Open command, flag error if not supported
(prior versions would play mono at double speed)
- Added new operation OASAudioGetMP3TrackInfo to return info on MP3 file
(bitrate, sample rate etc.) but only for supported playback formats

0.60: functional update
- support for PCM/WAV format (experimental)
- tighten checks on supported file formats, will generate error responses
on all unsupported formats
- new IO buffering engine implemented to minimize risk of 'stuttering' 
caused by slow/erratic file reads - engine can now provide up to 10s pre
buffered audio to deal with drop outs/network glitches.

0.70: functional & bug fix update (shipped with OAS Playout v2.4)
- support for OGG/Vorbis (.ogg) format (experimental) via optional OGG/Vorbis
support DLLs (not included)
- IO buffering engine (in 0.60) does not recover well if MP3 stream encounters
a decoding error, often track will terminate playback immediately. Note this
only manifests itself if track is corrupt in some way
- improved capability for detecting VBR files & correctly calculating track
length, also provides more accurate seeks on these files
- logic change: track length will only be fully re-calculated (including
VBR detect & scan) if the 'TrackLength' param passed to 'OASAudioGetMP3TrackInfo'
is set to zero. If it is non-zero, it is assumed the length is already correctly
calculated by some other means, this is for performance reasons.
- logic change: a OAS_MSG_CMD_SET_DURATION message will no longer generate
a OAS_MSG_NTFY_STREAM_DURATION return. If required, this will need to be
posted manually
- bug fix: 'OASAudioGetMP3TrackLength' did not work for PCM/WAV format files.
- bug fix: 'OASAudioGetMP3TrackInfo ' returns corrupt bit rate
- bug fix: 'OASAudioPlayerDestroy' can deadlock if player is created but
never actually used (only since 0.60).
- bug fix: MPGLIB can terminate  unexpectedly if a corrupt MPEG stream is 
detected. 

0.71: functional update
- add support for Fraunhofer-IIS VBRI style headers

0.72: bug fix & functional update (shipped with OAS Playout v2.5)
- memory leak, dsound secondary buffers never released
- add exception handler to audio thread, post OAS_MSG_NTFY_ERROR on exception
- new command OAS_MSG_CMD_SET_OUTPUT_FREQUENCY 

0.73: bug fix (shipped with OAS Playout v2.6)
- potential deadlock if STOP command is issued as it enters EOS state on
directsound outputs.

0.74: functional update
- experimental support for mono format (stock 44khz)

0.80: functional update
- remove mono format handling
- optimise file start parsing (skip ID3 header)
- add support for AAC/Mp4 via FAAD2 decoder

0.81: functional update
- add experimental support for Windows Media (WMA)
- exception handlers for new decoders

0.82: functional/bug fix (shipped with OAS Playout v2.61+)
- ID3 header skip not working correctly (may try & play header)
- Correctly detect WMA VBR files
- Add exports for WMA metadata

0.83: bug fix
- fix handling of partial Xing VBR headers

0.84: bug fix & functional update (shipped with Playout v3, Beta 1)
- fix handling of additional data tacked on PCM/WAV files
(stops playback of this non-audio data)
- new routine: 'OASAudioFormatErrorString' to generate
textual error message from error codes.

0.85: bug fix (shipped with OAS Playout v3.0,3.01)
- bug fix: Crash if 'OASAudioEnumerateDevices' is called before a
player instance is instantiated. 

0.86: bug fix
- MP4/AAC seek inaccurate (also requires updated mp4lib DLL to fix)

0.87: bug fix (shipped with OAS Playout v3.03)
- fix memory leak in MP4/AAC core
- mod to fix a possible race hazzard in the async IO MP3 reader,
under rare (slow data retrieval conditions) could lead to abortive
EOS flagged.

0.88: bug fix (shipped with OAS Playout v3.04)
- wait for async-io to finish any outstanding file reads before
closing file handle

0.90: functional update
- add support for any audio sample rate (remove 44khz limitation)
- add support for mono file formats
- add exception handlers & dispatch routines to child threads

0.91: bug fix (shipped with OAS Playout v3.06)
- handle MP3, MPEG V2.5 format (needed for lower sample rates)
- bug fix: PCM/WAV & MP3 formats do not play at low sample rates
- bug fix: v.short MP3 files may not calculate length correctly
- bug fix: SW could try and re-configure a 'playing' dsound 
buffer for a new format causing core exception

0.92: functional update (shipped with OAS Playout v3.07,3.08)
- support aacPlus (AAC HE) playback (with suitably built codec)
- report correct track length for aacPlus

0.93: minor update (shipped with OAS Playout v3.09)
- reject SEEK commands if currently playing
- add additional (optional) callback for output modules
- bug fix: aac file (raw, not m4a) will not play with ID3v2
tags present
- bug fix: aac (raw) track length not calc'd correctly through
OASAudioGetMP3TrackLength

0.94: functional update/bug fix (shipped with OAS Playout v3.1)
- improve exception & error handling in DS core, AIO core
- bug fix: remove STOP message posted during SEEK (added in 0.93)
causes playback to abort prior to EOS completing
- add timeout checks in DS core & AIO core in case of system error
- bug fix: DX output can 'skip' audio
- OAS_MSG_CMD_SET_OUTPUT_FREQUENCY now supplied as a ratio and
preserved across sample format changes

0.95: functional update (shipped with OAS Playout v3.2)
- new message OAS_MSG_CMD_OUTPUT_CLOSE
- FLAC file support (experimental)
- new messages OAS_MSG_CMD_SET_MAIN_VOLUME, OAS_MSG_CMD_GET_MAIN_VOLUME,
OAS_MSG_NTFY_MAIN_VOLUME for manipulating sound card volume levels
- OAS_ERROR_PRELOAD_NOT_DSOUND renamed OAS_ERROR_NOT_DSOUND
- update some 64bit int/double conversions with true 64bit maths (flac,wma).
- bug fix: wma seek not working properly for long tracks (>~7mins)

0.96: bug fix update (shipped with OAS Playout v3.3x)
- bug fix: FLAC files will not seek properly if count of samples >2^32.
- bug fix: Remove 2GB file limit on .wav files (now handles up to 4GB)
- support for wav64 format.
- optional support for using 'libsndfile' for decoding various audio formats
- VBR flag always set when processing MP4 container files
- Fix race hazzard conditions on waiting for thread terminations
- Thread safe mpglib
- calibrate volume levels correctly in DX
- look for "libvorbisfile.dll" as well as "vorbisfile.dll" in line with
newer Xiph naming conventions
- internal code changes on processing WMA attributes (for Playout)
- bug fix: Potential thread lockup/crash if a "stop" message is
processed in the 1s window after EOS is posted to the dsound module

0.97: minor bux fix update (shipped with OAS Playout v3.4)
- include more error checks on dsound layer & flow errors up to application
layer
- subtle logic change when using libsnd, if this fails to handle the file
it's now passed to the MP3 decoder
- initialise libsndfile struct prior to calling sf_open
- when using processex, always start threads disabled so we cant loose
the thread handle if it quits rapidly

0.98: minor bux fix update (shipped with OAS Playout v3.41)
- relinked with patched BCC runtime libs to avoid heap crash issue.

0.99: bug fix update (shipped with OAS Playout v3.42)
- improve seek accuracy of Xing VBR files

1.00: bug fix update
- OAS_MSG_NTFY_INPUT_POSN/OAS_MSG_NTFY_INPUT_TIME messages sent before
OAS_MSG_NTFY_STREAM_DURATION message on file open which is incorrect


Quick Overview
--------------

All functions, structure and data declared in 'oas-audio.h'

caveats:

- no internal error checking of params (crap in=crap out)
- allegedly the codec can deal with MP2 files at this rate....
- DX3 or better, not NT

Files in archive
----------------

oas-audio.txt 		- this file
oas-audio.dll 		- API itself
oas-audio.h		- 'C' header file
mpglib.dll 		- MPGLIB v0.92 (modified) decoder
oas-audio_bc.lib	- BCC import library
oas-audio_vc.lib	- VC import library
oas-audio.chm 		- API help file
lpgl.txt 		- GNU Lesser General Public Licence (LGPL)
readme.txt		- readme for MPGLIB
interface.c		- Modifications made to MPGLIB v0.92
mpglibdll.h		- "
mpglibdll.zip		- original (unmodified) MPGLIB

JRB, 02/01/06
