<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>Lame-</title>
</head>
<body bgcolor="#FFFFFF">
<p align="center"> </p>
<p align="center"><font size="7">Lame-enc DLL</font> <br>
<font size="5">Interface version 1.32</font> (and above)<br>
(Lame engine version: 3.93 or higher) <br>
<font size="6">Programmers Manual</font></p>
<p align="center"><i>The lame_enc.dll and this manual is
copyright by Albert L Faber<br>
Originally the the DLL interface is modeled after the BladeEnc
DLL interface<br>
which is copyrighted by Tord Jansson and Jukka Poikolainen<br>
This document and the DLL interface may be distributed freely</i>
<br>
<i>as long as modifications are released under the LGPL license.</i>
</p>
<p align="center"> </p>
<p align="center"><b>Homepage</b>: <a
href="http://www.cdex.n3.net">http://www.cdex.n3.net</a><br>
<b>E-mail:</b> mailto: <a
href="mailto:afaber@users.sourceforge.net">afaber@users.sourceforge.net</a>
</p>
<p><br>
<br>
<br>
<br>
</p>
<p><font size="5">Distribution</font> </p>
<p>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. </p>
<p><br>
</p>
<p><font size="5">Disclaimer</font> </p>
<p>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. <br>
<br>
</p>
<p><font size="5">Current Bugs and Limitations</font> </p>
<p>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. <br>
</p>
<p><font size="5">Future Compatibility</font> </p>
<p>This interface should be compatible with all future versions
of lame_enc.DLL without any need to recompile your programs. You
should therefore <b>not</b> check the version number upon start
and prevent users from running your program with a later version
of lame_enc.DLL. <br>
</p>
<hr>
<p><font size="5">How to use the DLL</font> </p>
<p>1. Fill in a <a href="#The BE_CONFIG Structure">BE_CONFIG </a>structure
and send it to <a href="#beInitStream()">beInitStream()</a>. Make
sure that BE_ERR_SUCCESSFUL is returned. </p>
<p>2. Reserve at least the amount of memory returned in
dwBufferSize as your output buffer. </p>
<p>3. Call <a href="#beEncodeChunk()">beEncodeChunk()</a> until
you've encoded everything you want. </p>
<p>4. Call <a href="#beDeinitStream()">beDeinitStream()</a> to
make sure that all encoded data is flushed out before closing the
stream. </p>
<p>5. Close the stream using <a href="#beCloseStream()">beCloseStream()
</a></p>
<p>6. Finally, call the <a href="#beWriteVBRHeader()">beWriteVBRHeader()</a>
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.</p>
<p>A handy feature is the available <a
href="#Lame_enc.dll debug option">Lame_enc.dll debug option</a>,
which will dump the important lame internal settings to a text
file.<br>
</p>
<p> </p>
<p><font size="5">Return Values</font> </p>
<p>See the header-file for a complete list of function return
values. All functions should return BE_ERR_SUCCESSFUL unless
something went wrong. <br>
</p>
<hr>
<h1><a name="Type definitions"><font size="5">Type definitions</font></a></h1>
<p>The DLL is by default compiled with the MS Visual C/C++
compiler, which has the following type definitions:</p>
<table border="0">
<tr>
<td>Type </td>
<td>Description</td>
</tr>
<tr>
<td>CHAR</td>
<td>signed char (8 bits)</td>
</tr>
<tr>
<td>BYTE</td>
<td>unsigned char (8 bits)</td>
</tr>
<tr>
<td>SHORT</td>
<td>signed short (16 bits)</td>
</tr>
<tr>
<td>WORD</td>
<td>unsigned short (16 bits)</td>
</tr>
<tr>
<td>INT</td>
<td>signed long (32 bits)</td>
</tr>
<tr>
<td>LONG</td>
<td>signed long (32 bits)</td>
</tr>
<tr>
<td>BOOL</td>
<td>signed long (32 bits) (YES, 32 bits for a one bit
value)<br>
TRUE = 0<br>
FALSE=-1</td>
</tr>
<tr>
<td>DWORD</td>
<td>unsigned long (32 bits)</td>
</tr>
<tr>
<td>FLOAT</td>
<td>floating point (32 bits)</td>
</tr>
<tr>
<td>DOUBLE</td>
<td>float point (64 bits)</td>
</tr>
<tr>
<td>LPCSTR</td>
<td>const char* (32 bits pointer to zero terminated
character string)</td>
</tr>
</table>
<p>Within the lame_enc.dll All the structure elements are one
byte alligned (due to backwards compatibility with BladEnc.DLL!</p>
<p> </p>
<hr>
<h1><a name="The BE_CONFIG Structure"><font size="5">The
BE_CONFIG Structure </font></a></h1>
<p><font size="3">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</font></p>
<p> </p>
<h2><font size="5">The MP3 BE_CONFIG - structure (OBSOLETE)</font></h2>
<p>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.</p>
<p>These are the members of the BE_CONFIG structure you need to
fill in before you call beInitStream(): <br>
</p>
<table border="0">
<tr>
<td><b>dwConfig</b></td>
<td>Specifies what kind of output you want. Since only
MP3 currently is supported you must set this to <b>BE_CONFIG_MP3</b></td>
</tr>
<tr>
<td><b>format.mp3.dwSampleRate</b> </td>
<td>Samplerate in Hz for MP3 file. This can be set to
either <b>32000</b>, <b>44100</b> or <b>48000</b>.</td>
</tr>
<tr>
<td><b>format.mp3.byMode</b></td>
<td>Stereomode for MP3 file. This can be either <b>BE_MP3_MODE_STEREO</b>,
<b>BE_MP3_MODE_DUALCHANNEL</b> or <b>BE_MP3_MODE_MONO.</b></td>
</tr>
<tr>
<td><b>format.mp3.bitrate</b></td>
<td>Bitrate (i.e. size) of MP3 file in kBit/s. Allowed
bitrates are: <b>32, 40, 48, 56, 64, 80, 96, 112, 128,
160, 192, 224, 256</b> and <b>320</b>.</td>
</tr>
<tr>
<td><b>format.mp3.bCopyright</b></td>
<td>If this is set to TRUE the Copyright bit in the MP3
stream will be set.</td>
</tr>
<tr>
<td><b>format.mp3.bCRC</b></td>
<td>Set this to TRUE in order to enable CRC-checksum in
the bitstream.</td>
</tr>
<tr>
<td><b>format.mp3.bOriginal</b></td>
<td>If this is set to TRUE the Original bit in the MP3
stream will be set.</td>
</tr>
<tr>
<td><b>format.mp3.bPrivate</b></td>
<td>If this is set to TRUE the Private bit in the MP3
stream will be set.</td>
</tr>
</table>
<p> </p>
<h2><font size="5">The LHV1 BE_CONFIG - structure (recommended)</font></h2>
<p>These are the members of the LHV1 BE_CONFIG structure, you
need to fill in before you call beInitStream(): <br>
</p>
<table border="0">
<tr>
<td><b>dwConfig</b></td>
<td>Specifies what kind of output you want. Since only
MP3 currently is supported you must set this to <b>BE_CONFIG_LAME</b></td>
</tr>
<tr>
<td> </td>
<td> </td>
</tr>
<tr>
<td><b>format.LHV1.dwStructVersion</b></td>
<td>Indicates the version number of the structure,
current version number is 1</td>
</tr>
<tr>
<td><b>format.LHV1.dwStructSize</b></td>
<td>Specifies the size of the BE_CONFIG structure
(currently 331 bytes)</td>
</tr>
<tr>
<td> </td>
<td> </td>
</tr>
<tr>
<td><b>format.LHV1.dwSampleRate</b> </td>
<td>Samplerate in Hz for MP3 file. This can be set to
either:<br>
<b>32000</b>, <b>44100</b> or <b>48000</b> for MPEG-I<br>
<b>16000</b>, <b>22050</b> or <b>24000</b> for MPEG-I<br>
<b>8000</b>, <b>11025</b> or <b>12000</b> for MPEG-II.5</td>
</tr>
<tr>
<td><b>format.LHV1.dwReSampleRate</b></td>
<td>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</td>
</tr>
<tr>
<td><b>format.LHV1.nMode</b></td>
<td>Stereomode for MP3 file. This can be either <b>BE_MP3_MODE_STEREO</b>,
<b>BE_MP3_MODE_JSTEREO, BE_MP3_MODE_DUALCHANNEL</b> or <b>BE_MP3_MODE_MONO.</b></td>
</tr>
<tr>
<td><strong>format.LHV1.dwBitrate</strong></td>
<td>For CBR, this specifies the actual bitrate, for VBR,
it specifies the minimum bitrate<br>
Allowed bitrates are: <b>32, 40, 48, 56, 64, 80, 96, 112,
128, 160, 192, 224, 256</b> and <b>320</b>.for MPEG-I<br>
Allowed bitrates are: <b>8, 16, 24, 32, 40, 48, 56, 64,
80, 96, 112, 128, 144 </b>and<b> 160</b>.for MPEG-II<p><strong>Note:</strong>
dwBitrate is used as the minimum bitrate in the case of
using a VBR mode.</p>
</td>
</tr>
<tr>
<td><strong>format.LHV1.dwMaxBitrate</strong></td>
<td>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.</td>
</tr>
<tr>
<td><strong>format.LHV1.nPreset</strong></td>
<td>Keep in mind that the presets can overwrite some of
the other settings, since it is called right before the
encoder is initialized<br>
<table border="0">
<tr>
<td>The nPreset option can be set to one of the
following presets values::</td>
</tr>
</table>
<p>LQP_NOPRESET (don't use any presets)<br>
LQP_NORMAL_QUALITY (quality is set to 5)<br>
LQP_LOW_QUALITY (quality is set to 9)<br>
LQP_HIGH_QUALITY (quality is set to 2)<br>
LQP_VOICE_QUALITY (use for voice encoding)<br>
LQP_R3MIX (r3mix preset option)<br>
LQP_VERYHIGH_QUALITY (quality is set to 0)<br>
LQP_STANDARD (lame command line alt-preset standard)<br>
LQP_FAST_STANDARD (lame command line alt-preset fast
standard)<br>
LQP_EXTREME (lame command line alt-preset extreme)<br>
LQP_FAST_EXTREME (lame command line alt-preset fast
extreme)<br>
LQP_INSANE (lame command line alt-preset insane)<br>
LQP_ABR (lame command line alt-preset abr)<br>
LQP_CBR(lame command line alt-preset cbr)<br>
<br>
<strong>(old lame preset options)</strong><br>
LQP_PHONE <br>
LQP_SW<br>
LQP_AM<br>
LQP_FM<br>
LQP_VOICE<br>
LQP_RADIO<br>
LQP_TAPE<br>
LQP_HIFI<br>
LQP_CD<br>
LQP_STUDIO</p>
</td>
</tr>
<tr>
<td> </td>
</tr>
<tr>
<td><b>format.LHV1.bCopyright</b></td>
<td>If this is set to TRUE the Copyright bit in the MP3
stream will be set.</td>
</tr>
<tr>
<td><b>format.LHV1.bCRC</b></td>
<td>Set this to TRUE in order to enable CRC-checksum in
the bitstream.</td>
</tr>
<tr>
<td><b>format.LHV1.bOriginal</b></td>
<td>If this is set to TRUE the Original bit in the MP3
stream will be set.</td>
</tr>
<tr>
<td><b>format.LHV1.bPrivate</b></td>
<td>If this is set to TRUE the Private bit in the MP3
stream will be set.</td>
</tr>
<tr>
<td> </td>
<td> </td>
</tr>
<tr>
<td><strong>format.LHV1.nVbrMethod</strong></td>
<td>Sepecifes if the VBR method to use, currently the
following settings are supported:<p><font size="3">VBR_METHOD_NONE
(don't use VBR, use CBR encoding instead),<br>
VBR_METHOD_DEFAULT (default VBR method)<br>
VBR_METHOD_OLD (old VBR method, proven to be reliable)<br>
VBR_METHOD_NEW (new VBR method, faster than
VBR_METHOD_OLD)<br>
VBR_METHOD_MTRH (depreciated, same as VBR_METHOD_NEW)<br>
VBR_METHOD_ABR (Average Bitrate Encoding, see also </font><strong>format.LHV1.dwVbrAbr_bps</strong><font
size="3">)</font></p>
</td>
</tr>
<tr>
<td><strong>format.LHV1.bWriteVBRHeader</strong></td>
<td>Sepecifes if the a XING VBR header should be written
or not. When this option is enabled, you have to call the
<font size="3">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.</font></td>
</tr>
<tr>
<td><strong>format.LHV1.bEnableVBR</strong></td>
<td>Specifies if VBR encoding option shall be used or
not, possible values are TRUE/FALSE</td>
</tr>
<tr>
<td><strong>format.LHV1.nVBRQuality</strong></td>
<td>Quality option if VBR is enabled (0=highest quality,
9 is lowest quality)</td>
</tr>
<tr>
<td><strong>format.LHV1.dwVbrAbr_bps</strong></td>
<td>If the Average Bit Rate is specified, the lame
encoder ignores the nVBRQuality settings (However, <strong>bEnableVBR</strong>
must be set to TRUE and the <strong>format.LHV1.nVbrMethod
</strong>parameter should be set to<strong> </strong><font
size="3"><strong>VBR_METHOD_ABR</strong>). The allowed
range for the </font><strong>format.LHV1.dwVbrAbr_bps </strong>parameter<strong>
</strong>any integer value <font size="3">between:</font><p><strong>MPEG-I:</strong>
32000 .. 320000 bps<b><br>
</b><strong>MPEG-II:</strong> 8000 .. 160000 bps</p>
</td>
</tr>
<tr>
<td> </td>
<td> </td>
</tr>
<tr>
<td><strong>format.LHV1.bNoBitRes</strong></td>
<td>Disables the bit-resorvoir and disables the insertion
of padded frames</td>
</tr>
<tr>
<td><strong>format.LHV1.nQuality</strong></td>
<td>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.</td>
</tr>
<tr>
<td><b>format.mp3.btReserved</b></td>
<td>For future use, set all elements to zero</td>
</tr>
</table>
<p> </p>
<p> </p>
<hr>
<h1><a name="beInitStream()"><font size="5">beInitStream()</font></a>
</h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top" width="80%">BE_ERR beInitStream(
PBE_CONFIG <i>pbeConfig</i>, PDWORD <i>dwSamples</i>,
PDWORD <i>dwBufferSize</i>, PHBE_STREAM <i>phbeStream</i>
)</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Parameters:</b></td>
<td valign="top" width="80%"><table border="0"
cellspacing="10" width="100%">
<tr>
<td valign="top" width="20%"><i>pbeConfig</i></td>
<td>Pointer at the struct containing encoder
settings.</td>
</tr>
<tr>
<td valign="top"><i>dwSamples</i></td>
<td>Pointer at double word where number of
samples to send to each <i>beEncodeChunk()</i> is
returned.</td>
</tr>
<tr>
<td valign="top"><i>dwBufferSize</i></td>
<td>Pointer at double word where minimum size in
bytes of output buffer is returned.</td>
</tr>
<tr>
<td valign="top"><i>phbeStream</i></td>
<td>Pointer at integer where Stream handle is
returned.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Description:</b></td>
<td valign="top" width="80%">This function is the first
to call before starting an encoding stream.</td>
</tr>
</table>
<hr>
<h1><a name="beEncodeChunk()"><font size="5">beEncodeChunk()</font>
</a></h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top" width="80%">BE_ERR beEncodeChunk(
HBE_STREAM <i>hbeStream</i>, DWORD <i>nSamples</i>,
PSHORT <i>pSamples</i>, PBYTE <i>pOutput</i>, PDWORD <i>pdwOutput</i>
)</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Parameters:</b></td>
<td valign="top"><table border="0" cellspacing="10"
width="100%">
<tr>
<td valign="top" width="20%"><i>hbeStream</i></td>
<td width="80%">Handle of the stream.</td>
</tr>
<tr>
<td valign="top" width="90"><i>nSamples</i></td>
<td>Number of samples to be encoded for this
call. This should be identical to what is
returned by <i>beInitStream()</i>, unless you are
encoding the last chunk, which might be smaller.</td>
</tr>
<tr>
<td valign="top" width="90"><i>pSamples</i></td>
<td>Pointer at the 16-bit signed samples to be
encoded. These should be in stereo when encoding
a stereo MP3 and mono when encoding a mono MP3.</td>
</tr>
<tr>
<td valign="top" width="90"><i>pOutput</i></td>
<td>Where to write the encoded data. This buffer
should be at least of the minimum size returned
by <i>beInitStream()</i>.</td>
</tr>
<tr>
<td valign="top" width="90"><i>pdwOutput</i></td>
<td>Where to return number of bytes of encoded
data written. The amount of data written might
vary from chunk to chunk.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Description:</b></td>
<td valign="top">Encodes a chunk of samples. <i>Please
note that if you have set the output to generate mono MP3
files you must feed beEncodeChunk() with mono samples!</i></td>
</tr>
</table>
<hr>
<h1><a name="beDeinitStream()"><font size="5">beDeinitStream()</font>
</a></h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top" width="80%">BE_ERR beDeinitStream(
HBE_STREAM <i>hbeStream</i>, PBYTE <i>pOutput</i>, PDWORD
<i>pdwOutput</i> )</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Parameters:</b></td>
<td valign="top"><table border="0" cellspacing="10"
width="100%">
<tr>
<td valign="top" width="20%"><i>hbeStream</i></td>
<td width="80%">Handle of the stream.</td>
</tr>
<tr>
<td valign="top"><i>pOutput</i></td>
<td>Where to write the encoded data. This buffer
should be at least of the minimum size returned
by <i>beInitStream()</i>.</td>
</tr>
<tr>
<td><i>pdwOutput</i></td>
<td>Where to return number of bytes of encoded
data written.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" width="20%"><b>Description:</b></td>
<td valign="top">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.</td>
</tr>
</table>
<hr>
<h1><a name="beCloseStream()"><font size="5">beCloseStream()</font></a>
</h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top">BE_ERR beCloseStream( HBE_STREAM <i>hbeStream</i>
)</td>
</tr>
<tr>
<td valign="top" width="90"><b>Parameters:</b></td>
<td valign="top"><table border="0" cellspacing="10"
width="100%">
<tr>
<td width="20%"><i>hbeStream</i></td>
<td>Handle of the stream.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" width="90"><b>Description:</b></td>
<td valign="top">Last function to be called when finished
encoding a stream. Should unlike <i>beDeinitStream()</i>
also be called if the encoding is canceled.</td>
</tr>
</table>
<hr>
<h1><a name="beVersion()"><font size="5">beVersion()</font> </a></h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top">VOID beVersion( PBE_VERSION <i>pbeVersion</i>
)</td>
</tr>
<tr>
<td valign="top"><b>Parameters:</b></td>
<td valign="top"><table border="0" cellspacing="10"
width="100%">
<tr>
<td valign="top" width="20%"><i>pbeVersion</i></td>
<td>Pointer at struct where version number,
release date and URL for homepage is returned.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top"><b>Description:</b></td>
<td valign="top">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.</td>
</tr>
</table>
<p> </p>
<hr>
<p> </p>
<h1><a name="beWriteVBRHeader()"><font size="5">beWriteVBRHeader()</font>
</a></h1>
<table border="0" cellspacing="16" width="100%">
<tr>
<td valign="top" width="20%"><b>Synopsis:</b></td>
<td valign="top">VOID beWriteVBRHeader( LPCSTR <i>pszMP3FileName</i>
)</td>
</tr>
<tr>
<td valign="top"><b>Parameters:</b></td>
<td valign="top"><table border="0" cellspacing="10"
width="100%">
<tr>
<td valign="top" width="20%"><i>pszMP3FileName</i></td>
<td>Const Pointer zero terminated string, that
contains the MP3 file name.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top"><b>Description:</b></td>
<td valign="top">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</td>
</tr>
</table>
<p> </p>
<p> </p>
<hr>
<p> </p>
<h1><a name="Lame_enc.dll debug option">Lame_enc.dll debug option</a></h1>
<p>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</p>
<p>[debug]<br>
WriteLogFile=1</p>
<p>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</p>
<p> </p>
<p><br>
</p>
</body>
</html>
root