Lame-enc DLL
Interface version 1.32 (and above)
(Lame engine version: 3.93 or higher)
Programmers Manual
The lame_enc.dll and this manual is
copyright by Albert L Faber
Originally the the DLL interface is modeled after the BladeEnc
DLL interface
which is copyrighted by Tord Jansson and Jukka Poikolainen
This document and the DLL interface may be distributed freely
as long as modifications are released under the LGPL license.
Homepage: http://www.cdex.n3.net
E-mail: mailto: afaber@users.sourceforge.net
Distribution
People and companies who wants to distribute lame_enc.dll with their commercial products are free to do so as far as I'm concerned (LGPL license), but should be aware that lame_enc.dll might infringe certain MP3 related software patents held by Fraunhofer IIS in certain countries.
Disclaimer
lame_enc.dll and this manual is distributed 'as is' with no
warranty of any kind. The Author is not to be held responsible
for the result of any use or misuse of this product.
Current Bugs and Limitations
Although the interface is designed to be able to handle
multiple parallel streams it can't be done yet due to limitations
in the engine, only one stream is allowed.
Future Compatibility
This interface should be compatible with all future versions
of lame_enc.DLL without any need to recompile your programs. You
should therefore not check the version number upon start
and prevent users from running your program with a later version
of lame_enc.DLL.
How to use the DLL
1. Fill in a BE_CONFIG structure and send it to beInitStream(). Make sure that BE_ERR_SUCCESSFUL is returned.
2. Reserve at least the amount of memory returned in dwBufferSize as your output buffer.
3. Call beEncodeChunk() until you've encoded everything you want.
4. Call beDeinitStream() to make sure that all encoded data is flushed out before closing the stream.
5. Close the stream using beCloseStream()
6. Finally, call the beWriteVBRHeader() functions, to insert the INFO tag MP3 Header. This is an extension of the Xing VBR tag which is also used for CBR encodings. This call can only be omitted if the INFO tag was explicilty disabled in the BE_CONFIG Structure.
A handy feature is the available Lame_enc.dll debug option,
which will dump the important lame internal settings to a text
file.
Return Values
See the header-file for a complete list of function return
values. All functions should return BE_ERR_SUCCESSFUL unless
something went wrong.
The DLL is by default compiled with the MS Visual C/C++ compiler, which has the following type definitions:
| Type | Description |
| CHAR | signed char (8 bits) |
| BYTE | unsigned char (8 bits) |
| SHORT | signed short (16 bits) |
| WORD | unsigned short (16 bits) |
| INT | signed long (32 bits) |
| LONG | signed long (32 bits) |
| BOOL | signed long (32 bits) (YES, 32 bits for a one bit
value) TRUE = 0 FALSE=-1 |
| DWORD | unsigned long (32 bits) |
| FLOAT | floating point (32 bits) |
| DOUBLE | float point (64 bits) |
| LPCSTR | const char* (32 bits pointer to zero terminated character string) |
Within the lame_enc.dll All the structure elements are one byte alligned (due to backwards compatibility with BladEnc.DLL!
Currently there the BE_CONFIG structure has to varians, the old MP3 config structure that is truly compatible with the old BladeEnc interface, and the new defined LHV1 structure, which can set far more options in the lame encoder
This is the old structure as it was originally defined by the BladeEnc.DLL interface. However, I do highly recommend to use the new Lame specific config structure, since it gives you more control over the Lame encoder settings.
These are the members of the BE_CONFIG structure you need to
fill in before you call beInitStream():
| dwConfig | Specifies what kind of output you want. Since only MP3 currently is supported you must set this to BE_CONFIG_MP3 |
| format.mp3.dwSampleRate | Samplerate in Hz for MP3 file. This can be set to either 32000, 44100 or 48000. |
| format.mp3.byMode | Stereomode for MP3 file. This can be either BE_MP3_MODE_STEREO, BE_MP3_MODE_DUALCHANNEL or BE_MP3_MODE_MONO. |
| format.mp3.bitrate | Bitrate (i.e. size) of MP3 file in kBit/s. Allowed bitrates are: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 and 320. |
| format.mp3.bCopyright | If this is set to TRUE the Copyright bit in the MP3 stream will be set. |
| format.mp3.bCRC | Set this to TRUE in order to enable CRC-checksum in the bitstream. |
| format.mp3.bOriginal | If this is set to TRUE the Original bit in the MP3 stream will be set. |
| format.mp3.bPrivate | If this is set to TRUE the Private bit in the MP3 stream will be set. |
These are the members of the LHV1 BE_CONFIG structure, you
need to fill in before you call beInitStream():
| dwConfig | Specifies what kind of output you want. Since only MP3 currently is supported you must set this to BE_CONFIG_LAME | |
| format.LHV1.dwStructVersion | Indicates the version number of the structure, current version number is 1 | |
| format.LHV1.dwStructSize | Specifies the size of the BE_CONFIG structure (currently 331 bytes) | |
| format.LHV1.dwSampleRate | Samplerate in Hz for MP3 file. This can be set to
either: 32000, 44100 or 48000 for MPEG-I 16000, 22050 or 24000 for MPEG-I 8000, 11025 or 12000 for MPEG-II.5 |
|
| format.LHV1.dwReSampleRate | Specifies to which sample rate the input stream has to be resampled, if set to 0, the encoder will decide which ReSample rate to use | |
| format.LHV1.nMode | Stereomode for MP3 file. This can be either BE_MP3_MODE_STEREO, BE_MP3_MODE_JSTEREO, BE_MP3_MODE_DUALCHANNEL or BE_MP3_MODE_MONO. | |
| format.LHV1.dwBitrate | For CBR, this specifies the actual bitrate, for VBR,
it specifies the minimum bitrate Allowed bitrates are: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 and 320.for MPEG-I Allowed bitrates are: 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144 and 160.for MPEG-II Note: dwBitrate is used as the minimum bitrate in the case of using a VBR mode. |
|
| format.LHV1.dwMaxBitrate | When VBR mode is enabled, it specifies the maximum allowed bitrate (see also dwBitrate to specify the minium bitrate), for CBR mode this setting is ignored. | |
| format.LHV1.nPreset | Keep in mind that the presets can overwrite some of
the other settings, since it is called right before the
encoder is initialized
LQP_NOPRESET (don't use any presets) |
|
| format.LHV1.bCopyright | If this is set to TRUE the Copyright bit in the MP3 stream will be set. | |
| format.LHV1.bCRC | Set this to TRUE in order to enable CRC-checksum in the bitstream. | |
| format.LHV1.bOriginal | If this is set to TRUE the Original bit in the MP3 stream will be set. | |
| format.LHV1.bPrivate | If this is set to TRUE the Private bit in the MP3 stream will be set. | |
| format.LHV1.nVbrMethod | Sepecifes if the VBR method to use, currently the
following settings are supported: VBR_METHOD_NONE
(don't use VBR, use CBR encoding instead), |
|
| format.LHV1.bWriteVBRHeader | Sepecifes if the a XING VBR header should be written or not. When this option is enabled, you have to call the beWriteVBRHeader function when encoding has been completed. Keep in mind that the VBR info tag can also be written for CBR encoded files, the TAG info can be useful for additional info like encoder delay and the like. | |
| format.LHV1.bEnableVBR | Specifies if VBR encoding option shall be used or not, possible values are TRUE/FALSE | |
| format.LHV1.nVBRQuality | Quality option if VBR is enabled (0=highest quality, 9 is lowest quality) | |
| format.LHV1.dwVbrAbr_bps | If the Average Bit Rate is specified, the lame
encoder ignores the nVBRQuality settings (However, bEnableVBR
must be set to TRUE and the format.LHV1.nVbrMethod
parameter should be set to VBR_METHOD_ABR). The allowed
range for the format.LHV1.dwVbrAbr_bps parameter
any integer value between: MPEG-I:
32000 .. 320000 bps |
|
| format.LHV1.bNoBitRes | Disables the bit-resorvoir and disables the insertion of padded frames | |
| format.LHV1.nQuality | Quality Setting, HIGH BYTE should be NOT LOW byte, otherwhise quality is set to 5. This is done to be backward compatible. So to set quality to 3, you have to set the nQuality parameter to 0xFC03. | |
| format.mp3.btReserved | For future use, set all elements to zero |
| Synopsis: | BE_ERR beInitStream( PBE_CONFIG pbeConfig, PDWORD dwSamples, PDWORD dwBufferSize, PHBE_STREAM phbeStream ) | ||||||||
| Parameters: |
|
||||||||
| Description: | This function is the first to call before starting an encoding stream. |
| Synopsis: | BE_ERR beEncodeChunk( HBE_STREAM hbeStream, DWORD nSamples, PSHORT pSamples, PBYTE pOutput, PDWORD pdwOutput ) | ||||||||||
| Parameters: |
|
||||||||||
| Description: | Encodes a chunk of samples. Please note that if you have set the output to generate mono MP3 files you must feed beEncodeChunk() with mono samples! |
| Synopsis: | BE_ERR beDeinitStream( HBE_STREAM hbeStream, PBYTE pOutput, PDWORD pdwOutput ) | ||||||
| Parameters: |
|
||||||
| Description: | This function should be called after encoding the last chunk in order to flush the encoder. It writes any encoded data that still might be left inside the encoder to the output buffer. This function should NOT be called unless you have encoded all of the chunks in your stream. |
| Synopsis: | BE_ERR beCloseStream( HBE_STREAM hbeStream ) | ||
| Parameters: |
|
||
| Description: | Last function to be called when finished encoding a stream. Should unlike beDeinitStream() also be called if the encoding is canceled. |
| Synopsis: | VOID beVersion( PBE_VERSION pbeVersion ) | ||
| Parameters: |
|
||
| Description: | Returns information like version numbers (both of the DLL and encoding engine), release date and URL for lame_enc's homepage. All this information should be made available to the user of your product through a dialog box or something similar. |
| Synopsis: | VOID beWriteVBRHeader( LPCSTR pszMP3FileName ) | ||
| Parameters: |
|
||
| Description: | Writes a Xing Header in front of the MP3 file. Make sure that the MP3 file is closed, and the the beConfig.format.LHV1.bWriteVBRHeader has been set to TRUE. In addition, it is always save to call beWriteVBRHeader after the encoding has been finished, even when the beConfig.format.LHV1.bWriteVBRHeader is not set to TRUE |
The lame_enc.dll has a built-in debug option, that dumps all the important internal settings to a text file. To enable this feature, create a text file in the Windows directory which is named lame_enc.ini, and should contain the following two lines
[debug]
WriteLogFile=1
Save this text file, and each time you encode a file, the settings are added to a file name lame_enc.txt, that is located in the same directory as the lame_enc.dll