r8b.dll v1.9
Copyright (c) 2002-2005 Aleksey Vaneev
http://www.voxengo.com/r8brain/
e-mail: support@voxengo.com

r8b.dll API

DLL file that comes with the GUI is a freely-available module that you can
use in your products free of charge. License for "r8b.dll" is available in
the "r8b_license.txt" file.

------------------------------------------------------------------------------

Basically, this DLL has a very small number of procedures. The first procedure
is called "r8b_getWAVInfo" which returns sample rate and bit depth of the
specified WAV file. The second one called "r8b_execute" performs actual sample
rate conversion. The third one called "r8b_executeMem" does the same as
"r8b_execute", but works with in-memory buffers. Since this DLL was originally
written in Pascal, API is also defined in Pascal. Conversion to C/C++ or any
other language supporting DLL modules must be rather trivial.


1. r8b_getWAVInfo
-----------------

procedure r8b_getWAVInfo (fname: PChar; var SR, Depth: LongInt;
    var err: TR8BError); cdecl; external 'r8b.dll';

Where fname is a full name of the WAV file to acquire info from. SR and Depth
variables will contain sample rate and bit depth values, respectively. Please
note, this procedure returns bit depth value not taking into account whether
it is a floating representation or not. err is a structure that will hold
error information occured.

TR8BError structure is declared as:

type
    TR8BError =
        packed record
            WasError: Boolean;
            ErrMsg: array [0..127] of Char;
        end;

WasError = False on return means procedure completed successfully. Otherwise
ErrMsg buffer will contain error message.


2. r8b_execute
--------------

procedure r8b_execute (InFileName, OutFileName: PChar;
    OutRate, OutBitDepth, OutQuality, Preallocate: LongInt;
    var CancelFlag: LongInt; Callback: TR8BCallback; p: Pointer;
    var err: TR8BError); cdecl; external 'r8b.dll';

This procedure performs sample rate conversion. WAV file InFileName will be
converted to WAV file with the name OutFileName.

OutRate - sample rate of output file. Please, don't use extreme values for
output sample rate. Normal "designed" input to output sample rate ratio lies
between 0.2 to 5. Also it is not a very good idea to specify the output sample
rate value equal to the input sample rate value (e.g., for performing bit
depth conversion only) since internally conversion will take place in any
way, thus slightly cutting higher frequencies of the original file.

OutBitDepth specifies bit depth of the output file. Allowed values are
8, 16, 24, 32 and 64. Please note that values 32 and 64 mean output file will
be written in IEEE floating sample format.

OutQuality value must be specified in the range from 0 to 4 inclusive,
where 0 is the lowest quality and the highest execution speed, and 4 is the
highest quality and the lowest execution speed.

If Preallocate parameter is non-zero, WAV file will be expanded to the
necessary size before performing conversion. Preallocation allows to minimize
output file fragmentation thus increasing speed of subsequent accesses.

CancelFlag variable can be adjusted to a non-zero value during callback to
signal r8b_execute to stop processing. r8b_execute automatically zeroes it
before processing starts. Even if conversion was stopped output WAV file will
be correctly closed and will contain data up to the point where the process
was stopped. Actually, WAV file will be larger if Preallocate variable was set
to a non-zero value.

Callback is an address of the callback procedure, defined as:

type
    TR8BCallback = procedure (Position, Max: LongInt; p: Pointer); cdecl;

That is, if Callback <> nil, r8b_execute periodically calls this procedure
signalling the progress of the conversion. Position is the current state of
the process and Max is its maximal value. Position is always lesser or equal
to Max. Progress in percent is calculated this way:
progress = Position / Max * 100.0. p is an additional custom pointer you have
provided when calling r8b_execute.


3. r8b_executeMem
-----------------

procedure r8b_executeMem (var InFormat: TR8BInputFormat; OutBuffer: Pointer;
    OutLength, OutRate, OutBitDepth, OutQuality: LongInt;
    var CancelFlag: LongInt; Callback: TR8BCallback; p: Pointer;
    var err: TR8BError; var ActualOut: LongInt); cdecl; external 'r8b.dll';

This procedure does the same as the "r8b_execute" procedure. The only
difference is that the "r8b_executeMem" works with headerless in-memory input
buffer.

TR8BInputFormat record is defined as:

type
    TR8BInputFormat =
        packed record
            Buffer: Pointer;
            Rate: LongInt;
            BitDepth: LongInt;
            Channels: LongInt;
            IEEE: LongInt;
            Len: LongInt;
        end;

InFormat.Buffer specifies pointer to the input data.

InFormat.Rate variable specifies input sample rate. Valid values are
considered to be in the range 1000 to 500000.

InFormat.BitDepth specifies bit depth of the input buffer. Valid values are
8, 16, 24, 32 and 64. 64 can be defined only when InIEEE <> 0.

InFormat.Channels specifies the number of channels in the input buffer. Valid
values are 1 and 2. Please note that 2-channel sample data in the input buffer
must be stored in the interleaved form (like it is stored in the WAV files).

InFormat.IEEE must be equal to 0 if input samples are in integer form.
Non-zero values can be specified only for 32 and 64 bit depths.

InFormat.Len defines the number of samples provided in the input buffer.
Please note this is not an actual size in bytes of the input buffer.

OutBuffer - buffer to receive the resampled result.

OutLength - how many samples output buffer can hold. Resampling will stop
after filling this number of samples. Number of samples that are necessary
to hold all output data can be calculated this way:

    Trunc (Double (InFormat.Len) * Double (OutRate) /
        Double (InFormat.Rate) + 0.5)

On successful execution ActualOut will contain the number of samples that
were actually written to the output buffer.

Other procedure parameters have the same meaning as in the "r8b_execute"
procedure. Also note that specifying values for parameters other than those
described in this document can produce errorneous operation. It is a good idea
not to perform resampling if the input sample rate is equal to the output
sample rate even if this is possible.


4. r8b_execute2
---------------

procedure r8b_execute2 (InFileName, OutFileName: PChar; OutRate,
	OutBitDepth, OutQuality, Preallocate: LongInt; OutRateReal: Double;
	var CancelFlag: LongInt; Callback: TR8BCallback; p: Pointer;
	var err: TR8BError); cdecl;

Please, read the description of the "r8b_execute" procedure. "r8b_execute"
additionally allows to specify the fractional destination sample rate
OutRateReal. Please note that while you can specify the fractional sample
rate, actual sample rate which will be written into WAV file header is
specified too, as integer number.


5. r8b_executeMem2
------------------

procedure r8b_executeMem2 (var InFormat: TR8BInputFormat; OutBuffer: Pointer;
	OutLength: LongInt; OutRate: Double; OutBitDepth, OutQuality: LongInt;
    var CancelFlag: LongInt; Callback: TR8BCallback; p: Pointer;
    var err: TR8BError; var ActualOut: LongInt); cdecl;

This procedure works exactly like the "r8b_executeMem" procedure. The only
difference is that this procedure allows to specify the fractional destination
sample rate OutRate.

27-aug-2005
