General:
Introduction
Features of irrKlang
Links into the API documentation
Tips and Tricks
Programming irrKlang:
Starting up the Engine
Playing Sounds
Influencing Sounds during Playback
Using Sound Sources
3D Sound
Removing Sounds
Using Sound Events
Memory Playback
Sound Effects
Overriding File Access
Adding Audio Decoders
Creating irrKlang Plugins
Using irrKlang as static Lib
Enumerating sound devices
Recording Audio
Unicode support
Short full examples:
Quick Start Example
Quick Start Example 2
Welcome to the irrKlang API documentation. This page should give you a short overview over irrKlang, the high level audio library. In this documentation files you'll find any information you'll need to develop applications with irrKlang using C++. If you are looking for a tutorial on how to start, you'll find some on the homepage of irrKlang at http://www.ambiera.com/irrklang or inside the SDK in the directory .
The irrKlang library is intended to be an easy-to-use 3d and 2d sound engine, so this documentation is an important part of it. If you have any questions or suggestions, please take a look into the ambiera.com forum or just send a mail.
irrKlang is a high level 2D and 3D cross platform sound engine and audio library. It has a very simply object orientated interface and was designed to be used in games, scientific simulations, architectural visualizations and similar. irrKlang plays several file formats such as
It is also able to run on different operating systems and use several output drivers:
irrklang::ISoundEngine: The main class of irrKlang.
Class list: List of all classes with descriptions.
Class members: Good place to find forgotten features.
This section lists a few tips you might consider when implementing the sound part of your application using irrKlang:
irrKlang is designed so that it is very easy to achieve everything, its interface should be very simple to use. The Quick Start Example shows how to play and mp3 file, and there is another example, Quick Start Example 2, showing some few more details.
To start up the sound engine, you simply need to call createIrrKlangDevice(). To shut it down, call IRefCounted::drop():
#include <irrKlang.h> // ... // start up the engine irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice(); // ... // after finished, // close the engine again, similar as calling 'delete' engine->drop();
The createIrrKlangDevice() function also accepts several parameters, so that you can specify which sound driver should be used, if plugins should be used, if irrKlang should run in multithreaded mode, and similar.
Once you have irrKlang running (like in Starting up the Engine), you can start playing sounds:
engine->play2D("someSoundFile.wav");
This works with all supported file types. You can replace "someSoundFile.wav" with "someSoundFile.mp3", or "someSoundFile.ogg", for example.
To play a sound looped, set the second parameter to 'true':
engine->play2D("myMusic.mp3", true);
To stop this looping sound again, use engine->stopAllSounds() to stop all sounds, or irrklang::ISound::stop() if you only want to stop that single sound. Influencing Sounds during Playback shows how to get to that ISound interface.
To influence parameters of the sound such as pan, volume or playback speed during runtime, to get the play position or stop playback of single playing sounds, you can use the irrklang::ISound interface. irrklang::ISoundEngine::play2D (but also play3D) returns a pointer to this interface when its third ('startPaused') or fourth ('track') parameter was set to true:
irrklang::ISound* snd = engine->play2D("myMusic.mp3", true, false, true); // ... if (snd) snd->setVolume(someNewValue); // ... if (snd) { snd->drop(); // don't forget to release the pointer once it is no longer needed by you snd = 0; }
The irrklang::ISound interface can also be used to test if the sound has been finished, set event receivers, pause and unpause sounds and similar.
To be more flexible playing back sounds, irrKlang uses the concept of sound sources. A sound source can be simply the name of a sound file, such as "sound.wav". It is possible to add "sound.wav" as sound source to irrKlang, and play it using the sound source pointer:
irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); engine->play2D(shootSound); // note: you don't need to drop() the shootSound if you don't use it anymore
The advantage of using irrklang::ISoundSource is that it is possible to set default values for this source, such as volume or distances if it should be used as 3D sound:
irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); shootSound->setDefaultVolume(0.5f); // shootSound will now be played with half its sound volume by default: engine->play2D(shootSound);
It is also possible to have multiple settings for the same sound file:
irrklang::ISoundSource* shootSound = engine->addSoundSourceFromFile("shoot.wav"); irrklang::ISoundSource* shootSound2 = engine->addSoundSourceAlias(shootSound, "silentShoot"); shootSound2->setDefaultVolume(0.1f); // shootSound will now be played with 100% of its sound volume by default, // shootSound2 will now be played 10% of its sound volume by default. It is // also possible to play it using engine->play("silentShoot"), now.
Using addSoundSourceFromMemory(), it is also possible to play sounds back directly from memory, without files. Of course, it is not necessary to use sound sources. Using irrklang::ISound, it is possible to change the settings of all sounds, too. But using sound sources, it is not necessary to do this every time a sound is played.
There is nothing difficult in playing sounds in 3D using irrKlang: Instead of using irrklang::ISoundEngine::play2D(), just use irrklang::ISoundEngine::play3D(), which takes a 3D position as additional parameter:
irrklang::vec3df position(23,70,90); engine->play3D("yourSound.wav", position);
But to make it sound realistic, you need to set a minimal sound distance: If your sound is caused by a bee, it will usually have a smaller sound radius than for example a jet engine. You can set default values using sound sources (see Using Sound Sources) or set these values after you have started the sound paused:
irrklang::vec3df position(23,70,90); // start the sound paused: irrklang::ISound* snd = engine->play3D("yourSound.wav", position, false, true); if (snd) { snd->setMinDistance(30.0f); // a loud sound snd->setIsPaused(false); // unpause the sound }
There is also the possibility to change the maxDistance, but it is only necessary to change this in very rare cicumstances. If the sound moves, it is also a good idea to update its position from time to time:
if (snd) snd->setPosition(newPosition);
And don't forget to drop() the sound after you don't need it anymore. If you do, it's nothing severe because irrKlang will still clean up the sounds resources after it has finished, but you still would waste some few bytes of memory:
if (snd) { snd->drop(); snd = 0; }
To update the position of yourself, the listener of the 3D sounds, use this from time to time:
irrklang::vec3df position(0,0,0); // position of the listener irrklang::vec3df lookDirection(10,0,10); // the direction the listener looks into irrklang::vec3df velPerSecond(0,0,0); // only relevant for doppler effects irrklang::vec3df upVector(0,1,0); // where 'up' is in your 3D scene engine->setListenerPosition(position, lookDirection, velPerSecond, upVector);
irrKlang manages the memory usage of sounds by itself, so usually, you don't have to care about memory management. But if you know you need to reduce the amount of used memory at a certain point in your program, you can do this:
engine->removeAllSoundSources();
This will remove all sounds and also cause all sounds to be stopped. To remove single sounds from the engine, use:
engine->removeSoundSource(pointerToSomeSoundSource); // or: engine->removeSoundSource("nameOfASoundFile.wav");
Note: Only removing buffered sounds will reduce the amount of memory used by irrKlang, streamed sounds don't occupy a lot of memory when they are not played.
In order to wait for a sound to be finished, it is simply possible to poll irrklang::ISound::isFinished(). Another way would be to constantly use irrklang::ISoundEngine::isCurrentlyPlaying to test wether a sound with that name or source is currently playing. But of course, an event based approach is a lot nicer. That's why irrKlang supports sound events.
The key to sound events is the method setSoundStopEventReceiver of the irrklang::ISound interface (See Influencing Sounds during Playback on how to get the ISound interface):
irrklang::ISound* snd = engine->play2D("speech.mp3", false, false, true); if (snd) snd->setSoundStopEventReceiver(yourEventReceiver, 0);
The optional second parameter of setSoundStopEventReceiver is a user pointer, set it to whatever you like. 'yourEventReceiver' must be an implementation of the irrklang::ISoundStopEventReceiver interface.
A whole implementation could look like this:
class MySoundEndReceiver : public irrklang::ISoundStopEventReceiver { public: virtual void OnSoundStopped (irrklang::ISound* sound, irrklang::E_STOP_EVENT_CAUSE reason, void* userData) { // called when the sound has ended playing printf("sound has ended"); } } // ... MySoundEndReceiver* myReceiver = new MySoundEndReceiver(); irrklang::ISound* snd = engine->play2D("speech.mp3", false, false, true); if (snd) snd->setSoundStopEventReceiver(myReceiver); myReceiver->drop(); // similar to delete
The irrklang::ISoundStopEventReceiver::OnSoundStopped() method is guaranteed to be called when a sound or sound stream has stopped, either because the sound reached its playback end, its sound source was removed, ISoundEngine::stopAllSounds() has been called or the whole engine was deleted.
Using irrKlang, it is easily possible to play sounds directly from memory instead out of files. There is an example project showing this: In the SDK, in /examples/03.MemoryPlayback. But in short, it simply works by adding the memory as sound source (See Using Sound Sources for details about sound sources):
engine->addSoundSourceFromMemory(pointerToMemory, memorySize, "nameforthesound.wav"); // play sound now engine->play2D("nameforthesound.wav");
Or using a sound source pointer:
irrklang::ISoundSource* snd = engine->addSoundSourceFromMemory(pointerToMemory, memorySize, "nameforthesound.wav"); // play sound now engine->play2D(snd);
Note: It is also possible to overwrite the file access directly, don't use this Memory Playback feature for this. See Overriding File Access for details.
irrKlang supports the effects Chorus, Compressor, Distortion, Echo, Flanger Gargle, 3DL2Reverb, ParamEq and WavesReverb, when using the sound driver irrklang::ESOD_DIRECT_SOUND_8, which selected by default when using Windows.
Using the irrklang::ISound interface, you can optain the irrklang::ISoundEffectControl interface if the sound device supports sound effects and the last parameter ('enableSoundEffects') was set to true when calling play2D():
irrklang::ISound* snd = engine->play2D("sound.wav", true, false, true, ESM_AUTO_DETECT, true); if (snd) { irrklang::ISoundEffectControl* fx = snd->getSoundEffectControl(); if (fx) { // enable the echo sound effect for this sound fx->enableEchoSoundEffect(); } } snd->drop();
This enabled the echo sound effect for this sound. The method also supports a lot of parameters, and can be called multiple times to change those parameters over time if wished. There are a lot of other sound effects, see irrklang::ISoundEffectControl for details.
It is possible to let irrKlang use your own file access functions. This is useful if you want to read sounds from other sources than just files, for example from custom internet streams or an own encypted archive format. There is an example in the SDK in examples/04.OverrideFileAccess which shows this as well.
The only thing to do for this is to implement your own irrklang::IFileFactory, and set it in irrKlang using irrklang::ISoundEngine::addFileFactory():
// a class implementing the IFileFactory interface to override irrklang file access class CMyFileFactory : public irrklang::IFileFactory { public: // Opens a file for read access. Simply return 0 if file not found. virtual irrklang::IFileReader* createFileReader(const ik_c8* filename) { // return your own irrklang::IFileReader implementation here, for example like that: return new CMyReadFile(filename); } }; // ... CMyFileFactory* myFactory = new CMyFileFactory(); engine->addFileFactory(myFactory); myFactory->drop();
For a full example implementation, just take a look into the SDK in examples/04.OverrideFileAccess.
To add support for new file formats, it is possible to add new audio decoders to irrKlang. The only thing to do for this is to implement your own irrklang::IAudioStreamLoader, and irrklang::IAudioStream, and set it in irrKlang using irrklang::ISoundEngine::registerAudioStreamLoader():
class NewAudioStreamLoader : public irrklang::IAudioStreamLoader { // ... returns NewAudioDecoder and the used file name suffices. }; class NewAudioDecoder : public irrklang::IAudioStream { public: // ... decodes the new file format }; // ... NewAudioDecoder* loader = new NewAudioDecoder(); engine->registerAudioStreamLoader(loader); loader->drop();
There is an example audio decoder and loader with full source in plugins/ikpMP3, which adds MP3 audio decoding capabilities to irrKlang.
irrKlang plugins are ikp*.dll (Windows), ikp*.so (Unix) or ikp*.dylib (MacOS) files which are loaded by irrKlang at startup when the irrklang::ESEO_LOAD_PLUGINS was set (which is default) or irrklang::ISoundEngine::loadPlugins() was called.
The plugin only needs to contain the following function which will be called by irrKlang:
#ifdef WIN32 // Windows version __declspec(dllexport) void __stdcall irrKlangPluginInit(ISoundEngine* engine, const char* version) #else // Linux and Mac OS version void irrKlangPluginInit(ISoundEngine* engine, const char* version) #endif { // your implementation here }
In there, it is for example possible to extend irrKlang with new audio decoders, see Adding Audio Decoders for details.
There is an example plugin with full source in plugins/ikpMP3, which adds MP3 audio decoding capabilities to irrKlang.
If you don't want to use the irrKlang.DLL file and link irrKlang statically, you can do this by simply linking to the irrKlang.lib in the bin/win32-visualstudio_lib folder. This folder will only available in the pro versions of irrKlang, which you get when purchasing an irrKlang license.
To use irrKlang in this way, just define IRRKLANG_STATIC before including irrklang.h, like this:
#define IRRKLANG_STATIC #include <irrKlang.h>
Of course, IRRKLANG_STATIC can also simply be defined in the project/compiler settings instead of in the source file.
irrKlang uses the default sound device when playing sound when started without parameters. But if you want irrKlang to playback sound on one specific sound device, you may want to enumerate the available sound devices on your system and select one of them. Use irrklang::createSoundDeviceList() for this. This example code shows how to print a list of all available sound devices on the current system and lets the user choose one of them:
int main(int argc, const char** argv) { // enumerate devices irrklang::ISoundDeviceList* deviceList = createSoundDeviceList(); // ask user for a sound device printf("Devices available:\n\n"); for (int i=0; i<deviceList->getDeviceCount(); ++i) printf("%d: %s\n", i, deviceList->getDeviceDescription(i)); printf("\nselect a device using the number (or press any key to use default):\n\n"); int deviceNumber = getch() - '0'; // create device with the selected driver const char* deviceID = deviceList->getDeviceID(deviceNumber); ISoundEngine* engine = createIrrKlangDevice(irrklang::ESOD_AUTO_DETECT, irrklang::ESEO_DEFAULT_OPTIONS, deviceID); deviceList->drop(); // delete device list // ... use engine now }
In this way, it is also possible to play back sound using two devices at the same time: Simply create two irrKlang devices with each a different deviceID.
Note: createSoundDeviceList() takes a driver type parameter (such as irrklang::ESOD_DIRECT_SOUND8), which you have to set to the same value as the first parameter you want to use with createIrrKlangDevice(), if it is other than irrklang::ESOD_AUTO_DETECT.
irrKlang is able to record audio from sound capturing devices such as microphones (currently only supported in windows). Use the irrklang::IAudioRecorder interface to do this. The following example shows how to record some audio and play it back again using the engine:
int main(int argc, const char** argv) { irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice(); irrklang::IAudioRecorder* recorder = irrklang::createIrrKlangAudioRecorder(engine); if (!engine || !recorder) { printf("Could not create audio engine or audio recoder\n"); return 1; } printf("\nPress any key to start recording audio...\n"); getch(); // record some audio recorder->startRecordingBufferedAudio(); printf("\nRECORDING. Press any key to stop...\n"); getch(); recorder->stopRecordingAudio(); printf("\nRecording done, recorded %dms of audio.\n", recorder->getAudioFormat().FrameCount * 1000 / recorder->getAudioFormat().SampleRate ); printf("Press any key to play back recorded audio...\n"); getch(); // play the recorded audio recorder->addSoundSourceFromRecordedAudio("myRecordedVoice"); engine->play2D("myRecordedVoice", true); // wait until user presses a key printf("\nPress any key to quit..."); getch(); recorder->drop(); engine->drop(); // delete engine return 0; }
In order to select a specific audio capturing device for recording, it is necessary to enumerate the available devices. Simply replace the first to lines of code of the example above with code like this to list all devices and select one:
// enumerate recording devices and ask user to select one irrklang::ISoundDeviceList* deviceList = irrklang::createAudioRecorderDeviceList(); printf("Devices available:\n\n"); for (int i=0; i<deviceList->getDeviceCount(); ++i) printf("%d: %s\n", i, deviceList->getDeviceDescription(i)); printf("\nselect a device using the number (or press any key to use default):\n\n"); int deviceNumber = getch() - '0'; // create recording device with the selected driver const char* deviceID = deviceList->getDeviceID(deviceNumber); irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice(); irrklang::IAudioRecorder* recorder = irrklang::createIrrKlangAudioRecorder(engine, irrklang::ESOD_AUTO_DETECT, deviceID);
irrKlang supports unicode on all operating systems. Internally, it uses UTF8, and all functions accepting strings and file names take UTF8 strings. If you are running irrKlang on Windows, and are using the UNICODE define or using wchar_t* strings directly, you can do this as well. Use the irrKlang provided function makeUTF8fromUTF16string() to convert your wchar_t* string to a char* string.
This example shows how:
const wchar_t* yourFilename = L"SomeUnicodeFilename.wav"; // assuming this is the file name you get from some of your functions const int nBufferSize = 2048; // large enough, but best would be wcslen(yourFilename)*3. char strBuffer[nBufferSize]; irrklang::makeUTF8fromUTF16string(yourFilename, strBuffer, nBufferSize); // now the converted file name is in strBuffer. We can play it for example now: engine->play2D(strBuffer);
Of course, you can use any other unicode converion function for this. makeUTF8fromUTF16string() is only provided for convenience.
To simply start the engine and play a mp3 file, use code like this:
#include <iostream> #include <irrKlang.h> #pragma comment(lib, "irrKlang.lib") // link with irrKlang.dll int main(int argc, const char** argv) { irrklang::ISoundEngine* engine = irrklang::createIrrKlangDevice(); if (!engine) return 1; // could not start engine engine->play2D("someMusic.mp3", true); // play some mp3 file, looped std::cin.get(); // wait until user presses a key engine->drop(); // delete engine return 0; }
A mp3 file is being played until the user presses enter in this example. As you can see, irrKlang uses namespaces, all of the classes are located in the namespace irrklang. If you don't want to write this in front of every class and function you are using, simply write
using namespace irrklang;
in front of your code, as also shown in the next example.
The following is a simple interactive application, starting up the sound engine and playing some streaming .ogg music file and a .wav sound effect every time the user presses a key.
#include <iostream> #include <irrKlang.h> using namespace irrklang; #pragma comment(lib, "irrKlang.lib") // link with irrKlang.dll int main(int argc, const char** argv) { // start the sound engine with default parameters ISoundEngine* engine = createIrrKlangDevice(); if (!engine) return 0; // error starting up the engine // play some sound stream, looped engine->play2D("../../media/helltroopers.ogg", true); std::cout << "\nHello World!\n"; char i = 0; while(i != 'q') { std::cout << "Press any key to play some sound, press 'q' to quit.\n"; // play a single sound engine->play2D("../../media/bell.wav"); std::cin >> i; // wait for user to press some key } engine->drop(); // delete engine return 0; }
 |
The irrKlang
Engine Documentation © 2003-2018 by Nikolaus Gebhardt. Generated
by Doxygen
(1.6.1) |