SIP SIMPLE Client SDK

== sip_audio_session ==

[[TOC(SipTesting*, sip_*, xcap*,depth=2)]]

=== Description ===

This script can be used for interactive audio session or for scripting alarms. The script returns appropriate shell response codes for failed or successful sessions. The script can be setup to auto answer and auto hangup after predefined number of seconds, detects SIP negative response codes, missing ACK and the lack of RTP media after a session has been established.

[[Image(http://www.tech-invite.com/img/cf3665/cf3665-32.gif)]]

Source code: [source:scripts/sip_audio_session.py scripts/sip_audio_session.py]

{{{

adigeo@ag-oxygen:~$sip_audio_session --help

Usage: sip_audio_session [options] [user@domain]

This script can sit idle waiting for an incoming audio session, or initiate an

outgoing audio session to a SIP address. The program will close the session

and quit when Ctrl+D is pressed.

Options:

  -h, --help            show this help message and exit

  -a NAME, --account=NAME

                        The account name to use for any outgoing traffic. If

                        not supplied, the default account will be used.

  -c [FILE], --config-file=[FILE]

                        The path to a configuration file to use. This

                        overrides the default location of the configuration

                        file.

  -s, --trace-sip       Dump the raw contents of incoming and outgoing SIP

                        messages.

  -j, --trace-pjsip     Print PJSIP logging output.

  -n, --trace-notifications

                        Print all notifications (disabled by default).

  -S, --disable-sound   Disables initializing the sound card.

  --auto-answer         Interval after which to answer an incoming session

                        (disabled by default). If the option is specified but

                        the interval is not, it defaults to 0 (accept the

                        session as soon as it starts ringing).

  --auto-hangup         Interval after which to hang up an established session

                        (applies only to outgoing sessions, disabled by

                        default). If the option is specified but the interval

                        is not, it defaults to 0 (hangup the session as soon

                        as it connects).

  -D, --daemonize       Enabled running this program as a deamon. Note that

                        this forces --disable-sound and --auto-answer.

}}}

=== Example for incoming session ===

{{{

adigeo@ag-imac3:~$sip_audio_session

Using account 31208005169@ag-projects.com

Available control keys:

  h: hang-up the active session

  r: toggle audio recording

  t: toggle SIP trace on the console

  j: toggle PJSIP trace on the console

  <> : adjust echo cancellation

  SPACE: hold/on-hold

  Ctrl-d: quit the program

  ?: display this help message

Succesfully registered using contact "sip:cwntuzyl@192.168.1.6:61163"

Detected NAT type: Port Restricted

Incoming audio session from ""Adrian G." <sip:31208005169@ag-projects.com>", do you want to accept? (y/n)

Session established, using "PCMU" codec at 8000Hz

Audio RTP endpoints 192.168.1.6:50132 <-> 85.17.186.7:53358

Remote SIP User Agent is "CSCO/7"

Session ended by remote party.

Session duration was 3 seconds

}}}

=== Example for outgoing session ===

{{{

adigeo@ag-imac3:~$sip_audio_session ag@ag-projects.com

Using account 31208005169@ag-projects.com

Initiating SIP session from "Adrian G." <sip:31208005169@ag-projects.com> to 

sip:ag@ag-projects.com via udp:81.23.228.150:5060 ...

Available control keys:

  h: hang-up the active session

  r: toggle audio recording

  t: toggle SIP trace on the console

  j: toggle PJSIP trace on the console

  <> : adjust echo cancellation

  SPACE: hold/on-hold

  Ctrl-d: quit the program

  ?: display this help message

Succesfully registered using contact "sip:ztomvpis@192.168.1.6:61215"

Ringing...

Session established, using "speex" codec at 32000Hz

Audio RTP endpoints 192.168.1.6:50374 <-> 81.23.228.129:52156

Remote SIP User Agent is "sip2sip-0.9.0-pjsip-1.0.2-trunk-r2553"

Detected NAT type: Port Restricted

Ending session...

Session ended by local party.

Session duration was 12 seconds

}}}

=== Example for bonjour mode ===

In bonjour mode no server is used. This mode is useful for serverless ad-hoc LAN operation. 

> The actual bonjour protocol that uses multicast DNS to broadcast the contact SIP URIs is not implemented.

[[Image(http://www.tech-invite.com/img/cf3665/cf3665-31.gif)]]

'''Called party'''

{{{

adigeo@ag-imac3:~$sip_audio_session -a bonjour@local

Using account bonjour@local

Listening on "sip:wjnrczhi@192.168.1.6:57624;transport=tls"

Listening on "sip:wjnrczhi@192.168.1.6:57623;transport=tcp"

Listening on "sip:wjnrczhi@192.168.1.6:61994"

Available control keys:

  h: hang-up the active session

  r: toggle audio recording

  t: toggle SIP trace on the console

  j: toggle PJSIP trace on the console

  <> : adjust echo cancellation

  SPACE: hold/on-hold

  Ctrl-d: quit the program

  ?: display this help message

Incoming audio session from "sip:imdyzosg@192.168.1.6", do you want to accept? (y/n)

Session established, using "speex" codec at 32000Hz

Audio RTP endpoints 192.168.1.6:50276 <-> 192.168.1.6:50100

RTP audio stream is encrypted

Remote SIP User Agent is "sip2sip-0.9.0-pjsip-1.0.2-trunk-r2553"

Session ended by remote party.

Session duration was 5 seconds

}}}

'''Calling party'''

{{{

adigeo@ag-imac3:~$sip_audio_session -a bonjour@local "sip:wjnrczhi@192.168.1.6:57624;transport=tls"

Using account bonjour@local

Listening on "sip:imdyzosg@192.168.1.6:57626;transport=tls"

Listening on "sip:imdyzosg@192.168.1.6:57625;transport=tcp"

Listening on "sip:imdyzosg@192.168.1.6:62008"

Initiating SIP session from sip:imdyzosg@192.168.1.6 to sip:wjnrczhi@192.168.1.6:57624;transport=tls via tls:192.168.1.6:57624 ...

Available control keys:

  h: hang-up the active session

  r: toggle audio recording

  t: toggle SIP trace on the console

  j: toggle PJSIP trace on the console

  <> : adjust echo cancellation

  SPACE: hold/on-hold

  Ctrl-d: quit the program

  ?: display this help message

Ringing...

Session established, using "speex" codec at 32000Hz

Audio RTP endpoints 192.168.1.6:50100 <-> 192.168.1.6:50276

RTP audio stream is encrypted

Remote SIP User Agent is "sip2sip-0.9.0-pjsip-1.0.2-trunk-r2553"

Ending session...

Session ended by local party.

Session duration was 5 seconds

}}}

=== Alarm system ===

sip_audio_session script can be used for end-to-end testing of a SIP service. To setup the alarm system start periodically a caller script from a monitoring software using the following arguments:

  {{{

sip_audio_session --auto-hangup user@domain

  }}}

Where the user@domain has been configured as the SIP account of the listener, can be an answering machine on the PSTN network. The caller script hangs up after each call. The shell return code can be used to determine if the session setup has failed. The failure can be caused by timeout, a negative response code or lack of RTP media after the SIP session has been established.

To receive calls and answer them automatically you can also use sip_audio_session script as follows:

  {{{

sip_audio_session --daemonize

  }}}

You must run the script as user root. The --daemonize option puts the client in the background and the logging goes to /var/log/syslog. The program saves its pid file to /var/run/sip_audio_session.pid.