pjsua as a testing client

原文, original

PJSIP: Command-Line VoIP Client for Linux

January 20, 2008 – 11:10 pm

Some time ago, I was tasked at work with finding an IP telephony client that used the SIP protocol, ran on linux, and did everything from the command line. The goal was to have a program that could be deployed at remote networks to test the quality and performance of VoIP calls between the remote site and our central Asterisk VoIP server. I thought this would be an easy task, but it turned out to be far more difficult to find a client that had all of the necessary features. There are a few command-line SIP clients for linux, and most of them are designed for testing, but paradoxically this means that their feature sets have been limited to simply making a call and playing some sort of wav file or reading text from a file. This was handy for sure, but we needed something that would for all intents and purposes be a full-fledged SIP phone that we could control remotely either with a web script or through SSH.

Yesterday I finally stumbled across a program that fit the bill. More than just a program with a static set of features, PJSIP contains a complete library of functions so that you can build your own programs based on the SIP protocol in practically any language you like. However, it does come with several example applications you can build and use on multiple platforms. The primary application is called pjsua, and contains a fully-featured, menu-based interface for the command line. This program alone did everything we needed and more.

Pjsua is incredibly easy to use. Run without any options, it presents you with a nice menu-interface where you can add accounts, add and view the status of other SIP users, make calls, transfer calls, put calls on hold, conference calls, and even pipe in audio from wav files. If you’re in a hurry, you can make a call with the following short and simple command:

pjsua sip:<user>@<domain>

Or if you know the IP address of the other user, you can do the following:

pjsua sip:<ip address>

Chances are you’ll want to have a registered account on a server running something like Asterisk. You can use command-line options to specify the account details every time, or you can put the command-line options into a config file and have pjsua load that instead using the following syntax:

pjsua –config-file=<config file>

One of the neatest features of pjsua is the ability to run it in “daemon” mode, officially called auto-answer. In this mode, pjsua sits idling, waiting for an incoming call. When it detects an incoming call, pjsua answers and can do several different things. Here is an example command:

pjsua –null-audio –play-file=data3.wav –auto-play –rec-file=call001.wav –auto-rec –auto-answer=200 –config-file=pj-config

Broken down, this command tells pjsua to run, register itself with the central server with the details provided in “pj-config”, to listen for incoming calls and automatically answer with code 200 (for those of you familiar with HTTP status codes, SIP status codes are remarkably similar), to loop data3.wav after answering the call, and to record any audio on the line (except the wav file being piped in).

Why on earth would this be useful? Say, for instance, I have a business client using my VoIP service at the other end of the state. He calls me to complain that call quality has been atrocious for the past few days. There are a few things I can do. I can take up a bunch of his time having him troubleshoot with me on the phone, I can drive all the way across the state and troubleshoot the issue myself, or I can use the web server we’ve also installed on his network to make my own test calls without ever leaving my office or tying up the client’s time or phone line. I can simply place a call to the test number and listen to the looped recording for evidence of audio quality issues. This only tells me half the story however, as often times with VoIP sessions only one side of the conversation is affected. This is where the recording comes in, as I can now download it from the remote server and analyze it for problems. This saves both time and money, and provides an easy yet effective way to track down problems.

Pjsua is a fully featured SIP client, so if you have speakers and a microphone on your system, you can use this just like you would any other soft-phone. However, given that there are several other soft-phones for linux with a nice GUI interface, one of them may be a better choice if your goal is simply to make and receive calls from your computer. But if you need something to run in a windowless environment, or you’re like me and need something lightweight to help troubleshoot VoIP issues, you can download Pjsua and the entire PJSIP library from http://www.pjsip.org.