# SoftBank Robotics documentation What's new in NAOqi 2.8?

# ALAudioDevice API

NAOqi Audio - Overview | API

Namespace : AL

    #include <alproxies/alaudiodeviceproxy.h>

## Method list

As any module, this module inherits methods from ALModule API. It also has the following specific methods:

class `ALAudioDeviceProxy`

- `ALAudioDeviceProxy::disableEnergyComputation`
- `ALAudioDeviceProxy::enableEnergyComputation`
- `ALAudioDeviceProxy::flushAudioOutputs`
- `ALAudioDeviceProxy::getFrontMicEnergy`
- `ALAudioDeviceProxy::getLeftMicEnergy`
- `ALAudioDeviceProxy::getOutputVolume`
- `ALAudioDeviceProxy::getParameter`
- `ALAudioDeviceProxy::getRearMicEnergy`
- `ALAudioDeviceProxy::getRightMicEnergy`
- `ALAudioDeviceProxy::isAudioOutMuted`
- `ALAudioDeviceProxy::muteAudioOut`
- `ALAudioDeviceProxy::playSine`
- `ALAudioDeviceProxy::sendLocalBufferToOutput`
- `ALAudioDeviceProxy::sendRemoteBufferToOutput`
- `ALAudioDeviceProxy::setClientPreferences`
- `ALAudioDeviceProxy::setFileAsInput`
- `ALAudioDeviceProxy::setOutputVolume`
- `ALAudioDeviceProxy::setParameter`
- `ALAudioDeviceProxy::startMicrophonesRecording`
- `ALAudioDeviceProxy::stopMicrophonesRecording`
- `ALAudioDeviceProxy::subscribe`
- `ALAudioDeviceProxy::unsubscribe`

Deprecated Parameter

- inputBufferSize: has no effect since version 1.22.

Deprecated Methods

- `ALAudioDeviceProxy::closeAudioInputs` (deprecated)
- `ALAudioDeviceProxy::closeAudioOutputs` (deprecated)
- `ALAudioDeviceProxy::openAudioInputs` (deprecated)
- `ALAudioDeviceProxy::openAudioOutputs` (deprecated)
- `ALAudioDeviceProxy::isInputClosed` (deprecated)
- `ALAudioDeviceProxy::isOutputClosed` (deprecated)

## Signal list

- `ALAudioDeviceProxy::speakersPlaying`

## Methods

void `ALAudioDeviceProxy::``disableEnergyComputation`()

  Disables the computation of the energy on each input channel.

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:

  - `ALAudioDeviceProxy::getFrontMicEnergy`
  - `ALAudioDeviceProxy::getRearMicEnergy`
  - `ALAudioDeviceProxy::getLeftMicEnergy`
  - `ALAudioDeviceProxy::getRightMicEnergy`

void `ALAudioDeviceProxy::``flushAudioOutputs`()

  This methods clears all the samples that may remain to be sent to the loudspeaker.

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 `ALAudioDeviceProxy::enableEnergyComputation`.

  Returns: | energy [0,32768]

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 `ALAudioDeviceProxy::enableEnergyComputation`.

  Returns: | energy [0,32768]

int `ALAudioDeviceProxy::``getOutputVolume`()

  Gets the overall output volume of the system. This volume can be set with `ALAudioDeviceProxy::setOutputVolume`.

  Returns: | volume [0,100]

int `ALAudioDeviceProxy::``getParameter`(const std::string& parameter)

  Deprecated since version 1.22: parameter ‘inputBufferSize’ has no effect now.

  This method returns the internal parameter (‘outputSampleRate’). The value -1 is returned if the specified parameter is not valid.

  Parameters: | parameter – Name of the parameter
  Returns: | value

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 `ALAudioDeviceProxy::enableEnergyComputation`.

  Returns: | energy [0,32768]

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 `ALAudioDeviceProxy::enableEnergyComputation`.

  Returns: | energy [0,32768]

bool `ALAudioDeviceProxy::``isAudioOutMuted`()

  Tells if the audio output device has been muted by a call to `ALAudioDeviceProxy::muteAudioOut`.

  Returns: | True if the output device has been muted, False otherwise.

void `ALAudioDeviceProxy::``muteAudioOut`(const bool& mute)

  Mutes the output device.

  Parameters: | mute – True to mute, False to unmute.

void `ALAudioDeviceProxy::``openAudioInputs`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Opens the audio device used for capture by ALAudioDevice. This device is open by default. This method is however useful if you used `ALAudioDeviceProxy::closeAudioInputs` before.

void `ALAudioDeviceProxy::``openAudioOutputs`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Opens the audio device used for playback by ALAudioDevice. This device is open by default. This method is however useful if you used `ALAudioDeviceProxy::closeAudioOutputs` before.

void `ALAudioDeviceProxy::``playSine`(const int& frequence, const int& gain, const int& pan, const float& duration)

  Play a sine wave which the specified characteristics.

  Parameters: | frequence – Frequence in Hertz gain – Volume between 0 and 100 pan – Stereo Pan set to either {-1,0,+1} duration – Duration of the sine wave in seconds

bool `ALAudioDeviceProxy::``sendLocalBufferToOutput`(const int& nbOfFrames, const int& buffer)

  By using this method a local module (a module running on the robot) can send a signal to the robot’s loudspeakers. This signal should be formated as a 16 bits stereo interleaved buffer. The size of this buffer should also not exceed 16384.

  Parameters: | nbOfFrames – Number of stereo frames contained in the buffer buffer – Memory address of the buffer to send.
  Returns: | True if the operation is successful - False otherwise

  Warning

  This interface can crash the robot if not use correctly! Be very careful with the second parameter.

      // Example: Play a 1kHz sine wav on the robot's loudspeakers during 2s

      int sineTableSize = 1024;
      int outputBufferSize = 16384;
      float sine[sineTableSize];
      int left_phase = 0;
      int right_phase = 0;
      int nbOfOutputChannels=2;
      int sampleRate = 48000;
      int freq =1000;
      float duration = 2.0;
      boost::shared_ptr<ALProxy> audiodeviceProxy = getParentBroker()->getProxy("ALAudioDevice");

      signed short fOutputBuffer[nbOfOutputChannels*outputBufferSize];
      for ( int i=0; i<sineTableSize; i++ )
      {
        sine[i] = float(32767) * sin((double(i)/double(sineTableSize))*M_PI*2.0);
      }

      float ratio= 1.0 /( 1.0 / float(freq) * float(sampleRate) / float(sineTableSize));
      double inc= std::ceil(ratio);
      int nbOfBuffersToSend = std::ceil(duration*sampleRate/outputBufferSize);

      for (int d=0;d<nbOfBuffersToSend;d++)
      {
        for (int i=0;i<nbOfOutputChannels*outputBufferSize;i+=nbOfOutputChannels)
        {
          // left channel
          fOutputBuffer[i] = (signed short)(float(sine[left_phase]));
          // right channel
          fOutputBuffer[i+1] = (signed short)(float(sine[right_phase]));
          left_phase += inc;
          if ( left_phase >= sineTableSize ) left_phase -= sineTableSize;
          right_phase += inc;
          if ( right_phase >= sineTableSize ) right_phase -= sineTableSize;
        }
        audiodeviceProxy->callVoid("sendLocalBufferToOutput",
                                   outputBufferSize,
                                   (int) &fOutputBuffer);
      }

      def onInput_onStart(self):
          self.isRunning = True
          self.ad = ALProxy("ALAudioDevice")
          self.addedPaths = [self.behaviorAbsolutePath()]
          for addedPath in self.addedPaths:
              sys.path.append(addedPath)
          from pydub import AudioSegment
          songPath = os.path.join(self.behaviorAbsolutePath(), "audio_file.wav")
          self.song = AudioSegment.from_wav(songPath)
          try:
              # here is important to note that the second parameter is contigus memory audio data!
              self.ad.sendLocalBufferToOutput(int(self.song.frame_count()), id(self.song._data))
          except Exception as e:
              self.log("error for buffer: " + str(e) + str(id(self.song.data)))
          self.onUnload()
          pass

bool `ALAudioDeviceProxy::``sendRemoteBufferToOutput`(const int& nbOfFrames, const AL::ALValue& buffer)

  By using this method a remote module (a module running outside the robot) can send a signal to the robot’s loudspeakers. This signal should be formated as a 16 bits stereo interleaved buffer. The size of this buffer should also not exceed 16384.

  Parameters: | nbOfFrames – Number of stereo frames contained in the buffer buffer – Buffer to send
  Returns: | True if the operation is successful - False otherwise

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 combinations 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 `ALAudioDeviceProxy::subscribe` or startDetection() to be taken into account.

      // This shows how setClientPreferences can be used
      boost::shared_ptr<ALProxy> proxyAudioDevice = getParentBroker()->getProxy("ALAudioDevice");
      proxyAudioDevice->callVoid("setClientPreferences",
                                 getName(),                //Name of this module
                                 48000,                    //48000 Hz requested
                                 (int)ALLCHANNELS,         //4 Channels requested
                                 1                         //Deinterleaving requested
                                 );

  Parameters: | name – Name of the module. This name must be the same that the one used in subscribe(const std::string& module). sampleRate – Sample rate requested can either be 16000Hz or 48000Hz. channels – Channel configuration requested can be either AL::ALLCHANNELS, AL::FRONTCHANNEL, AL::LEFTCHANNEL, AL::RIGHTCHANNEL or AL::REARCHANNEL. deinterleaved – Only relevant if AL::ALLCHANNEL is requested.

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.

  Parameters: | fileName – Absolute path of the file.

void `ALAudioDeviceProxy::``setOutputVolume`(const int& volume)

  Sets the overall output volume of the system. This volume can be collected with `ALAudioDeviceProxy::getOutputVolume`.

  Parameters: | volume – Volume [0-100]

void `ALAudioDeviceProxy::``setParameter`(const std::string& parameter, const int& value)

  Deprecated since version 1.22: parameter ‘inputBufferSize’ has no effect now.

  This method sets the internal parameter (‘outputSampleRate’).

  Parameters: | parameter – ‘outputSampleRate’ can be set to either 16000Hz, 22050Hz, 44100Hz or 48000Hz. value – The value to which the specified parameter should be set.

void `ALAudioDeviceProxy::``startMicrophonesRecording`(const std::string& fileName)

  This method records the signal collected on the 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.

  Parameters: | fileName – Absolute path of the file

void `ALAudioDeviceProxy::``stopMicrophonesRecording`()

  This method stops the recording started by the call to `ALAudioDeviceProxy::startMicrophonesRecording`.

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:

      process(const int & nbOfChannels, const int & nbrOfSamplesByChannel, const AL_SOUND_FORMAT * buffer, const ALValue & timeStamp)

  Parameters: | module – This module must inherits from ALSoundExtractor

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.

  Parameters: | module – This module must inherits from ALSoundExtractor

void `ALAudioDeviceProxy::``closeAudioInputs`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Closes the audio device used for capture by ALAudioDevice. This method is useful to allow an external program (e.g. arecord) to access the input device of the robot. Note however that a call to this method will prevent every functionality that uses microphones to work correctly (e.g. ALSpeechRecognition, ALAudioSourceLocalization, etc...).

void `ALAudioDeviceProxy::``closeAudioOutputs`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Closes the audio device used for playback by ALAudioDevice. This method is useful to allow an external program (e.g. aplay) to access the output device of the robot. Note however that a call to this method will prevent every functionality that uses microphones to work correctly (e.g. ALTextToSpeech).

bool `ALAudioDeviceProxy::``isInputClosed`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Tells if the audio input device has been closed by a call to `ALAudioDeviceProxy::closeAudioInputs`.

  Returns: | True if the input device has been closed, False otherwise.

bool `ALAudioDeviceProxy::``isOutputClosed`()

  Deprecated since version 1.22: due to technical improvements, closing the audio is not necessary anymore.

  Tells if the audio output device has been closed by a call to `ALAudioDeviceProxy::closeAudioOutputs`.

  Returns: | True if the output device has been closed, False otherwise.

## Signals

qi::Signal<bool> `ALAudioDeviceProxy::``speakersPlaying`

  Signal emitted every 130 ms while the robot is playing sound.

Glossary Site map Index Support Contact Legal Notices