Manual of pjsua - Command Line SIP User Agent/Softphone

Screenshot of pjsua on Windows, the command line SIP soft phone.
pjsua can run on Windows, Linux, *nix, MacOS X, and many more.

Introduction

pjsua is an open source command line SIP user agent (softphone) that is used as the reference implementation for PJSIP, PJNATH, and PJMEDIA. Despite its simple command line appearance, it does pack many features!

Reference

Synopsis


Usage:
  pjsua [options] [SIP URL to call]

General options:
  --config-file=file  Read the config/arguments from file.
  --help              Display this help screen
  --version           Display version info

Logging options:
  --log-file=fname    Log to filename (default stderr)
  --log-level=N       Set log max level to N (0(none) to 6(trace)) (default=5)
  --app-log-level=N   Set log max level for stdout display (default=4)
  --color             Use colorful logging (default yes on Win32)
  --no-color          Disable colorful logging
  --light-bg          Use dark colors for light background (default is dark bg)

SIP Account options:
  --use-ims           Enable 3GPP/IMS related settings on this account
  --use-srtp=N        Use SRTP?  0:disabled, 1:optional, 2:mandatory (def:0)
  --srtp-secure=N     SRTP require secure SIP? 0:no, 1:tls, 1:sips (def:1)
  --registrar=url     Set the URL of registrar server
  --id=url            Set the URL of local ID (used in From header)
  --contact=url       Optionally override the Contact information
  --contact-params=S  Append the specified parameters S in Contact URI
  --proxy=url         Optional URL of proxy server to visit
                      May be specified multiple times
  --reg-timeout=SEC   Optional registration interval (default 55)
  --realm=string      Set realm
  --username=string   Set authentication username
  --password=string   Set authentication password
  --publish           Send presence PUBLISH for this account
  --use-100rel        Require reliable provisional response (100rel)
  --auto-update-nat=N Where N is 0 or 1 to enable/disable SIP traversal behind
                      symmetric NAT (default 1)
  --next-cred         Add another credentials

SIP Account Control:
  --next-account      Add more account

Transport Options:
  --ipv6              Use IPv6 instead for SIP and media.
  --local-port=port   Set TCP/UDP port. This implicitly enables both
                      TCP and UDP transports on the specified port, unless
                      if TCP or UDP is disabled.
  --ip-addr=IP        Use the specifed address as SIP and RTP addresses.
                      (Hint: the IP may be the public IP of the NAT/router)
  --bound-addr=IP     Bind transports to this IP interface
  --no-tcp            Disable TCP transport.
  --no-udp            Disable UDP transport.
  --nameserver=NS     Add the specified nameserver to enable SRV resolution
                      This option can be specified multiple times.
  --outbound=url      Set the URL of global outbound proxy server
                      May be specified multiple times
  --stun-srv=name     Set STUN server host or domain

TLS Options:
  --use-tls           Enable TLS transport (default=no)
  --tls-ca-file       Specify TLS CA file (default=none)
  --tls-cert-file     Specify TLS certificate file (default=none)
  --tls-privkey-file  Specify TLS private key file (default=none)
  --tls-password      Specify TLS password to private key file (default=none)
  --tls-verify-server Verify server's certificate (default=no)
  --tls-verify-client Verify client's certificate (default=no)
  --tls-neg-timeout   Specify TLS negotiation timeout (default=no)
  --tls-cipher        Specify prefered TLS cipher (optional).
                      May be specified multiple times

Media Options:
  --add-codec=name    Manually add codec (default is to enable all)
  --dis-codec=name    Disable codec (can be specified multiple times)
  --clock-rate=N      Override conference bridge clock rate
  --snd-clock-rate=N  Override sound device clock rate
  --stereo            Audio device and conference bridge opened in stereo mode
  --null-audio        Use NULL audio device
  --play-file=file    Register WAV file in conference bridge.
                      This can be specified multiple times.
  --play-tone=FORMAT  Register tone to the conference bridge.
                      FORMAT is 'F1,F2,ON,OFF', where F1,F2 are
                      frequencies, and ON,OFF=on/off duration in msec.
                      This can be specified multiple times.
  --auto-play         Automatically play the file (to incoming calls only)
  --auto-loop         Automatically loop incoming RTP to outgoing RTP
  --auto-conf         Automatically put calls in conference with others
  --rec-file=file     Open file recorder (extension can be .wav or .mp3
  --auto-rec          Automatically record conversation
  --quality=N         Specify media quality (0-10, default=6)
  --ptime=MSEC        Override codec ptime to MSEC (default=specific)
  --no-vad            Disable VAD/silence detector (default=vad enabled)
  --ec-tail=MSEC      Set echo canceller tail length (default=256)
  --ec-opt=OPT        Select echo canceller algorithm (0=default,
                        1=speex, 2=suppressor)
  --ilbc-mode=MODE    Set iLBC codec mode (20 or 30, default is 30)
  --capture-dev=id    Audio capture device ID (default=-1)
  --playback-dev=id   Audio playback device ID (default=-1)
  --capture-lat=N     Audio capture latency, in ms (default=100)
  --playback-lat=N    Audio playback latency, in ms (default=100)
  --snd-auto-close=N  Auto close audio device when it is idle for N seconds.
                      Specify N=-1 (default) to disable this feature.
                      Specify N=0 for instant close when unused.
  --no-tones          Disable audible tones
  --jb-max-size       Specify jitter buffer maximum size, in frames (default=-1)

Media Transport Options:
  --use-ice           Enable ICE (default:no)
  --ice-no-host       Disable ICE host candidates (default: no)
  --ice-no-rtcp       Disable RTCP component in ICE (default: no)
  --rtp-port=N        Base port to try for RTP (default=4000)
  --rx-drop-pct=PCT   Drop PCT percent of RX RTP (for pkt lost sim, default: 0)
  --tx-drop-pct=PCT   Drop PCT percent of TX RTP (for pkt lost sim, default: 0)
  --use-turn          Enable TURN relay with ICE (default:no)
  --turn-srv          Domain or host name of TURN server ("NAME:PORT" format)
  --turn-tcp          Use TCP connection to TURN server (default no)
  --turn-user         TURN username
  --turn-passwd       TURN password

Buddy List (can be more than one):
  --add-buddy url     Add the specified URL to the buddy list.

User Agent options:
  --auto-answer=code  Automatically answer incoming calls with code (e.g. 200)
  --max-calls=N       Maximum number of concurrent calls (default:4, max:255)
  --thread-cnt=N      Number of worker threads (default:1)
  --duration=SEC      Set maximum call duration (default:no limit)
  --norefersub        Suppress event subscription when transfering calls
  --use-compact-form  Minimize SIP message size
  --no-force-lr       Allow strict-route to be used (i.e. do not force lr)
  --accept-redirect=N Specify how to handle call redirect (3xx) response.
                      0: reject, 1: follow automatically (default), 2: ask

When URL is specified, pjsua will immediately initiate call to that URL

Command Line Options

The following options can be specified when invoking pjsua. The options use standard getopt long option convention, which means that option value can be specified after the option with either whitespace or equal sign.

General Options

Logging Options

SIP Account Options

PJSUA can be configured with zero or more SIP accounts. SIP accounts can be used to log in to SIP services, and send or receive requests using the specified SIP services.

Specify these options for each account to be configured. If you wish to create more account, specify "--next-account" to begin specifying parameters for the next account.

SIP Account Authentication Options

Each account has separate authentication settings, and you can put multiple credentials in one account (e.g. when one need to specify different credentials for each proxies). Use the argument "--next-cred" to specify next credential:

Transport Options

TLS Options

Note that these TLS options can only be specified when TLS support is configured during compilation (PJSIP_HAS_TLS_TRANSPORT macro is enabled).

Media Options

Media Transport Options

Buddy List

User Agent Options

Application Menus

These command line menus are available within the application. To invoke the command, input the command then press ENTER.


	+=============================================================================+
	|       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       sleep MS     echo [0|1|txt]        n: detect NAT type        |
	+=============================================================================+

Call Commands

IM and Presence Commands

Account Commands

Conference Commands

Status and Config Commands

Other Commands

Invoking pjsua

Basic Peer-to-Peer

The easiest way to use pjsua is to use it in serverless configuration, to call or receive calls from other SIP user agents directly.

Running pjsua without any arguments will bind pjsua to TCP and UDP port 5060 of local host:

Registering with SIP Provider

This command below will make pjsua send outgoing requests (such as INVITE) with From: header set to sip:alice@example.com, but pjsua will not register to any SIP servers:

To make pjsua register to a SIP provider, the command below can be used. This will make pjsua register to sip:example.com server using user-id alice and password secret. All command line arguments are mandatory:

pjsua also supports multiple identities and server registrations. To register with both provider1.com and provider2.com simultaneously:

To register to server example.com with user id Alice, and send the requests to outbound.home.com which requests different authentication:

Using TCP Transport

By default, TCP transport will be created and initialized. However, TCP will not be used automatically unless the destination URL has ";transport=tcp" parameter in it. (Note: this behavior may change once we support resolving NAPTR records).

TCP can be specified when registering to server and when sending outgoing requests. To use TCP when registering, add ";transport=tcp" in the registrar's URL, for example with "--registrar sip:example.com;transport=tcp" option.

Similarly ";transport=tcp" parameter needs to be added in the destination URL when making outgoing calls, subscribing presence, or sending outgoing MESSAGE request.

Using TLS Transport

TLS transport option will be available if it is enabled during the build process.

To use TLS transport, add ";transport=tls" parameter for outgoing URIs, similar to TCP transport above.

Using IPv6

IPv6 support must be enabled during build process by declaring "#define PJ_HAS_IPV6 1" in your config_site.h. These instructions below apply to PJSIP version 1.2 or later.

Note above that with --bound-addr option it is necessary to disable TCP with --no-tcp since the SIP TCP transport does not support IPv6 at the moment.

Miscellaneous

This will automatically answer all incoming calls with 200/OK, playback the WAV file to incoming calls, and also loopback calls's media to itself (remote will hear the file mixed with their own voice):

Config File

The config file basicly are the same command line arguments, saved in a file! For example, to specify above command line in the file called alice.cfg:

pjsua Manual Page

Table of Contents