© 2001 Tilman Liebchen
Last update: 02.02.2001
The LPAC Codec API (Application Programming Interface) is a simple C interface for the LPAC codec. You can use the functions in your own applications to losslessly encode wave files (*.wav) and store them in the LPAC file format (*.pac) as well as to decode existing LPAC files. There are functions to encode or decode a whole file with only one function call, and there are sets of functions to process files frame by frame.
To run your application the files "lpaccodec.dll" (the codec itself) and "lpac_codec_api.dll" (the C interface) have to be found in the search path.
Simply add the library "lpac_codec_api.lib" to your project and #include the header file "lpac_codec_api.h" into your source code file. Then the DLLs will be loaded automatically when your application is started.
In addition to including the header file "lpac_codec_api.h" you will need to explicitly load the DLL "lpac_codec_api.dll" by a special command in your source code (please refer to the documentation of your programming language). The DLL "lpaccodec.dll" should be loaded automatically when "lpac_codec_api.dll" is loaded.
The following sections describe data structures, encoder functions and decoder functions.
The PACINFO structure can hold information about a compressed LPAC file. It is used by DecoderGetInfo and GetPacFileInfo.
Fields
- frame: Size of one frame of audio data in bytes
- ver: Version of the file format (2, 4, 5, or 6)
- ra: Random access coding on (1) / off (0)
- poly: Polynomial prediction (fast compression mode) on (1) / off (0)
- js: Joint Stereo coding on (1) / off (0)
- ap: Adaptive prediction order on (1) / off (0)
- aq: Adaptive quantization (file format version < 6) on (1) / off (0)
- res: Resolution in bits (8, 16, or 24). If the original wave file defined a resolution of 20 bit / 12 bit, this field will be 24 / 16, since each sample was originally stored with 3 bytes / 2 bytes.
- ch: Number of channels (1 or 2)
- num: Total number of samples (per channel)
- freq: Sampling frequency in Hz
- wsize: Size of the original wave file in bytes
- psize: Size of the compressed LPAC file in bytes
This function offers a very simple means to losslessly compress a wave file using only one function. Input and Output file are opened and closed internally, so you just have to provide the file names and some coding options.
Parameters
- WavName: Input wave file (*.wav).
- PacName: Compressed output file (should be *.pac).
- Version: Version of the file format, should be 6 (for current format v6). A value of 0 automatically is mapped to the most recent format (currently 6).
- CompMode: Compression mode 1 (fast) ... 5 (extra high). Other values are mapped to 3 (medium compression).
- Joint: Joint Stereo Coding on if 1, else off (should always be on).
- RA: Random Access on if 1, else off.
Return values
- 0: Successfull
- 1: Encoder construction failed
- 2: File open failed
- 3: Encoding failed (no valid wave file)
Creates an encoder object. Call this function before using any other encoder function.
Return values
- 0: Successfull
- 1: Encoder construction failed
Opens input and output file for the encoder. The files have to be specified by their names.
Parameters
- WavName: Input wave file (*.wav).
- PacName: Compressed output file (should be *.pac).
Return values
- 0: Successfull
- 1: File open failed (WavName)
- 2: File open failed (PacName)
Closes input and output file after encoding. Call this function before calling EncoderDelete.
Return values
- 0: Successfull
- 1: File close failed (input file)
- 2: File close failed (output file)
Specifies input and output file for the encoder. The files have to be specified by file pointers after being opened by the calling application.
Parameters
- fpWav: Input wave file pointer
- fpPac: Compressed output file pointer
Return values
- 0: Successfull
- 1: fpWav or fpPac is NULL
Deletes the encoder object. Call this function before creating another encoder object by calling EncoderCreate.
Return values
- 0: Successfull
Sets the version of the file format to use. Valid file formats are v2/v4 (codec 1.5x), v5 (codec 2.0x), and v6 (codec 3.x). Call this function (if necessary) before calling EncoderSetCompMode, EncodeFile or EncodeHeader.
Parameters
- Version: 2, 4, 5, or 6 (default). Other values automatically map to the most recent file format (currently v6).
Return values
- Version value actually set.
Sets the compression mode. Valid modes are 1 (fast), 2 (simple), 3 (medium), 4 (high), and 5 (extra high). Call this function (if necessary) before calling EncodeFile or EncodeHeader.
Parameters
- CompMode: 1, 2, 3 (default), 4, or 5. Other values automatically map to mode 3.
Return values
- Compression mode actually set.
Turns joint stereo coding on/off. Call this function (if necessary) before calling EncodeFile or EncodeHeader.
Parameters
- Joint: A value of 1 enables joint stereo coding, other values disable it.
Return values
- 0: Joint stereo off
- 1: Joint stereo on
Turns random access coding on/off. Call this function (if necessary) before calling EncodeFile or EncodeHeader.
Parameters
- RA: A value of 1 enables random access coding, other values disable it.
Return values
- 0: Random access off
- 1: Random access on
Encodes a whole file. This function is equivalent to calling EncodeHeader, EncodeFrame for all frames, and EncodeRemains. Input and output file have to be specified by calling EncoderOpenFiles or EncoderSetFiles before.
Return values
- 0: Successfull
- 1: Encoding failed (no valid wave file)
Checks the wave file to encode and then encodes the header information. Input and output file have to be specified by calling EncoderOpenFiles or EncoderSetFiles before.
Return values
- Non-negative: Number of frames to encode
- -1: Encoding failed (no valid wave file)
Encodes a single frame of audio samples. The number of frames to encode for the whole file has to be determined by calling EncodeHeader before.
Return values
- 0: Successfull
Encodes remaining non-audio parts of the wave file and writes the CRC. Always use this function after encoding the last audio frame.
Return values
- Number of trailing non-audio bytes.
This function offers a very simple means to decompress a compressed LPAC file using only one function. Input and Output file are opened and closed internally, so you just have to provide the file names.
Parameters
- PacName: Compressed input file (*.pac).
- WavName: Output wave file (should be *.wav).
Return values
- 0: Successfull
- 1: CRC failed
- -1: Decoding failed (no valid LPAC file)
- -2: Decoder construction failed
- -3: File open failed
Creates an decoder object. Call this function before using any other decoder function.
Return values
- 0: Successfull
- 1: Decoder construction failed
Opens input and output file for the decoder. The files have to be specified by their names.
Parameters
- PacName: Compressed input file (*.pac).
- WavName: Output wave file (should be *.wav). If "" (empty string) is passed, no wave file will be generated. Instead, each decoded frame will be written into a buffer, which can be read by calling DecoderGetAudioData.
Return values
- 0: Successfull
- 1: File open failed (PacName)
- 2: File open failed (WavName)
Closes input and output file after decoding. Call this function before calling EncoderDelete.
Return values
- 0: Successfull
- 1: File close failed (input file)
- 2: File close failed (output file)
Specifies input and output file for the decoder. The files have to be specified by file pointers after being opened by the calling application.
Parameters
- fpWav: Compressed input file pointer
- fpPac: Output wave file pointer. If NULL is passed, no wave file will be generated. Instead, each decoded frame will be written into a buffer, which can be read by calling DecoderGetAudioData.
Return values
- 0: Successfull
- 1: fpWav is NULL
Deletes the decoder object. Call this function before creating another decoder object by calling DecoderCreate.
Return values
- 0: Successfull
Decodes a whole file. This function is equivalent to calling DecodeHeader, DecodeFrame for all frames, and DecodeRemains. Input and output file have to be specified by calling DecoderOpenFiles or DecoderSetFiles before.
Return values
- 0: Successfull
- 1: CRC failed
- -1: Decoding failed (no valid wave file)
Checks the LPAC file to decode and then decodes the header information. Input and output file have to be specified by calling DecoderOpenFiles or DecoderSetFiles before.
Return values
- Non-negative: Number of frames to decode
- -1: Decoding failed (no valid LPAC file)
Decodes a single frame of audio samples. The number of frames to decode for the whole file has to be determined by calling DecodeHeader before.
Return values
- 0: Successfull
Decodes remaining non-audio parts of the file and verifies the CRC. Always use this function after decoding the last audio frame.
Return values
- 0: Successfull
- 1: CRC failed
Retrieves information from the decoder about the currently opened LPAC file. To use this function, you have to call DecodeHeader or DecodeFile first.
Parameters
- info: PACINFO structure to hold the information
Return values
- 0: Successfull
Supplies a pointer to the buffer which contains the last frame of decoded audio data. The size of this buffer in bytes as well as information about the audio format can be retrieved by evaluating the PACINFO structure after calling DecoderGetInfo or GetPacFileInfo.
Return values
- Pointer to the audio frame buffer
Retrieves information from a compressed LPAC file without calling any other decoder functions. The file is opened and closed internally.
Parameters
- PacName: Compressed LPAC file (*.pac)
- info: PACINFO structure to hold the information
Return values
- 0: Successfull
- 1: File open failed (PacName)
- -1: No valid LPAC file