class methods
- ofSoundStream()
- close()
- getBufferSize()
- getDeviceList()
- getMatchingDevices()
- getNumInputChannels()
- getNumOutputChannels()
- getSampleRate()
- getSoundStream()
- getTickCount()
- printDeviceList()
- setInput()
- setOutput()
- setSoundStream()
- setup()
- start()
- stop()
global functions
ofSoundStream is used for more low-level access to the sound buffer and uses the RtAudio library developed at McGill University by Gary P. Scavone. RtAudio provides an API that lets you control and read data from the audio hardware of your computer. You can manipulate sound with openFrameworks using two approaches. The first option is to directly manipulate the sound data sent from the sound card by using the ofSoundStream class that is included as a part of the core oF distribution. The ofBaseApp class defines two callback methods that let you work with sound: audioIn() is called when the system receives any sound, and audioOut() is called before the system sends sound to the sound card. Both of these callbacks require that the ofSoundStreamSetup() method is called before they will be activated. This tells the RtAudio library to start up, begin processing audio from the system microphone (or line in), and send data to the system sound card: ofSoundStreamSetup(int nOutputs, int nInputs, int sampleRate, int bufferSize, int nBuffers) The ofSoundStreamSetup() method has five parameters: nOutput Is the number of output channels that your computer supports. Usually this will be two: left and right. If you have a surround sound setup, it might be four or five. nInputs - Is the number of input channels that your system uses. sampleRate - Is usually 44,100 kHz, or CD quality, though you may want to make it higher or lower depending on the needs of your application. bufferSize - Is the size of the buffer that your system supports. At the time of writing this book, on any operating system, it’s probably 256 values. nBuffers - Is the number of buffers that your system will create and swap out. The more buffers, the faster your computer will write information into the buffer, but the more memory it will take up. You should probably use two for each channel that you’re using. Here’s an example call:
ofSoundStreamSetup(2, 0, 44100, 256, 4);
The previous snippet will send two channels of stereo sound to the audioIn() method each time the underlying RtAudio library sends information from the sound card. This should be called in the setup method of your openFrameworks application. Now, look at the first of two callback methods. The audioIn() method is called whenever the system microphone detects sound: void audioIn(float * input, int bufferSize, int nChannels) input Is a pointer to the array of data. bufferSize - Is the size of the buffer, the number of floating-point values in the input array. nChannels - Is the number of sound channels represented in the sound data.
The input parameter is always an array of floating-point numbers with the length given in the bufferSize variable. This sounds a little tricky to work with, but as you can see, by using a for loop with a length determined by bufferSize, it isn’t that difficult:
float samples[bufferSize]; for (int i = 0; i < bufferSize; i++) { // increment the sample counter samples[sampleCounter] = input[i]; }
Note that this callback won’t be triggered unless you call ofSoundStreamSetup() with one or two channels set as the input, like so:
ofSoundStreamSetup(0, 2, 44100, 256, 4);
Next, the audioOut() method is called when the system needs one buffer worth of audio to send to the sound card. The method sends the array of floating-point information that represents the buffer of audio data, the size of the buffer, and the number of channels: void audioOut() (float * output, int bufferSize, int nChannels) To have the audioOut() callback triggered by the system, you would need to call ofSoundStreamSetup() with one or two channels in the output. If you want to alter the data before it’s sent to the sound buffer, you must do it within this method.
Documentation from code comments
Gives access to audio input and output devices
ofSoundStream controls access to your computer's audio input and output devices. For example, you could use an ofSoundStream to get live input from a microphone, or generate sound in realtime for your computer's speakers.
A typical openFrameworks app will use just one ofSoundStream, and you might not even need to use this class directly at all if you don't need to query things like the sample rate or buffer size. In order to start receiving or generating audio, your ofApp should implement either ofBaseApp::audioIn() or ofBaseApp::audioOut() respectively, and then call ofSoundStreamSetup(). You can find examples of this in either the audioInputExample or the audioOutputExample.
Starting a stream with 0 input or output channels will prevent audioIn() or audioOut() from being called, respectively.
Some platforms (iOS, for example) will expose additional platform-specific sound stream functionality. See the platform-specific examples for demos.
Warning: Be aware that audioIn() and audioOut() will be called on a different thread from your app's update() / draw() thread.
close()
void ofSoundStream::close()
Documentation from code comments
stops the stream and cleans up its resources.
getBufferSize()
int ofSoundStream::getBufferSize()
Documentation from code comments
Queries the stream's buffer size. \return the current buffer size of the stream.
getDeviceList(...)
vector< ofSoundDevice > ofSoundStream::getDeviceList(ofSoundDevice::Api api=DEFAULT)
Documentation from code comments
Retrieves a list of available audio devices
getMatchingDevices(...)
vector< ofSoundDevice > ofSoundStream::getMatchingDevices(const string &name, unsigned int inChannels, unsigned int outChannels, ofSoundDevice::Api api=DEFAULT)
Documentation from code comments
Get all devices which match the arguments (name can be a partial match)
getNumInputChannels()
int ofSoundStream::getNumInputChannels()
Documentation from code comments
Queries the stream's number of input channels. \return the number of input channels (e.g. 2 for stereo).
getNumOutputChannels()
int ofSoundStream::getNumOutputChannels()
Documentation from code comments
Queries the stream's number of output channels. \return the number of output channels (e.g. 2 for stereo).
getSampleRate()
int ofSoundStream::getSampleRate()
Documentation from code comments
Queries the stream's sample rate \return the current sample rate of the stream \note The returned sample rate may differ from the requested sample rate.
getTickCount()
uint64_t ofSoundStream::getTickCount()
Documentation from code comments
Queries the number of "ticks" passed since the stream started.
This is a representation of how many buffers have passed through the stream since it started. This can be converted to seconds with the following formula:
secondsOfPlayback = (tickCount * bufferSize) / sampleRate
\return number of buffers passed through the stream since it started.
printDeviceList()
void ofSoundStream::printDeviceList()
Documentation from code comments
Prints a list of available audio devices to the console
setInput(...)
void ofSoundStream::setInput(ofBaseSoundInput &soundInput)
Documentation from code comments
Sets the object which will have audioIn() called when the device receives audio.
setInput(...)
void ofSoundStream::setInput(ofBaseSoundInput &soundInput)
Documentation from code comments
Sets the object which will have audioIn() called when the device receives audio.
setOutput(...)
void ofSoundStream::setOutput(ofBaseSoundOutput &soundOutput)
Documentation from code comments
Sets the object which will have audioOut() called when the device requests audio.
setOutput(...)
void ofSoundStream::setOutput(ofBaseSoundOutput &soundOutput)
Documentation from code comments
Sets the object which will have audioOut() called when the device requests audio.
setSoundStream(...)
void ofSoundStream::setSoundStream(shared_ptr< ofBaseSoundStream > soundStreamPtr)
start()
void ofSoundStream::start()
Documentation from code comments
Starts a stream (note that setup() will start the stream on its own).
ofSoundStreamClose()
void ofSoundStreamClose()
Documentation from code comments
Stops the sound stream and also cleans up the stream's resources
ofSoundStreamListDevices()
vector< ofSoundDevice > ofSoundStreamListDevices()
Documentation from code comments
Prints a list of all available audio devices \return all sound devices found on the system
ofSoundStreamStart()
void ofSoundStreamStart()
Documentation from code comments
Starts the sound stream (audioIn() / audioOut() will start being called)
ofSoundStreamStop()
void ofSoundStreamStop()
Documentation from code comments
Stops the sound stream (audioIn() / audioOut() will stop being called)
Last updated Saturday, 17 August 2024 20:47:20 UTC - 99bfb4fd7929e233b87b05758efc36f91505592e
If you have any doubt about the usage of this module you can ask in the forum.
If you want to contribute better documentation or start documenting this section you can do so here
If you find anything wrong with this docs you can report any error by opening an issue