SoundLib3 (c) 1997-2008 by Stefan Goehler
Last update of this helpfile: 23rd of January 2008
This helpfile is for version 3 beta 2 of SoundLib only.
INDEX Introduction About SoundLib SoundLib is a Multichannel and 3D sound mixing library for Delphi, Free Pascal and C++.
It is quite comprehensive but avoids to offload this to the user. Instead, most functionality will initialize itself, like the selection of the best output interface, output device and its speaker selection. However, advanced users have the possibility to access and control extended features.
Goals of SoundLib

Simplicity -- Easy to use API, free formats avoid licensing hassle
Hands free -- Initializes what you likely need, but only if you want so
Straight formats -- Supports every free format you need for development, not every format on market
Platform independence -- Pure software mixer makes it sound the same anywhere, everywhere

Contacting the author E-Mail: stefan.goehler at gmx.de

My homepage Crossfire Designs is accessible at this URL:
http://www.crossfire-designs.de/
Get SoundLib here:
http://www.soundlib.net/

You will always find the latest version of SoundLib on both pages.
Library SoundLib Classes

-- Sound interface class
-- Organizes streams and samples
-- Sound streaming class
-- Loads and streams sound files
-- Static sound (from stream or memory) class

To get more information about the object layers in SoundLib, please read the chapter .
Understanding the SoundLib class system The SoundLib class system consists of 3 layers.
First the interface layer, represented by the tSoundInterface class. Second the Sound layer (tSoundCollection and derivates), and third the Sound Stream layer (Derivates of tSoundStream).

           tSoundInterface                  ----- Interface layer
           /            \
          /              \
         /               tSoundCollection   ----- Sound Collection layer
 tSoundCollection       /      \
     /     \           /        \
    /  tSoundStream   /     tSoundStream    ----- Sound Stream layer
   /              tSoundStream
tSoundStream

No layer can be initialized before the layer above has been initialized. Changing the volume and other details of a layer above affects all layers below.

Closing layers above WON'T close the lower layers. Instead close all lower layers FIRST.

Adding new sound layers will lower the overall volume. It's recommended not to use more than 2 tSoundCollection layers. One for playing the program's samples, the other for playing e.g. background music. All Sound Object layers should be open at program start, so the volume keeps the same all the time. Definition: Samples In the help file, there's always something about 'bytes, NOT samples'. Well...
to make some things easier to use and to avoid channel problems and similar, all procedures, which have something to do with accessing the sound data, take their values in samples.

A sample is an information unit for all channels at the same time of playing. So if you have an 8 bit Stereo file, the sample sizes 2 bytes (2 channels at each 1 byte). It's the same with 16 bit Mono data (1 channel at 2 bytes).
To give you the method how SoundLib calculates the size of a sample:
(Resolution in bits)/8 * (Number of channels)

So if you want to get to a position within the sample, just give the method the sample position. You don't have to care about if the file is Multichannel or Mono or which resolution it has got. Supported file formats SoundLib does currently support as sample formats WAVe files (uncompressed PCM, 8..16 bits, mono up to multichannel), OGG Vorbis and FLAC files (both any format, also multichannel). Concerning music files, SoundLib does support MODule files with the formats MOD/WOW/NST, S3M and XM. SoundLib supports MOD and S3M surround commands. Additionally, all front speakers are being used for MODule playback (this currently means a center speaker is being used if present).

If you intend to load OGG files, you have to put ogg.dll, vorbis.dll and vorbisfile.dll into the same directory as your application and soundlib.dll. To put it into different words: adding the vorbis DLL files is optional, SoundLib works without them (but can't load OGG then).
The same applies to FLAC: put libflac.dll in the same directory if you need FLAC support. About MODule music files Modules are music files based upon samples and information about how to play them back. They are thus similar to the MIDI concept, except for having their own samples. This lends those files a big advantage: while they keep the size down, they sound the same on every system.
Classic MOD files originate from the Amiga Tracker "The Ultimate Soundtracker" by Karsten Obarski. While the Amiga limited these files somehow to four channels, this limit has been abandoned with PC trackers. The latter also introduced new file formats, like S3M, XM and IT. Except for IT support, which is currently under development, all these formats are supported (MOD and S3M should be perfect, about 90% of XM files play without problems).
While Modules are not free, there are thousands of them available on several sites. You may contact their respective authors in case you want to use them in your production. In many cases stating the authors in your work is enough, such details are mostly provided in the instrument information of these files, which often acts as a built-in "readme" file.

Some points to start:
Modarchive.org
fLAtDiSk
Amiga Music Preservation Archive Including SoundLib to Delphi

Open the project's properties by pressing Shift+CRTL+F11

Select tab "Directories/Conditions"
Add the soundlib header path to the search paths

Add soundlib3dll and vectors to the uses clause
Copy all necessary DLL files into your project's directory

Including SoundLib to Lazarus

Open the project's compiler settings (Project->Compiler Settings)

Select tab "Paths"
Add the soundlib header path to the unit paths

Add soundlib3dll and vectors to the uses clause
Copy all necessary DLL files into your project's directory

Including SoundLib to Microsoft Visual C++ All configuration identifiers have been translated from the german version of MSVC++ 2005, hence names may differ slightly in english version.

Open the project properties by pressing Alt+F7

Add the SoundLib headers path under Project properties->C/C++->Common
Add the SoundLib library path under Project properties->Linker->Common
Add "soundlib.lib" to the additional dependencies under Project properties->Linker->Input

Add soundlib.h and soundlib.cpp to your project's project map (simply drag them)
Copy all necessary DLL files into your project's directory

Error handling SoundLib does error handling by throwing exceptions. This an effective and proven system under both Pascal and C++ compilers.
All errors are strings (C++: char*) messages and usually mean that you can't work any further with the class that generated this message.

Error handling example for Pascal compilers: uses ...,soundlib3dll,sysutils; ... try driver.startplayback(); except on E: Exception do error('Could not initialize sound output ('+E.Message+')'); end; Error handling example for C++ compilers: #include "soundlib.h" #include "iostream" ... try { driver->startplayback(); } catch (char* s) { cout << "Could not initialize sound output: "; cout << s; } Tips & Tricks Class tSoundInterface Class tSoundInterface This class is the father object for any registered sound driver used in SoundLib.

Methods

-- Initializes the tSoundInterface object
-- Closes the tSoundInterface object
-- Starts the sound playback at certain values
-- Stops the playback
-- Returns true if playback running
-- Returns information about playback details
-- Fills record with physical device information
-- Selects physical sound device
-- Returns current device ID
-- Returns number of devices
-- Fills record with physical interface information
-- Selects physical sound device
-- Returns current interface ID
-- Returns number of interfaces
-- Returns current number of mixed buffers
-- Toggles manual/automatic mixing
-- Returns mixed sound data (internal format)
-- Returns mixed sound data (sound device format)
-- Sets listener's speed
-- Sets listener's position
-- Sets listener's orientation
-- Updates all listener values in one function

CONSTANTs

cnt_xxxx -- Output control constant

TYPEs

tDeviceInfo -- Hardware information structure
tInterfaceInfo -- Sound interface information structure

tSoundInterface constructor Initializes the sound interface. constructor create; tSoundInterface(); tSoundInterface destructor Closes the tSoundInterface object, deinitializes interface and variables. destructor destroy; ~tSoundInterface(void); startPlayback Starts the sound playback with the given values. procedure startPlayback(frequency,flags,channels,buffersize,buffers : longword); void startPlayback(unsigned int frequency,unsigned int flags,unsigned int channels,unsigned int buffersize,unsigned int buffers); Frequency is the playback frequency to be used. You can request the possible frequencies by using . If you us the value 0 for Frequency, the driver will automatically use the recommended available value (usually 48Khz, if below, the highest possible value).

Channels forces a certain number of output channels to be used. Set this to 0 to let SoundLib choose the best value (uses system's audio control panel values).

Usable values for channels:

Constant	Explanation
channels_mono	Mono playback
channels_stereo	Stereo playback
channels_4	4 channel playback (L,R,RL,RR)
channels_5	5 channel playback (L,R,C,RL,RR)
channels_6	6 channel playback (L,R,C,RL,RR,CS)
channels_7	7 channel playback (L,R,RL,RR,SL,SR)
channels_lfe	Add LFE channel to output format (NOT recommended)

Please be aware that activating the LFE is currently not recommended. SoundLib automatically chooses if enabling LFE is required for playback.
Buffersize is the buffer size to use in samples. If it is 0, the default buffer size will be used (recommended, uses 1024 samples). This value may be slightly adjusted by the output methods.

Buffers determines the number of buffers used for playback. The default value here is usually 3, but depends on the output interface, operating system and sound card (SoundLib may raise the value if it is known to be necessary).
Please read the "important" section to find out more about buffers and buffer size, they effectively determine the playback quality and why the defaults may not work on some machines due to bad drivers.

Flags are the initialization commands.

Usable flags:

Constant	Explanation
snd_default	Default; 8 bits playback
snd_8bit	8 bit sample output
snd_16bit	16 bit sample output
snd_24bit	24 bit sample output
snd_signed	Use signed samples (recommended for 16 bits+)
snd_monosurround	Surround playback with one surround channel (Dolby Pro Logic compatible)
snd_stereosurround	Surround playback with two surround channels (Dolby Pro Logic II compatible playback)

Many flags can be combined, so will
startPlayback(48000,snd_16bit+snd_signed,channels_stereo); start the playback at 48000 Hz at 16 bit Stereo (signed) with automatic buffer size.

Please be aware that SoundLib may alter some variables in order that the output works. So sometimes an LFE channel will be added (OpenAL multichannel playback), snd_monosurround and snd_stereosurround are ignored (number of channels not equal 2) and the signed flag will usually be set for any format with a resolution above 8 bits. This is the most important method of SoundLib. Please make sure you read everything thoroughly to give the best application experience to your users. If you use the snd_auto flag, the driver will automatically choose the best available settings on your card. SoundLib, however, can not certainly determine if the user has a Pro Logic or Pro Logic II compatible sound set, so choosing the output type should be offered to the user.

Snd_monosurround allows Dolby Pro Logic compatible playback. It requires a Pro Logic capable amplifier to hear the surround signal the right way. However, snd_monosurround also produces a slight surround effect even when not played on a surround capable amplifier. Pro Logic compatible playback is recommended even for use on stereo systems if you use 3D positioning of sounds. The larger the buffer and the more buffers used, the longer the response time until an action is effectively heard. The buffer size determines how many times per seconds newly started sounds will be recognized (default: 48000 Hz / 1024 Samples = 47 ms), this is recommended not to be larger than 2048 Samples, while 512 samples will probably create problems when using too few buffers. The number of buffers determines the lag between when a sound starts and the user hears it (default mean time: 3 buffers, one to be filled with one actively playing: (3-1[fill]-1[play])*47 ms+0.5[average playback lag]*47 ms+(unknown driver lag) = 70.5 ms+(unknown driver lag)).
Using too few buffers (< 3) will create crackle on certain sound cards, sometimes bad written drivers will force you to use even more buffers (probably 5 or more) to have crackle free playback. It is absolutely recommended to let the user choose the number of buffers. While a lag below or equal to 150 ms won't be noticed by most users, values above this will lower the experience. Inform your users about that, push them to install the latest sound drivers if they experience problems with playback! Output of more than 6 channels has not been tested yet. It should work, but there may be unknown bugs. Playback format not supported Number of buffers or buffer size not supported stopPlayback Stops the current playback. procedure stopPlayback; void stopPlayback(); Allows to call again, possibly with other settings. isPlaying Returns true if output interface plays back. function isPlaying; bool isPlaying(); getPlaybackInfo Returns information about current playback details. function getPlaybackInfo : tPlaybackInfo; tPlaybackInfo getPlaybackInfo(); This function is especially useful if you rely on automatic playback initialization. Returned information is only valid if startPlayback has successfully been called. getDeviceInfo Returns information about the currently used sound device. function getDeviceInfo(device : longword) : tSoundDeviceInfo; tSoundDeviceInfo getDeviceInfo(unsigned int device); setDevice Selects physical device for sound output. Usually, SoundLib selects the best fitting (and working) output device for the platform. In case you want to change the device anyway, or you plan to offer functions for user based device selection, use this method.
You can get the list of available devices by using and querying information about these devices using .
Switching devices is not possible while playback. You have to call and start the playback again via . The speed of the switch depends on the output, but generally switching should happen with almost no interrupt in sound playback. procedure setDevice(device : longword); void setDevice(unsigned int device); getDeviceCount Count of available output devices. The available output devices usually refer to all physical sound devices available on your system. function getDeviceCount : longword; unsigned int getDeviceCount(); getCurrentDevice Returns id of currently used output device. function getCurrentDevice : longword; unsigned int getCurrentDevice(); getInterfaceInfo Returns information about the currently used sound interface. function getInterfaceInfo(device : longword) : tSoundInterfaceInfo; tSoundInterfaceInfo getInterfaceInfo(unsigned int device); setDevice Selects interface for sound output. Usually, SoundLib selects the best fitting (and working) interface for the platform. For the Windows platform, this is usually DirectSound. In case you want to change the interface anyway, or you plan to offer functions for user based interface selection, use this method.
You can get the list of available interfaces by using and querying information about these interfaces using .
Switching devices is not possible while playback. You have to call and start the playback again via . Keep in mind that in case you do sound device selection, devices differ depending on the selected interface.
The speed of the switch depends on the output, but generally switching should happen with almost no interrupt in sound playback. procedure setInterface(device : longword); void setInterface(unsigned int device); getInterfaceCount Returns count of available interfaces. The available interfaces refer to the installed sound interfaces on your system (Windows: WaveOut, DirectSound, OpenAL). function getInterfaceCount : longword; unsigned int getInterfaceCount(); getCurrentInterface Returns id of currently used interface. function getCurrentInterface : longword; unsigned int getCurrentInterface(); getMixCount Returns number of mixed buffers since startPlayback. function getMixCount : cardinal; unsigned int getMixCount(); Useful, if you run any sound analyzing software and need to read to current output buffer or you do the mixing manual by using . setMixManual Toggles manual mixing. procedure setMixManual(active : boolean); void setMixManual(bool active); Usually, the sound interface driver does the mixing using a thread. You can switch to manual mixing (without hearing output!) by using this function. Mix and get the sound data with or .
This function is only useful if you want to pass away the output sound data to your own target, for example for a disk writer. getMixData Returns mixing buffer data (internal format). procedure getMixData(dest : pointer); void getMixData(void *dest); Will return internal mixing buffer format. This is either a 32 bits integer format with a 2 bits clipping window (essentially 30 bits, but at this point no clipping has been applied!) or a 32 bits floating point value (single). If getPlaybackInfo.is_fp is true, floating point values are being used.
There are two ways to use this function. In case you use normal playback, ensure that the current buffer changed by observing the number of mixed buffers with .
In case you want to mix your data manually, use to enable manual mixing. You won't hear any output, instead, with every call of getMixData, a new block will be mixed to your buffer.
You need to reserve memory for your destination buffer; in any case, the size has to be getPlaybackInfo.buffersize*getPlaybackInfo.inSampleSize! getMixData Returns mixing buffer data (sound device format). procedure getOutputData(dest : pointer); void getOutputData(void *dest); There are two ways to use this function. In case you use normal playback, ensure that the current buffer changed by observing the number of mixed buffers with .
In case you want to mix your data manually, use to enable manual mixing. You won't hear any output, instead, with every call of getMixData, a new block will be mixed to your buffer.
You need to reserve memory for your destination buffer; in any case, the size has to be getPlaybackInfo.buffersize*getPlaybackInfo.outSampleSize! The returned data is the output format that has been chosen when calling . Since some values may have been adapted by the output driver, ensure you use the values returned by . setListenerPosition Sets listener's position in 3D environment. Given values are based on metres. procedure setListenerPosition(position : tSVector); void setListenerPosition(tSVector position); setListenerOrientation Sets listener's orientation in 3D environment. Values for this function are radian based (2*pi rad = 360 degrees). procedure setListenerOrientation(orientation : tSVector); void setListenerOrientation(tSVector orientation); setListenerVelocity Sets listener's speed in 3D environment. Values for this function are metres per second (m/s). Setting this to anything diffent than zero will create a Doppler effect by shifting the playback speed (function is not affected).
The Doppler effect created by SoundLib is physically not 100% correct. Since playback speed is affected, the according sample will also play faster or slower in addition to its changed frequency. procedure setListenerVelocity(velocity : tSVector); void setListenerVelocity(tSVector velocity); updateListener Sets listener's parameters in 3D environment. Given values for position are based on metres. Values for orientation are radian based (2*pi rad = 360 degrees). Values for speed are metres per second (m/s). Setting speed to anything diffent than zero will create a Doppler effect by shifting the playback speed (function is not affected).
procedure updateListener(position, orientation, speed : tSVector); void updateListener(tSVector position, tSVector orientation, tSVector speed); class tSoundCollection Class tSoundCollection Holds all playback samples, channels and sound files you assign to it. Methods

-- Initializes the tSoundCollection object
-- Closes the tSoundCollection object
-- Sets the volume of a tSoundCollection object channel
-- Returns the volume of a tSoundCollection object channel
-- Changes calculation chunk size
-- Allows No of channel change after Create
-- Returns SoundLib version string
-- Toggle playback interpolation
-- Toggle volume ramping
-- Returns number of mixed blocks
-- Sets size of environment
-- Sets type of environment
-- Returns upper node (tSoundInterface)

tSoundCollection constructor Initializes the tSoundCollection class. constructor create(interface : tSoundInterface;channels : longword); tSoundCollection::tSoundCollection(tSoundInterface *driver,int channels); Interface is the destination sound interface where you want to playback your assigned samples. Channels is the maximum number of channels you want to play at the same time. The sound interface used for initialization has to be initialized first (you have to have called ) Playing more than the given channels at once may result in sound overdrive and hence degrade sound quality! sound interface wasn't initialized tSoundCollection destructor Closes the tSoundCollection object. destructor destroy; tSoundCollection::~tSoundCollection(); Close ANY assigned sound before closing this object any assigned objects were left getUpperNode Returns upper node (tSoundInterface). function getUpperNode : tSoundInterface; tSoundInterface* getUpperNode; setVolume Sets the volume of a channel in the object. procedure setVolume(channel : integer; volume : double); void setVolume(int channel, double volume); Channel represents the output channel. The value chn_left is for left, chn_right for right and so on. Set to chn_all to affect all channels. Volume is a value between 0 and 2. If the value exceeds 1, the maximum sample volume has been reached and the amplitude will be amplified above the normal limit. This MAY result in volume overdrive, similar to a cassette which has been recorded too loud. The more channels you have and the more quiet the sound is, the less is the probability to overdrive. Setting the volume will affect all assigned sounds. It will NOT directly change the volume setting of any assigned sound. It works independend from it. Close ANY assigned sound before closing this object any assigned objects were left getVolume Returns the volume of an output channel of the object. function getVolume(channel : longword) : double; double getVolume(unsigned int channel); Channel represents the output channel. The value chn_left is for left, value chn_right and so on. The return is a value between 0 and 2. If the value exceeds 1, the maximum sample volume has been reached and the amplitude is being amplified. setBufferSize Changes the calculation queue size from the default value. procedure setBufferSize(samples : longword); not implemented Default value: 1024 samples. Useful if one needs to do modifications in a certain time frame, e.g. in MODule-Players. The value "Samples" means how many samples, not bytes or words. setChannels Allows to change the number of channels to be played at the same time after you already setted it in Create. procedure setChannels(channels : longword); not implemented getVersionString Returns SoundLib version string. function getVersionString : pchar; not implemented setInterpolation Toggles the playback interpolation of all assigned sounds. procedure setInterpolation(interpolationtype : longword); void setInterpolation(unsigned int interpolationtype); This feature is turned to INTERPOLATION_LINEAR by default.
Interpolation requires a slighly higher CPU time consumption, but sounds a lot better in most cases. It reduces aliasing, which is especially audible when playing a sample at a lower frequency than the output frequency. setRamping Toggles volume ramping of all assigned sounds. procedure setRamping(active : boolean); void setRamping(bool active); Volume Ramping tries to avoid click sounds appearing when starting a sample or changing its volume.
This feature is turned ON by default. getMixCount Returns continuous count of blocks requested by the software mixer. This function will help to detect if a new block has been mixed or - if in manual mixing mode - a new block should be mixed. Just compare if the returned number is higher than the last number. function getMixCount : cardinal; long long getMixCount(); stopAll Stops all underlying streams and samples. procedure stopAll; void stopAll(); pauseAll Pauses all underlying streams and samples. procedure pauseAll; void pauseAll(); resumeAll Resumes all underlying streams and samples. Resuming applies to all paused streams and samples under the current sound object. procedure resumeAll; void resumeAll(); setEnvironmentType Sets environment type. This function is currently NOT supported. It will set the type of environment. According to this, reflections, echoes and hall effects can be calculated. procedure setEnvironmentType(entype : longword); void setEnvironmentType(unsigned int envtype); setEnvironmentSize Sets environment size. This function is currently NOT supported. It will set the size of the environment. All values are in metres. According to this, reflections, echoes and hall effects can be calculated. procedure setEnvironmentSize(size : tSVector); void setEnvironmentSize(tSVector size); Class tSoundStream Class tSoundStream This class is the father object for any sound streaming class used in SoundLib. Only the creation and desctruction are different. So these are explained separately, additional procedures also. Methods

-- Sound streaming class
-- Connect to sound collection
-- Disconnect from sound collection
-- Returns upper node (tSoundCollection)
-- Returns volume of a channel
-- Sets channel (input to output) mapping
-- Returns channel (input to output) mapping
-- Set buffer size for playback
-- Set panning and volume in a 3D-field
-- Set information about the stream data
-- Get information about the stream data
-- Starts playback of the object
-- Pauses playback of the object
-- Stops playback of the object
-- Returns true if sound is playing
-- Returns true if sound is paused
-- Returns VU meter value
-- Set playback speed
-- Alternative to SetSpeed
-- Toggle playback interpolation
-- Toggle volume ramping
-- Mutes object without affecting volume or playback
-- Set position in sample data
-- Get current position in sample data
-- Get size of stream in samples
-- Sets object position
-- Sets physical orientation of sound object
-- Sets physical velocity of sound object
-- Sets spread angle of sound object
-- Sets physical size of sound object

INHERITED and additional methods

-- Sample playback class
-- Create object, load sample data
-- Close object, unload sample data
-- Set loop within sample data

Types

-- Sound device information record

All other procedures are out of interest for you and only for internal usage. connect Connects stream to sound collection. procedure connect(collection : tSoundCollection); void connect(tSoundCollection collection); This procedure is being used for user streams. After calling this method, certain other methods can be called, like setChannelMapping and setSpeed. Use after you have set sound details using and buffer size using Do not try to connect an already connected stream Do not try to start playback on not fully initialized user streams Stream already connected Collection not properly initialized disconnect Disconnects stream from sound collection. procedure disconnect; void disconnect(); getUpperNode Returns upper node (tSoundCollection). function getUpperNode : tSoundCollection; tSoundCollection* getUpperNode; setBufferSize Sets buffer size of stream. procedure setBufferSize(samples : longword); void setBufferSize(unsigned int samples); This function is mainly for user streams and will set the buffer size of such a stream. This the exact size in samples which will also be used when SoundLib calls user stream class overwritten functions or .
The current buffer size can be obtained by using . Use this for user streams only Changing buffer size of already initialized streams may result in unexpected behaviour setVolume Sets the volume of a channel. procedure setVolume(channel : integer; volume : double); void setVolume(int channel, double volume); Channel represents the output channel. The value chn_left is for left, value chn_right for right, higher values are for other channels. Use chn_all to affect all channels at once.

Volume is a value between 0 and 2. If the value exceeds 1, the maximum sample volume has been reached and the amplitude will be amplified. If too many channels are very loud, this MAY result in distortion, similar to a cassette recorded too loud. Setting the volume here will only affect the specific sound object. Alternatively, you can set each sound's channel position via in a 2D-field. Don't use SetVolume if you use , they will interfere. GetVolume Returns the volume of a channel in the object. function getVolume(channel : longword) : double; double getVolume(unsigned int channel : longword); Channel represents the output channel. The value 0 is for left, value 1 for right, higher values are for other channels.

The return is a value between 0 and 2. If the value exceeds 1, the maximum sample volume has been reached and the amplitude is being amplified. getChannelMapping Set channel (input to output) mapping procedure setChannelMapping(var map : tChannelVolumeMap); void setChannelMapping(tChannelVolumeMap map); Map is a matrix of the type tChannelVolumeMap. This method allows to map any input channel to any output channel. Don't use setChannelMapping if you use 3D positioning, they will interfere. Don't use setChannelMapping if you use , they will interfere. setChannelMapping Set channel (input to output) mapping function getChannelMapping : tChannelVolumeMap; tChannelVolumeMap getChannelMapping(); This method returns the current channel mapping used for this stream. Hint: calling setChannelVolumeMap(getChannelVolumeMap) will reset the volume functions to mapping and return from panning or 3D positioning volume setting. Play Starts the playback of the stream. If the stream was paused, it resumes the playback from the last position, otherwise it starts at the beginning. You can also stop or pause the playback of the object. procedure play; void play(); Pause Pauses the playback of the stream. If the playback has already been paused, it resumes the playback. Alternatively to resume, you can also call . procedure pause; void pause(); Stop Stops the playback of the stream. A call of thereafter starts the playback at the beginning of the object. procedure stop; void play(); IsPlaying Informs if stream is currently playing Returns true if the sound is currently playing. Returns false if module is being paused or stopped or has been stopped. function isPlaying : Boolean; bool isPlaying(); IsPaused Returns if sound playback has been paused. function isPaused : boolean; bool isPaused(); GetVU Returns a value which determines the current sample volume level. Returns a value between 0..1 for VU meter displays. This has currently nothing to do with peak values or dB metrics, but is a simple average of the volume since the last call of this function. function getVU : double; double getVU(); SetPanning Sets the panning and volume of an object in a 3D-field. This function is NOT a good representation of a 3D world since it doesn't set the volume by distance to the listener but by distance to the speaker. For this purpose, use and similar functions instead. X-AXIS (LR) Y | A L 0 R X -1 1 I S LS S RS -1 L: Left speaker R: Right speaker LS: Left surround speaker RS: Right surround speaker S: Surround speaker (when in Pro Logic compatible mode) 0: Center speaker position procedure setPanning(channel : integer; LR,CS,TB,Volume : double); void setPanning(int channel, double lr, double cs, double tb, double volume); LR defines the position between Left and Right, CS the position between Center and Surround, TB the position between top and bottom (will not do anything in this version).

Volume is a value between 0 and 2. If the value exceeds 1, the maximum sample volume has been reached and the amplitude will be amplified. This MAY result in volume overflow, similar to a cassette which has been recorded too loud. It's preferable to use this procedure only when in any surround mode (use mono or stereo surround even with a two-speaker setup, if possible). If you aren't, it's better to set the CS position to zero. TB values are currently ignored but will be supported in the future. Mono and Stereo surround modes (compatible with Dolby Pro Logic (II)) also produces a slight surround effect even when not played on a surround capable amplifier.
Surround modes can be enabled when using . Don't use if you use setPanning. They will interfere! You can't use 3D positioning by using setObject* if you use panning. Once using setPanning, you switch to speaker based volume (3D positioning switches to distance based. getInfo Returns information about the sound stream. function getInfo : tSoundInfo; tSoundInfo getInfo(); Returns information of the type tSoundInfo. setInfo Sets user stream information. procedure setInfo(info : tSoundInfo); void setInfo(tSoundInfo info); Sets details of the user stream by using the type tSoundInfo. All fields except buffersize have to be filled. Use nil/null to mark non-existing text information. Use this for user streams only Changing information of already initialized streams may result in unexpected behaviour SetSpeed Sets the playback speed (pitch and tempo) of the stream. procedure setSpeed(speed : double); void setSpeed(double speed); Setting this value to e.g. 1.2 plays the stream 1.2 times faster.
Used formula: newFrequency := normalFrequency*speed Use SetSpeed OR , not both. They both rely on the same data fields and will interfere. setFrequency Sets the playback frequency of the stream. This affects the playback speed (pitch). procedure setFrequency(frequency : longword); void setFrequency(unsigned int frequency); Use OR SetFrequency, not both. They both rely on the same data fields. SetInterpolation Toggles playback interpolation. This feature is turned to INTERPOLATION_LINEAR by default.
Interpolation requires a slighly higher CPU time consumption, but sounds a lot better in most cases. It reduces aliasing, which is especially audible when playing a sample at a lower frequency than the output frequency. procedure setInterpolation(intpoltype : longword); void setInterpolation(unsigned int intpoltype); setRamping Toggles volume ramping. Volume Ramping tries to avoid click sounds appearing when starting a sample or changing its volume.

This feature is turned ON by default. procedure setRamping(Active : Boolean); void setRamping(bool active); Mute Toggles muting. The sample playback won't stop nor the sample volume values will be affected. You just don't hear the playback anymore. procedure mute(active : boolean); void mute(bool active); setPos Sets the playback position within the sample. procedure setPos(pos : cardinal); procedure setPos(long long pos : longword); Setting positions out of the sample size range will be ignored. The values are NOT byte values, but sample values! getPos Returns the current playback position. function getPos : cardinal; long long getPos(); The returned values are NOT byte values, but sample values! getSize Returns size of the stream. function getSize : cardinal; long long getSize(); The returned values are NOT byte values, but sample values! If the function returns -1, the size can't be determined (e.g. broadcasted streams) setObjectPosition Sets object position in 3D environment. Given values for position are based on metres. Channel determines which channel is affected. Setting channel to -1 will set all channels. Setting relative to true means that the sound playback will not be affected by the listener's position or orientation.
procedure setObjectPosition(channel : integer; position : tSVector; relative : boolean); void setObjectPosition(int channel, tSVector position, bool relative); setObjectOrientation Sets object orientation in 3D environment. Given values for orientation are based on radians.
IMPORTANT: This function is not functional at this moment. All sound sources are handled as POINT SOURCES ONLY. procedure setObjectOrientation(channel : integer; orientation : tSVector); void setObjectOrientation(tSVector orientation); setObjectVelocity Sets object velocity in 3D environment. Given values for velocity are based on metres per second (m/s). Setting this to anything diffent than zero will create a Doppler effect by shifting the playback speed (function is not affected).
Please use chn_all for channel, since this function can't distinguish between different channels at this moment of time.
The Doppler effect created by SoundLib is physically not 100% correct. Since playback speed is affected, the according sample will also play faster or slower in addition to its changed frequency. procedure setObjectVelocity(channel : integer; velocity : tSVector); void setObjectVelocity(tSVector velocity); setObjectSpreadAngle Sets object orientation in 3D environment. Given values for angle are based on radians.
IMPORTANT: This function is not functional at this moment. All sound sources are handled as POINT SOURCES ONLY. procedure setObjectSpreadAngle(channel : integer; angle : double); void setObjectSpreadangle(double angle); setObjectSize Sets object size in 3D environment. Use this function to define volumetric sound sources. Given values for size are based on metres. The position of the object will be interpreted as center of its size.
IMPORTANT: This function is not functional at this moment. All sound sources are handled as POINT SOURCES ONLY. procedure setObjectSize(channel : integer; size : tSVector); void setObjectSize(tSVector size); class tSoundFile Class tSoundFile tSoundFile extends tSoundStream and allows to load various sound files as a stream. Methods in this class:

-- Create object
-- Destroy object

tSoundFile constructor Creates a stream from a sound file. constructor create(dest : tSoundCollection; name : pChar); constructor create(dest : tSoundCollection; s : tStream); tSoundFile(tSoundCollection *sound, char *name); Dest has to be initialized before loading, even if you intend to load the stream to a tSample or play it later.

Loading by file name:
Name holds the file name of the source.

Loading by stream:
S holds a stream source of the type tStream. This allows loading from sources different from files on the disk only (e.g. file libraries or internet).
You can make a sound stream static by using tSample C++ implementation doesn't support file loading from streams at this moment. tSoundFile destructor Closes the tSoundFile object. destructor destroy; ~tSample(void); Destructor doesn't close the files if the file source is of the type tStream. This Destructor needs to be called before closing the tSoundCollection object above! class tSample Class tSample This class makes sound streams static (loads them completely to memory). TSample extends . TSample adds additional functions to the preceding class, mainly to control sound loops. Methods in this class:

-- Create object, load sample data
-- Close object, unload sample data
-- Set loop within sample data

tSample constructor Creates a sample from a stream or from memory. Loading from stream:
Stream holds a sound source of the type tSoundStream. You can destroy the stream after loading it to the sample, since all stream data is being loaded to memory. All files which can be loaded to a stream can act as a source for tSample.

Loading from memory:
Sampledata points to the sample buffer. All contained data will be copied into an internal buffer, so you can dispose your buffer after initialization. Samples specifies the number of samples in your buffer. Flags specify the type of sound information in the buffer by using the same flags as . Frequency specifies the frequency of the sample data.
Channel arrangements: L,R always first, C if format has center channel (5.1,6.1,7.1), then LSurround/RSurround, Csurround if format has surround center (6.1), then Lside/Rside (if 7.1). LFE channel is always last (if included). constructor create(dest : tSoundCollection;source : tSoundStream); constructor create(dest : tSoundCollection sampledata : pointer; samples, flags, channels, frequency : longword); tSample(tSoundCollection *sound,tSoundStream *stream); tSample(tSoundCollection *sound, void *sampledata, unsigned int samples, unsigned int flags, unsigned int channels, unsigned int frequency); Currently only 8 and 16 bits sample data are supported for direct load from memory. Dest is an object of tSoundCollection, which has to be initialized before you initialize tSample. tSample destructor Closes the sample, deallocates used memory. destructor destroy; ~tSample(void); This Destructor needs to be called before closing the tSoundCollection object above! setLoop Sets a loop within the sample. procedure setLoop(start,stop : longword); void setLoop(unsigned int start,unsigned int stop); If start and stop are set to zero, an existing loop will be removed. The values are NOT byte values, but sample values! If you set a loop, the sample won't stop until you called ! Setting positions out of the sound data will be ignored, the start position needs to be smaller than the end position. Types used in SoundLib Variable types Types used for type safe definitions. type sl_int8 = shortint; sl_uint8 = byte; sl_int16 = smallint; sl_uint16 = word; sl_int32 = longint; sl_uint32 = longword; sl_int64 = int64; sl_uint64 = int64; sl_bool = longbool; pointerval = longword; typedef signed char sl_int8; typedef char sl_uint8; typedef short int sl_int16; typedef unsigned short int sl_uint16; typedef long int sl_int32; typedef unsigned long sl_uint32; typedef long long sl_int64; typedef long long sl_uint64; typedef unsigned int sl_bool; Type tSVector 3D vector used for sound positioning in 3D environments. tSVector = array[0..2] of double; typedef double tSVector[3]; type tSoundDeviceInfo Contains information about sound devices. tSoundDeviceInfo = packed record deviceName : pchar; frequencies : record play : record min,max,preferred : sl_uint32; end; end; outputchannels : sl_uint32; lfe : sl_bool; flags : sl_uint32; version : sl_uint32; wavetablesize : sl_uint32; minbufsize, maxbufsize : sl_uint32; end; struct tSoundDeviceInfo { char* deviceName; sl_uint32 frequencies_play_min; sl_uint32 frequencies_play_max; sl_uint32 frequencies_play_preferred; sl_uint32 outputchannels; sl_bool LFE; sl_uint32 flags; sl_uint32 version; sl_uint32 wavetablesize; sl_uint32 minbufsize; sl_uint32 maxbufsize; }; type tSoundInterfaceInfo Contains information about sound interfaces. tSoundInterfaceInfo = packed record interfaceName : pchar; // Name of interface interfaceVersion : pchar; // Version of SL interface driver priority : sl_int32; // Priority of this interface (for auto selection) flags : sl_uint32; // stores information about interface physical : sl_bool; // True if physical device; false for null output end; struct tSoundInterfaceInfo { char* interfaceName; // Name of interface char* interfaceVersion; // Version of SL interface driver sl_int32 priority; // Priority of this interface (for auto selection) sl_uint32 flags; // stores information about interface sl_uint32 physical; // True if physical device; false for null output }; type tPlaybackInfo Contains information about current playback parameters. tPlaybackInfo = packed record frequency : sl_uint32; // Playback frequency resolution : sl_uint32; // Playback resolution outSamplesize : sl_uint32; inSamplesize : sl_uint32; is_fp : sl_bool; // Mixer uses floating point single values inchannels : sl_uint32; // Number of input channels for playback outchannels : sl_uint32; // Number of output playback channels lfe : sl_bool; // If true, last in/outchannel is an LFE channel buffersize : sl_uint32; // Size of playback mixing buffer in samples buffers : sl_uint32; // Number of buffers for playback end; struct tPlaybackInfo { unsigned int frequency; // Playback frequency unsigned int resolution; // Playback resolution unsigned int outSamplesize; unsigned int inSamplesize; unsigned int is_fp; // Playback uses floating point values unsigned int inchannels; // Number of input channels for playback unsigned int outchannels; // Number of output playback channels unsigned int LFE; // If true, last in/outchannel is an LFE channel unsigned int buffersize; // Size of playback mixing buffer in samples unsigned int buffers; // Number of buffers for playback }; type tSoundInfo Contains information about the sound stream. tSoundinfo = packed record name : pchar; // Name of the sound or song creator : pchar; // Creator of that sound or song encoder : pchar; // Encoder/Creation Software string info : pchar; // Additional info field if available length : sl_uint64; // Length of sound or song in samples frequency : sl_uint32; // Original playback frequency of that sound is_fp : sl_bool; // Floating point single values resolution : sl_uint32; // Resolution of sound data channels : sl_int32; // Number of channels this sound contains samplesize : sl_uint32; // Size of a sample in bytes buffersize : sl_uint32; // Stream buffer request size in samples end; struct tSoundInfo { char* name; // Name of the sound or song char* creator; // Creator of that sound or song char* encoder; // Encoder/Creation Software string char* info; // Additional info field if available sl_uint64 length; // Length of sound or song in samples sl_uint32 frequency; // Original playback frequency of that sound sl_uint32 is_fp; // Floating point single values sl_uint32 resolution; // Resolution of sound data sl_int32 channels; // Number of channels this sound contains sl_uint32 samplesize; // Size of a sample in bytes sl_uint32 buffersize; // Stream buffer request size in samples }; The length of the stream will be -1 if length can't be determined (e.g. if it's a broadcasted stream)