mod_portaudio: use default global configuration when configuring streams

               add tons of comments to default portaudio.conf.xml for streams and endpoints

diff --git a/conf/autoload_configs/portaudio.conf.xml b/conf/autoload_configs/portaudio.conf.xml
index 8a5c9b2b4243a01349a5d8151e385d0a09bc1b86..70fd596880bb6f0b82ca8dfa2639bee09bb77eba 100644 (file)
--- a/conf/autoload_configs/portaudio.conf.xml
+++ b/conf/autoload_configs/portaudio.conf.xml
@@ -36,65 +36,185 @@
     <param name="codec-ms" value="20"/>
   </settings>
 
+  <!-- 
+       mod_portaudio "streams"
+
+       The portaudio streams were introduced to support multiple devices and multiple channels in mod_portaudio.
+       For example, if you have a sound card that supports multiple channels or have multiple sound cards and you
+       want to use them at the same time, you can do it configuring streams and endpoints here.
+
+       A "stream" is just a logical container for some settings required by portaudio in order to stream audio and
+       define a friendly name for that configuration. Streams in itself do not do anything else than contain configs. 
+       Once you have your streams defined you can proceed to define "endpoints". Go to the "<endpoints>" section 
+       for more information on endpoints.
+
+       You can use the command "pa shstreams" (portaudio shared streams) to show the configured streams.
+  -->
   <streams>
+       <!--
+       In this example we define 2 streams, one for a usb audio device and another for the usual Mac defaults
+       The name="" attribute in the <stream> tag must uniquely identify the stream configuration and can be
+       later used when creating endpoints in the "instream" and "outstream" parameters of the endpoint.
+       -->
+
+       <!-- This sample "usb1" configuration was tested with a USB Griffin iMic device -->
        <stream name="usb1">
-               <!-- How many channels to open for this stream -->
+               <!-- 
+                       Which device to use for input in this stream 
+                       The value for this parameter must be either in the form '#devno', 
+                       for example '#2' for device number 2, or 'device-name', like 'iMic USB audio system'
+                       The output of command "pa devlist" will show you device names and numbers as enumerated
+                       by portaudio.
+               -->
                <param name="indev" value="#2" />
+
+               <!-- 
+                       Same as the indev but for output. In this case the device is capable of input and output
+                       Some devices are capable of input only or output only (see the default example)
+               -->
                <param name="outdev" value="#2" />
+
+               <!-- The sample rate to use for this stream -->
                <param name="sample-rate" value="48000" />
+
+               <!-- 
+                       Size of the packets in milliseconds. The smaller the number the less latency you'll have
+                       The minimum value is 10ms 
+               -->
                <param name="codec-ms" value="10" />
+
+               <!-- 
+                       How many channels to open for this stream.
+                       If you're device is stereo, you can choose 2 here. However, bear in mind that then
+                       your left and right channels will be separated and when creating endpoints you will have
+                       to either choose the left or right channel. This may or may not be what you want. This separation
+                       means that you can have 2 separate FreeSWITCH calls, listening to one of them in your left channel
+                       and the other in the right chanel.
+               -->
                <param name="channels" value="2" />
        </stream>
+
+       <!-- This default stream was tested using the default Macbook Pro input/output devices -->
        <stream name="default">
-               <!-- How many channels to open for this stream -->
+               <!-- The default system input device -->
                <param name="indev" value="#0" />
+               <!-- The default system output device -->
                <param name="outdev" value="#1" />
+               <!-- CD quality sampling rate ftw -->
                <param name="sample-rate" value="48000" />
+               <!-- Low latency -->
                <param name="codec-ms" value="10" />
+               <!-- Choosing 1 channel allows to hear in both left-right channel when using a headset -->
                <param name="channels" value="1" />
        </stream>
   </streams>
 
+  <!-- 
+       mod_portaudio "endpoints"
+
+       Endpoints is a way to define the input and output that a given portaudio channel will use.
+       There is a lot of flexibility. You can create endpoints which are "send-only", which means
+       audio will be read from FreeSWITCH and sent down to the provided stream, but no audio will
+       be read from that stream and only silence provided back to FreeSWITCH.
+
+               send-only endpoint:
+                       (FS CORE) ->-> audio ->-> sound-card-x
+
+       You can also create a read-only endpoint.
+
+               read-only-endpoint:
+                       (FS CORE) <-<- audio <-<- sound-card-x
+
+       And of course you can create a bidirectional endpoint:
+               bidirectional-endpoint:
+                       (FS CORE) <-> audio <-> sound-card-x
+
+       You can also define a stream which uses only the left or only the right channel of a given device stream.
+       This means you can have 2 SIP calls connected to the same device haring one call in your left ear and
+       the other call to your right ear :-)
+
+       The name="parameter" of the endpoint allows you to use it in the FreeSWITCH dial plan to dial, ie:
+
+       <action application="bridge" data="portaudio/endpoint/usb1out-left" />
+
+       You can use the command "pa endpoints" to show the configured endpoints.
+  -->
   <endpoints>
 
-       <!-- An endpoint is a handle name to represent a logical container to
-            read media from and write media to.
-            The endpoint can use any input/output stream combination for that purpose as 
-            long as the streams match the sampling rate and codec-ms (see <streams> XML tag) -->
+       <!-- 
+               An endpoint is a handle name to refer to a configuration that determines where to read media from 
+               and write media to. The endpoint can use any input/output stream combination for that purpose as 
+               long as the streams match the sampling rate and codec-ms (see <streams> XML tag).
+               You can also omit the instream or the outstream parameter (but obviously not both).
+       -->
+
+       <!-- 
+               Configuration for a "default" bidirectional endpoint that uses the default stream defined previously in
+               the <streams> section.
+        -->
+       <endpoint name="default">
+               <!-- 
+                       The instream, outstream is the name of the stream and channel to use. The stream
+                       name is the same you configured in the <streams> section. This parameters follow 
+                       the syntax <stream-name>:<channel index>. You can omit either the outstream
+                       or the instream, but not both! The channel index is zero-based and must be consistent 
+                       with the number of channels available for that stream (as configured in the <stream> section).
+                       You cannot use index 1 if you chose channels=1 in the stream configuration.
+               -->
+               <param name="instream" value="default:0" />
+               <param name="outstream" value="default:0" />
+       </endpoint>
+
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'send-only' or 'output-only' and uses the channel index 0 (left channel in a stereo device) 
+       -->
        <endpoint name="usb1out-left">
-               <!-- The instream, outstream parameters follow the syntax 
-                    <stream-name>:<channel index> You can omit either the outstream
-                    or the instream, but not both! -->
                <param name="outstream" value="usb1:0" />
        </endpoint>
 
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'send-only' or 'output-only' and uses the channel index 1 (right channel in a stereo device) 
+       -->
        <endpoint name="usb1out-right">
                <param name="outstream" value="usb1:1" />
        </endpoint>
 
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'receive-only' or 'input-only' and uses the channel index 0 (left channel in a stereo device) 
+       -->
        <endpoint name="usb1in-left">
                <param name="instream" value="usb1:0" />
        </endpoint>
 
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'receive-only' or 'input-only' and uses the channel index 1 (right channel in a stereo device) 
+       -->
        <endpoint name="usb1in-right">
                <param name="instream" value="usb1:1" />
        </endpoint>
 
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'bidirectional' or 'send-receive' and uses the channel index 0 (left channel in a stereo device) 
+       -->
        <endpoint name="usb1-left">
                <param name="instream" value="usb1:0" />
                <param name="outstream" value="usb1:0" />
        </endpoint>
 
+       <!-- 
+               This endpoint uses the USB stream defined previously in the <streams> section and
+               is 'bidirectional' or 'send-receive' and uses the channel index 1 (right channel in a stereo device) 
+       -->
        <endpoint name="usb1-right">
                <param name="instream" value="usb1:1" />
                <param name="outstream" value="usb1:1" />
        </endpoint>
 
-       <endpoint name="default">
-               <param name="instream" value="default:0" />
-               <param name="outstream" value="default:0" />
-       </endpoint>
-
   </endpoints>
 
 </configuration>

diff --git a/src/mod/endpoints/mod_portaudio/mod_portaudio.c b/src/mod/endpoints/mod_portaudio/mod_portaudio.c
index 046c5293b06ec23da191eb066eb934ada2a8ed28..21e912e968c68c2ef559bde2a28951d0ffb68bb4 100644 (file)
--- a/src/mod/endpoints/mod_portaudio/mod_portaudio.c
+++ b/src/mod/endpoints/mod_portaudio/mod_portaudio.c
@@ -1415,6 +1415,8 @@ static switch_status_t load_streams(switch_xml_t streams)
                stream->indev = -1;
                stream->outdev = -1;
                stream->sample_rate = globals.sample_rate;
+               stream->codec_ms = globals.codec_ms;
+               stream->channels = 1;
                switch_snprintf(stream->name, sizeof(stream->name), "%s", stream_name);
                for (param = switch_xml_child(mystream, "param"); param; param = param->next) {
                        char *var = (char *) switch_xml_attr_soft(param, "name");