Call Us Today! 877.742.2583




Page tree
Skip to end of metadata
Go to start of metadata

About

mod_portaudio is used for interfacing with sound card. This scenario is usually used when FreeSWITCH is used for a softphone basis, or as an easy way to get a local connection for development.

Interaction with mod_portaudio usually happens at the Freeswitch CLI, including setup, placing calls, answering calls, etc.

Many Softphones use embedded FreeSWITCH and portaudio at their core. Two examples are FSComm a QT4 cross platform communicator and FSClient a Windows .NET 4.0 softphone.

Portaudio (PA) is a cross-platform library.

Beware mod_portaudio recently had a large hunk of code injected into it and the configuration related to Shared Streams. For most scenarios this is not required and my throw (generally harmless) errors. Please see the note on #Shared_Streams_and_Endpoints for more details.

Features

  • Mulitiple calls with hold/call switching.
  • Inbound calls can play a ring file on specified device. (global and per call)
  • Optional hold music for backgrounded calls. (global and per call)
  • Switch audio devices even during a call (see live-stream-switching)
  • DTMF and deaf/mute options
 Click here to expand Table of Contents

Command Reference

  • A device_ident is either part of the device name or the device ID number (prefixed with a #) seen in pa devlist.

pa help - print usage summary

Will show the available commands

pa devlist [xml] - list audio devices

The list will be in the following format: device number;short name;input channels;output channels;freeswitch device configuration

The freeswitch device configuration is a comma separated list of these elements:

r   device is ring device
i   device is input device
o   device is output device

For example:

 

pa indev (device_ident), pa outdev (device_ident), pa switchstream (in_device_ident) (out_device_ident) - Set input/output device streams

Set the input (indev) or output (outdev) audio stream identified by device_ident. pa switchstream can switch both streams at once. These functions can only be use during a call if live-stream-switch configuration option is on.

pa ringdev (device_ident)

Set the device for portaudio to ring on a ringing call.

pa preparestream (in_device_ident) (out_device_ident) - Prepare an input and output device stream for use

Not required but preparing a stream prior to switching to it using the indev/outdev/switchstream allows portaudio to open the stream prior to using it. This makes for much more seamless switching between streams (no audio cut out). You only need to call this once before switching to that stream, streams are kept open until the end of all active calls. Calling it multiple times on the same stream will not cause delays or have negative effects.

pa call (number) [(dialplan)] [(cid_name)] [(cid_num)] - Place a new call

If you currently are on a call the existing call is placed on hold.

pa switch [(call_id)|none] - swap to a new active call

If used without args will switch to the previously active call. If a call_id (from pa list) is past will make that call active. If none is past then all calls are placed on hold.

pa list - view the current calls

pa list

pa dtmf (dtmf_digits) - send a dtmf string (1234) to the current call

pa dtmf 1234

pa answer [(call_id)] - Answer a ringing call

Without a call_id will answer the oldest call, with the call ID will answer that specific call

pa hangup [(call_id)] - End a call

Will end the current call if no ID is given otherwise will end the call with that ID.

pa rescan - Look for new devices

Portaudio assumes devices will not change during use, if they do you will need to use rescan for portaudio to see them. As this causes portaudio to re-init several things it cannot be used during an active call.

pa play [ringtest|(filename)] [(seconds)] [no_close] - Play an audio file or test stream to a device

Allows playing of arbitrary audio on the outdev device, optionally for only a specific number of seconds. no_close causes the audio stream to remain open after playing (allows for faster concurrent playing)

pa playdev (device_ident) [ringtest|(filename)] [(seconds)] [no_close] - Play an audio file or test stream to a specific device

Same as play but takes the device to play to also

pa flags on|off [ear] [mouth] - Set mute or deaf

Mutes the indev so no audio is directed to an active call, or deaf will silence the outdev from playing and audio

pa closestreams - Will close all active open streams

By default all streams are only closed at the end of all active calls, you can force them to close using pa closestreams as long as there is not an active call.

pa dump - Debug dump of all the devices

Dumps a variety of information about the various audio devices PA sees

Sample Implementations

Sample Softphone Configuration

For a sample Softphone configuration, see: Freeswitch_Softphone

Sample Mumble <-> Conference Bridge

Available with full instructions for Linux-based configurations at: Mumble_conference_with_alsa

Sample mod_portaudio intercom (auto answer)

In your dialplan, you can easily setup a portaudio intercom to dial into.

Note, to easily remember the extension number, we use the T9 translate of the acronym "PortAudio INtercom" aka PAIN, which is 7246. Go ahead and dial 7246 and you will immediately be able to talk over the portaudio speaker :-)

Note too, in real life you should probably have some kind of notifying tone so nobody can silently eavesdrop on you.

PA System w/ Chime

A modification to the Intercom sample can be used to feed to a Public Address system. Chime plays before and after paging.

post-chime.lua:

Web GUI

mod_xml_rpc loaded portaudio supplies it's own little GUI http://your.box:8080/api/pa

Install Notes

RHEL/CentOS

When building from source, make sure the "alsa-lib-devel" package is installed or you may get build errors.

Windows

Portaudio for windows by default builds with DirectX used for audio. It seems to provide the best results but it is possible to use the two other audio modes if desired by changing the build options.

Mac OS X

It's not the first time I get tons of errors. So if you see "missing required architecture ppc64 in file" when compile, that means you miss some arch files. I resolved this by edit libs/portaudio/Makefile and changed "-arch x86_64 -arch ppc64 -arch i386 -arch ppc" to "-arch i386".

FreeBSD

Tested on FreeBSD-8.1 AMD64 on hardware which meets the 'Intel HD Audio' spec. Add to the FreeBSD kernel config file:

device snd_hda device sound. Build and install the new kernel, no additional audio config is required. The configuration in portaudio.conf.xml has indev, outdev and ringdev value="0" Also requires: <param name="dual-streams" value="true"/>

-kimc

Reference

portaudio.conf settings

These options are set in the <settings> block of the config.

no-ring-during-call

Prevent an incoming call from ringing the ring device if you are already on a call

no-auto-resume-call

Do not auto resume the last call when the current call ends

live-stream-switch

Allows using the indev,outdev, and switchstream commands during a call

indev, outdev, ringdev

Allows you to preset the specific input and output devices you want portaudio using you can use the same device_ident values as used in the command reference

debug

Set the debug level for portaudio

dialplan

Set the default dialplan for making calls

context

Set the default context for calls

dual-streams

The default value is false which means one thread is handling the audio reading/writing from/to the core. Value true means 2 threads are used instead of one.

Shared Streams and Endpoints

Shared streams and endpoints are completely different than everything else mentioned on this page and are not required for most cases of using portaudio (especially if you are just using FS as a single softphone). They are specifically meant for if you need to use multiple audio devices on different calls at the same time. All of the stream commands above are NOT related to shared streams (just confusing terminology). The only documentation on them is found in the configuration file itself and the code was not tested by a large number of people so stability is not guaranteed. Most of the code paths for shared streams/endpoints are completely different from the rest of portaudio so most of the normal portaudio commands do not work with the shared stream/endpoint system. The commands that related to shared streams are the pa shtreams and pa endpoints commands, not the other stream commands. While you may see errors about shared streams in the console if you do not remove the configuration (per the portaudio.conf note below) these will not stop portaudio from working normally.

portaudio.conf <streams> and <endpoints>

See the note on shared streams and endpoints above. You can safely remove the <streams> and <endpoints> configuration sections from portaudio.conf if you do not need them, otherwise they will throw some console errors by default (that can be ignored).

Custom Events

Portaudio emits several custom events for major changes in portaudio. Every event will contain the pa_call_id variable to indicate which call is being changed.

portaudio::ringing

Is emitted when incoming call is received and portaudio plays the ring on the audio device.

Event portaudio::ringing
portaudio::makecall

Is emitted when a call is placed using pa call API command. fail header is set to true _ONLY_ the mod_portaudio fails to spawn the session, not if call is not completed.

Event portaudio::makecall

portaudio::callheld

Event when call is put on hold

portaudio::callresumed

Event when a call is taken off hold

See Also