pjsua: The Geek Out SIP Client

There are many options for making SIP/VoIP phone calls over the Internet. There are some with nice user interface, some that get you over almost all the the little hurdles and problems (like for example X-Lite, which you should try if you're ever stuck unable to make a connection, as it seems to work around most problems on its own). But if you're a real geek at heart, there is only one choice: pjsua. pjsua does not have any such timewasting features as a GUI or an address book.

In fact pjsua isn't really meant to be used as an everyday SIP client. It's more of a reference implementation, helping to make sure that a setup is right, helping you to find out what's going on over the (virtual) SIP wire. In the default setup it spews out all kind of connection messages and status things. The configuration is done over command line arguments.

But then, if you want to geek out, you can use pjsua very well as your everyday SIP client. Some of the shortcommings it has, will only help to keep you interested... and in the end you could use one of the language interfaces to the pjsip API to build your own client anyway.

So here's some of my setup: First of all you can also place those command line arguments you need to set up accounts and all that into a file in order to get something like a "saved account preferences". I then call pjsua with only one argument, the path to that file. Next I've created an alias in the shell, to call pjsua with that one argument.

Here is how such a config file could look:

# pjsua SIP client config file
# http://www.pjsip.org/pjsua.htm
--app-log-level=3
# get rid of almost all those status and debug messages
# ------------------------------------------
# when I'm in the office, I hook up to the PBX
--id sip:112@10.0.7.14
--registrar sip:10.0.7.14
--realm 'Registered Users'
# the realm used for our Panasonic PBX
--username 112
--password supersecret
--reg-timeout=1800
# the PBX initially complained about a too short registration
# timeout value, that's why this is here
# ------------------------------------------
--next-account
# ------------------------------------------
# a (hypothetical) SIP provider for my private calls:
--id sip:1234567890@sip.example.com
--registrar sip:sip.example.com
--username 1234567890
--password supersecret
--realm=sip.example.com
# this provider works only with UDP:
--no-tcp
--stun-srv=stun.example.com

You separate different accounts with ``--next-account``, then you probably can set up as many accounts as you want. So, even if this file is just "command line arguments written into a file", it works as well as any Unix config file.

Given that I've used ``--app-log-level=3`` to cut out most of the debug infos, the user interface is much more useable. The debug info *does come in handy*, the moment something doesn't work out, like when I had to find out why the PBX complained about a "too short time given" or something. In everyday usage, I just cut the log-level down and the UI cleans up. It now looks something like this:

+=============================================================================+
|       Call Commands:         |   Buddy, IM & Presence:  |     Account:      |
|                              |                          |                   |
|  m  Make new call            | +b  Add new buddy       .| +a  Add new accnt |
|  M  Make multiple calls      | -b  Delete buddy         | -a  Delete accnt. |
|  a  Answer call              |  i  Send IM              | !a  Modify accnt. |
|  h  Hangup call  (ha=all)    |  s  Subscribe presence   | rr  (Re-)register |
|  H  Hold call                |  u  Unsubscribe presence | ru  Unregister    |
|  v  re-inVite (release hold) |  t  ToGgle Online status |  >  Cycle next ac.|
|  U  send UPDATE              |  T  Set online status    |  [  Cycle prev ac.|
| ],[ Select next/prev call    +--------------------------+-------------------+
|  x  Xfer call                |      Media Commands:     |  Status + Config: |
|  X  Xfer with Replaces       |                          |                   |
|  #  Send RFC 2833 DTMF       | cl  List ports           |  d  Dump status   |
|  *  Send DTMF with INFO      | cc  Connect port         | dd  Dump detailed |
| dq  Dump curr. call quality  | cd  Disconnect port      | dc  Dump config   |
|                              |  V  Adjust audio Volume  |  f  Save config   |
|  S  Send arbitrary REQUEST   | Cp  Codec priorities     |  f  Save config   |
+------------------------------+--------------------------+-------------------+
|  q  QUIT   L  ReLoad   sleep MS   echo [0|1|txt]     n: detect NAT type     |
+=============================================================================+
You have 1 active call
Current call id=1 to sip:00411234567@sip.example.com [CONFIRMED]
>>> h
>>>  14:16:00.784    pjsua_app.c  Call 1 is DISCONNECTED [reason=200 (Normal call clearing)]

At the top is the status-and-command menu, a bit like on a BBS. Below is a prompt. There was a call in progress, which I just hung up using the h command. For example to make another call, I'd enter m, then I would be prompted to enter the number... but pjsua expects a sip-URI, something like the sip:00411234567@sip.example.com in the example screen. I'm not currently using the "buddy list" stuff, probably I could use that as some sort of rudimentare address book. For the few calls that I make currently, I just cut and paste these URLs.

So the usage of this beast can't get any more geeky. What's great though is the technical level: Since pjsip/pjsua is a reference implementation, you get the best that there is. The call quality is great. There are no delays to draw some GUI elements on the screen. (At least on my Macs,) audio just worked. I don't have to live with the limitation of some GUI SIP-clients (like the free X-Lite only giving you one account set up), I have my own geeky limitations!