.. _alaudiodevice-api: ALAudioDevice API ================= :ref:`Overview ` | API .. seealso:: - :ref:`Loudspeakers Hardware ` Namespace : **AL** .. code-block:: cpp #include Method list ----------- .. cpp:class:: ALAudioDeviceProxy * Methods: * :cpp:func:`ALAudioDeviceProxy::closeAudioInputs` * :cpp:func:`ALAudioDeviceProxy::closeAudioOutputs` * :cpp:func:`ALAudioDeviceProxy::openAudioInputs` * :cpp:func:`ALAudioDeviceProxy::openAudioOutputs` * :cpp:func:`ALAudioDeviceProxy::flushAudioOutputs` * :cpp:func:`ALAudioDeviceProxy::disableEnergyComputation` * :cpp:func:`ALAudioDeviceProxy::enableEnergyComputation` * :cpp:func:`ALAudioDeviceProxy::getFrontMicEnergy` * :cpp:func:`ALAudioDeviceProxy::getLeftMicEnergy` * :cpp:func:`ALAudioDeviceProxy::getRearMicEnergy` * :cpp:func:`ALAudioDeviceProxy::getRightMicEnergy` * :cpp:func:`ALAudioDeviceProxy::getOutputVolume` * :cpp:func:`ALAudioDeviceProxy::getParameter` * :cpp:func:`ALAudioDeviceProxy::playSine` * :cpp:func:`ALAudioDeviceProxy::sendLocalBufferToOutput` * :cpp:func:`ALAudioDeviceProxy::sendRemoteBufferToOutput` * :cpp:func:`ALAudioDeviceProxy::setClientPreferences` * :cpp:func:`ALAudioDeviceProxy::setFileAsInput` * :cpp:func:`ALAudioDeviceProxy::setOutputVolume` * :cpp:func:`ALAudioDeviceProxy::setParameter` * :cpp:func:`ALAudioDeviceProxy::startMicrophonesRecording` * :cpp:func:`ALAudioDeviceProxy::stopMicrophonesRecording` * :cpp:func:`ALAudioDeviceProxy::subscribe` * :cpp:func:`ALAudioDeviceProxy::subscribeLocalModule` * :cpp:func:`ALAudioDeviceProxy::subscribeRemoteModule` * :cpp:func:`ALAudioDeviceProxy::unSubscribeLocalModule` * :cpp:func:`ALAudioDeviceProxy::unSubscribeRemoteModule` * :cpp:func:`ALAudioDeviceProxy::unsubscribe` .. seealso:: * :ref:`Methods inherited from ALModule ` Methods ------- .. cpp:function:: void ALAudioDeviceProxy::closeAudioInputs() Closes the audio device used for capture by **ALAudioDevice**. This method is useful to allow an external program (eg. **arecord**) to access NAO's input device. Note however that a call to this method will prevent every functionnality that uses microphones to work correctly (eg. **ALSpeechRecognition**, **ALAudioSourceLocalization**, etc...). .. cpp:function:: void ALAudioDeviceProxy::closeAudioOutputs() Closes the audio device used for playback by **ALAudioDevice**. This method is useful to allow an external program (eg. **aplay**) to access NAO's output device. Note however that a call to this method will prevent every functionnality that uses microphones to work correctly (eg. **ALTextToSpeech**). .. cpp:function:: void ALAudioDeviceProxy::openAudioInputs() Opens the audio device used for capture by **ALAudioDevice**. This device is open by default. This method is however useful if you used :cpp:func:`ALAudioDeviceProxy::closeAudioInputs` before. .. cpp:function:: void ALAudioDeviceProxy::openAudioOutputs() Opens the audio device used for playback by **ALAudioDevice**. This device is open by default. This method is however useful if you used :cpp:func:`ALAudioDeviceProxy::closeAudioOutputs` before. .. cpp:function:: void ALAudioDeviceProxy::flushAudioOutputs() This methods clears all the samples that may remain to be sent to the loudspeaker. .. cpp:function:: void ALAudioDeviceProxy::disableEnergyComputation() Disables the computation of the energy on each input channel. .. cpp:function:: void ALAudioDeviceProxy::enableEnergyComputation() Enables the computation of the energy on each input channel (this computation is off by default). The result of this computation can be collected by calling: - :cpp:func:`ALAudioDeviceProxy::getFrontMicEnergy` - :cpp:func:`ALAudioDeviceProxy::getRearMicEnergy` - :cpp:func:`ALAudioDeviceProxy::getLeftMicEnergy` - :cpp:func:`ALAudioDeviceProxy::getRightMicEnergy` .. cpp:function:: float ALAudioDeviceProxy::getFrontMicEnergy() Returns the signal energy on the front microphone averaged on a 170ms buffer. The computation of the energy must first be enabled with :cpp:func:`ALAudioDeviceProxy::enableEnergyComputation`. :return: energy [0,32768] .. cpp:function:: float ALAudioDeviceProxy::getLeftMicEnergy() Returns the signal energy on the left microphone averaged on a 170ms buffer. The computation of the energy must first be enabled with :cpp:func:`ALAudioDeviceProxy::enableEnergyComputation`. :return: energy [0,32768] .. cpp:function:: float ALAudioDeviceProxy::getRearMicEnergy() Returns the signal energy on the rear microphone averaged on a 170ms buffer. The computation of the energy must first be enabled with :cpp:func:`ALAudioDeviceProxy::enableEnergyComputation`. :return: energy [0,32768] .. cpp:function:: float ALAudioDeviceProxy::getRightMicEnergy() Returns the signal energy on the right microphone averaged on a 170ms buffer. The computation of the energy must first be enabled with :cpp:func:`ALAudioDeviceProxy::enableEnergyComputation`. :return: energy [0,32768] .. cpp:function:: int ALAudioDeviceProxy::getOutputVolume() Gets the overall output volume of the system. This volume can be set with :cpp:func:`ALAudioDeviceProxy::setOutputVolume`. :return: volume [0,100] .. cpp:function:: int ALAudioDeviceProxy::getParameter(const std::string& parameter) This method returns the internal parameter ('outputSampleRate' or 'inputBufferSize'). The value -1 is returned if the specified parameter is not valid. :param parameter: Name of the parameter :return: value .. cpp:function:: void ALAudioDeviceProxy::playSine(const int& frequence, const int& gain, const int& pan, const float& duration) Play a sine wave which the specified caracteristics. :param frequence: Frequence in Hertz :param gain: Volume between 0 and 100 :param pan: Stereo Pan set to either {-1,0,+1} :param duration: Duration of the sine wave in seconds .. cpp:function:: bool ALAudioDeviceProxy::sendLocalBufferToOutput(const int& nbOfFrames, const int& buffer) By using this method a local module (a module running on NAO) can send a signal to NAO's loudspeakers. This signal should be formated as a 16 bits stereo interleaved buffer. The size of this buffer should also not exceed 16384. :param nbOfFrames: Number of stereo frames contained in the buffer :param buffer: Buffer to send :return: True if the operation is successfull - False otherwise .. cpp:function:: bool ALAudioDeviceProxy::sendRemoteBufferToOutput( const int& nbOfFrames, const AL::ALValue& buffer ) By using this method a remote module (a module running outside NAO) can send a signal to NAO's loudspeakers. This signal should be formated as a 16 bits stereo interleaved buffer. The size of this buffer should also not exceed 16384. :param nbOfFrames: Number of stereo frames contained in the buffer :param buffer: Buffer to send :return: True if the operation is successfull - False otherwise .. cpp:function:: void ALAudioDeviceProxy::setClientPreferences(const std::string & name, const int & sampleRate, const int & channels, const int & deinterleaved) By using this method a module can specify the format of the signal that will be sent after subscribing to **ALAudioDevice**. If no call to this method is made, the default format sent to this module is 4 channels interleaved at 48000Hz. Note that for now, only the following combinaisons are available: - four channels interleaved, 48000Hz, (default setting) - four channels deinterleaved, 48000Hz - one channels (either front, rear, left or right), 16000Hz This call must be made before the call to :cpp:func:`ALAudioDeviceProxy::subscribe` or *startDetection()* to be taken into account. .. code-block:: c++ // This shows how setClientPreferences can be used boost::shared_ptr proxyAudioDevice = getParentBroker()->getProxy("ALAudioDevice"); proxyAudioDevice->callVoid("setClientPreferences", getName(), //Name of this module 48000, //48000 Hz requested (int)ALLCHANNELS, //4 Channels requested 1 //Deinterleaving requested ); :param name: Name of the module. This name must be the same that the one used in *subscribe(const std::string& module)*. :param sampleRate: Sample rate requested can either be 16000Hz or 48000Hz. :param channels: Channel configuration requested can be either AL::ALLCHANNELS, AL::FRONTCHANNEL, AL::LEFTCHANNEL, AL::RIGHTCHANNEL or AL::REARCHANNEL. :param deinterleaved: Only relevant if AL::ALLCHANNEL is requested. .. cpp:function:: void ALAudioDeviceProxy::setFileAsInput(const std::string& fileName) This method notifies **ALAudioDevice** that audio inputs should be read in the specified file instead. The specified sound file must be a .wav file containing 48000Hz, 16bits, 4 channels interleaved signals. :param fileName: Absolute path of the file. .. cpp:function:: void ALAudioDeviceProxy::setOutputVolume(const int& volume) Sets the overall output volume of the system. This volume can be collected with :cpp:func:`ALAudioDeviceProxy::getOutputVolume`. :param volume: Volume [0-100] .. cpp:function:: void ALAudioDeviceProxy::setParameter(const std::string& parameter, const int& value) This method sets the internal parameter ('outputSampleRate' or 'inputBufferSize'). :param parameter: 'outputSampleRate' can be set to either 16000Hz, 22050Hz, 44100Hz or 48000Hz. 'inputBufferSize' can be set to 8192 or 16384. :param value: The value to which the specified parameter should be set. .. cpp:function:: void ALAudioDeviceProxy::startMicrophonesRecording(const std::string& fileName) This method records the signal collected on the NAO's microphones directly into the specified file. If the extension of the specified file is 'wav', data will be recored as a 16 bits, 48000Hz, 4 channels wav file. If the extension of the specified file is 'ogg', data will be recored as a 16 bits, 16000Hz, 1 channels ogg file. :param fileName: Absolute path of the file .. cpp:function:: void ALAudioDeviceProxy::stopMicrophonesRecording() This method stops the recording started by the call to :cpp:func:`ALAudioDeviceProxy::startMicrophonesRecording`. .. cpp:function:: void ALAudioDeviceProxy::subscribe(const std::string& module) This function allows a module which inherits from the ALSoundExtractor class to subscribe to the ALAudioDevice module. Once the module is subscribed, the function 'process' of the module (the module needs to contain one) will be automatically and regularly called with raw data from microphones as inputs. The call to this method can be replaced by a call to *startDetection()* within a NAOqi module that inherits from ALSoundExtractor. The callback function must be declared as follows: .. code-block:: c++ process(const int & nbOfChannels, const int & nbrOfSamplesByChannel, const AL_SOUND_FORMAT * buffer, const ALValue & timeStamp) :param module: This module must inherits from ALSoundExtractor .. cpp:function:: bool ALAudioDeviceProxy::subscribeLocalModule(const AL::ALPtr & module) .. deprecated:: 1.12 use :cpp:func:`ALAudioDeviceProxy::subscribe` instead. :param module: Pointer to the module inheriting from ALSoundExtractor :return: True if module has subscribed successfully - False otherwise .. cpp:function:: bool ALAudioDeviceProxy::subscribeRemoteModule(const std::string& module) .. deprecated:: 1.12 use :cpp:func:`ALAudioDeviceProxy::subscribe` instead. :param module: name of the module inheriting from ALSoundExtractor :return: True if module has subscribed successfully - False otherwise .. cpp:function:: bool ALAudioDeviceProxy::unSubscribeLocalModule(const AL::ALPtr & module) .. deprecated:: 1.12 use :cpp:func:`ALAudioDeviceProxy::unsubscribe` instead. :param module: Pointer to the module inheriting from ALSoundExtractor :return: True if module has unsubscribed successfully - False otherwise .. cpp:function:: bool ALAudioDeviceProxy::unSubscribeRemoteModule(const std::string& module) .. deprecated:: 1.12 use :cpp:func:`ALAudioDeviceProxy::unsubscribe` instead. :param module: Name of the module inheriting from ALSoundExtractor :return: True if module has unsubscribed successfully - False otherwise .. cpp:function:: void ALAudioDeviceProxy::unsubscribe(const std::string& module) This function allows a module which inherits from the ALSoundExtractor class to unsubscribe from the ALAudioDevice module. This stops the regular calls to the module callback "process". The call to this method can be replaced by a call to *stopDetection()* within a NAOqi module that inherits from ALSoundExtractor. :param module: This module must inherits from ALSoundExtractor