BLOG | DOCUMENTATION | TRAC

pjsua Manual Page

version: 0.9.0
[Last Update: $Date: 2007-10-04 14:05:21 +0100 (Thu, 04 Oct 2007) $]

Print Friendly Page


PJSUA screnshot

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

 

 

Table of Contents


Introduction

Command Reference

     Synopsis

     Command Line Options

         General Options
         Logging Options
         SIP Account Options
         SIP Account Authentication Options
         Transport Options
         TLS Transport Options
         Media Options
         Buddy List
         User Agent Options

     Application Menu

         Call Commands
         IM and Presence Commands
         SIP Account Commands
         Call Conference Commands
         Status and Config Commands
         Other Commands

Sample Commands

     Basic Peer-to-Peer SIP
     Registering with SIP Provider
     Using TCP Transport
     Using IPv6
     Miscellaneous

Config File

 

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!

SIP features:
  • Mutiple lines/identities (account registrations).
  • Multiple calls.
  • IPv6 (added in version 1.2)
  • PRACK (100rel, RFC 3262).
  • UPDATE (RFC 3311).
  • OPTIONS.
  • Call hold.
  • Call transfer (attended or unattended, with or without refersub, RFC 3515, 3891, 3892, 4488).
  • SIMPLE with PIDF and XPIDF support (SUBSCRIBE/NOTIFY, RFC 3265, 3856, 3863).
  • Custom presence status text (RPID, RFC 4480).
  • PUBLISH support (RFC 3903).
  • Instant messaging (MESSAGE) and message composing indication (RFC 3428, 3994)
  • UDP, TCP, and TLS transports.
  • DNS SRV resolution for SIP servers (RFC 3263).
  • DTMF with INFO (RFC 2976).
  • STUN (RFC 3489bis).
  • Digest AKA authentication (in development, RFC 3310, 4169).
Media features:
  • Multiple Concurrent calls
  • Conferencing
  • Speex, iLBC, GSM, G711, G722, and L16 codecs.
  • Wideband and ultra-wideband codec (Speex)
  • More codecs via Intel IPP library: AMR-NB, AMR-WB, G.722.1 (Siren7), G.723.1, G.726, G.728, G.729A
  • Stereo codecs (L16)
  • WAV file playing, streaming, and recording.
  • RTCP
  • Call quality monitoring.
  • RFC 2833
  • Auto-answer, auto-play file, auto-loop RTP
  • Tone generation.
  • AEC (Accoustic echo cancellation).
  • Adaptive jitter buffer.
  • Adaptive silence detection.
  • PLC (Packet Lost Concealment).
  • Packet loss simulation.
  • Multiple frames per RTP packet.
  • SRTP (Secure RTP)
NAT traversal features:
  • ICE (Interactive Connectivity Establishment, latest ICE draft).
  • STUN (latest rfc3489-bis).
  • TURN (latest draft-ietf-behave-turn)
  • rport.
  • SIP TCP and TLS keep-alive.
  • Auto-detect and recover SIP UDP address change.
  • Auto-detect ICE media transport change.

pjsua can be downloaded from http://www.pjsip.org/download.htm.

 

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

--help Show the command line help.
--version Display pjsua version along with other compilation flags then quits.
--config-file=FILE Read the command line options from FILE name.

 

Logging Options

--log-file=FILE Save all logging to FILE name.
--log-level=(0-6)

Set maximum logging verbosity level. Default is 5.

  • Level 0 Display fatal error only.
  • Level 1 Display error messages and more severe verbosity level only.
  • Level 2 Display Warning messages and more severe verbosity level only. 
  • Level 3 Info verbosity (normally used by applications).
  • Level 4 Important PJSIP events.
  • Level 5 Detailed PJSIP events.
  • Level 6 Very detailed PJLIB events.
--app-log-level=(0-6) Set maximum logging verbosify that will be displayed on screen/console. Default is 4.

 

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.

--id=URL Set SIP URL of the account(i.e. From header). For example: "sip:bob@example.com"
--contact=URL Optional SIP contact (i.e. Contact header). Specifying custom contact is not recommended , because pjsua is able to create contact from the user id and transport info.
--registrar=URL Set the URL of the registrar server. It not specified, then the account will not register. An example of URL: "sip:example.com"
--proxy=URL Optionally set the URL of proxies to build initial route set for all requests using this account. This option may be specified multiple times. The URL MUST have ";lr"parameter. For example, if you want all outgoing SIP requests to go via proxy.example.com, then the URL should be: "sip:proxy.example.com;lr".
--reg-timeout=SECONDS Set optional timeout (i.e. Expires header) for SIP account registration, in seconds. Default is 55.
--publish Enable presence publication for this account, by sending PUBLISH request to the registrar.
--use-100rel Require the use of reliable provisional response (100rel, PRACK) for this account.
--use-ims Enable 3GPP/IMS related settings on this account.
--use-srtp=N Control SRTP usage for this account. N=0: disabled, N=1: use optional disposition for SRTP in SDP, N=2: require SRTP for all calls for this account. Default is 0.
--srtp-secure=N Control whether the use of SRTP requires secure signaling. N=0: no, N=1: secure transport to next hop must be used, N=2: secure end-to-end transport must be used. Default is 1.
--auto-update-nat=N Allow changing contact header if necessary to work with symmetric NAT. Default is 1.

 

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:

--realm=string Set authentication realm. The realm is used to match this credential against challenges issued by downstream servers. If the realm is not known beforehand, wildcard character ('*') can be specified to make PJSIP respond to any realms.
--username=string Set authentication user ID.
--password=string Set authentication password (clear text).
--next-cred Specify additional credential for this account.

 

Transport Options

--ipv6

Note: added in v1.2

Use IPv6 only for (UDP) SIP and (UDP) media transports. This option will only appear if PJSIP is compiled with IPv6 support (by declaring "#define PJ_HAS_IPV6 1" in your config_site.h). Note that at present IPv6 is only supported by SIP UDP transport and UDP media transport.

--local-port=PORT Set local port for SIP transport. Default is 5060 for UDP and TCP, and 5061 for TLS.
--ip-addr=IP Use the specifed address as SIP and RTP addresses. The IP address does not have to correspond with local interface, e.g. it may be the public IP of the NAT/router.
--bound-addr=IP

Note: added in v1.2

Bind the SIP and media transports to the specified IP address. The IP address must be an IP address of one of the host network interface. When this option is used with --ipv6 option, it will be necessary to disable TCP with --no-tcp option since the TCP transport will not recognize the IPv6 address.

--no-tcp Prevent TCP transport from being created.
--no-udp Prevent UDP transport from being created.
--nameserver=NS Enable DNS SRV resolution for both SIP and STUN servers, by querying the specified name server. This option can be specified more than once, and the multiple nameservers will be used in fail-over configuration.
--outbound=URL Optionally set the URL of outbound proxies. The outbound proxies will be used for all accounts. More than one proxies may be specified. The URL MUST have ";lr" param.
--stun-srv=HOSTDOM Specify the STUN server to use, for SIP UP transport, UDP media transport, and ICE media transport. The HOSTDOM value may identify a hostname or a domain name. When DNS SRV resolution is enabled (with --nameserver option above), pjsua will first try to resolve the STUN server by querying DNS SRV record for the domain specified in HOSTDOM. If the DNS SRV resolution fails, or if nameserver is not configured, HOSTDOM is treated as a hostname.

 

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).

--use-tls Enable TLS transport. TLS support is still experimental, therefore it's still disabled by default, even when the program has been compiled with TLS support.
--tls-ca-file

Specify TLS Certificate of Authority file (default=none). A CA file must be specified for server, and for client when it wants to authenticate server's certificate (--tls-verify-server option).

This option is optional for client if it doesn't want to authenticate the server.

--tls-cert-file

Specify TLS certificate file (default=none). A certificate must be configured for server, and for client when it wants to authenticate server's certificate (--tls-verify-server option).

This option is optional for client if it doesn't want to authenticate the server.

--tls-privkey-file

Specify TLS private key file (default=none). This must be configured for server, and for client when it wants to authenticate server's certificate (--tls-verify-server option).

This option is optional for client if it doesn't want to authenticate the server.

--tls-password Specify password to open the private key file.
--tls-verify-server Verify the server's certificate when making outgoing TLS connections. The default is without server verification.
--tls-verify-client Verify the client's certificate when accepting incoming TLS connections. The default is without client verification.
--tls-neg-timeout Specify SSL negotiation timeout (in seconds). The default is without timeout limitation.

 

Media Options

--add-codec=NAME

Set codec NAME to have higher priority to use. The NAME is the standard name for the codec as specified by the relevant RFCs. If the name alone is not unique, then clock-rate (and potentially number of channels) must be appended to the NAME after the slash character.

Example of codec names: pcma, pcmu, speex/8000, speex/16000, speex/32000, ilbc, gsm, l16/44100/2, etc.

This option maybe specified multiple times. The order of the codec specifies the priority. C

--dis-codec=NAME Disable codecs with matching NAME.
--clock-rate=HZ Set the clock rate of the conference bridge. Default is 16000.
--snd-clock-rate=HZ Set the clock rate of the sound device. By default the sound device will be opened at the same clock rate as the conference bridge.
--stereo Open both sound device and the conference bridge in stereo mode. Left and right channels may be mixed if the media port registered to the conference bridge is not stereo.
--null-audio Disable the sound device. Calls will behave normally, except that no audio will be transmitted or played locally.
--play-file=WAVFILE Add file port to play WAV file to the conference bridge. File MUST be single channel/mono, 16bit signed PCM, with any sampling rate. If the sampling rate is not equal to sound device's clock rate, a resampling will occur.
--play-tone=FORMAT Add a tone generator to the conference bridge. FORMAT is "FREQ1,FREQ2,ON,OFF" where FREQ1 and FREQ2 are the tone frequencies (specify 0 in FREQ2 to play a single frequency tone), and ON and OFF are the tone on/off duration in miliseconds.
--auto-play Automatically stream the WAV file to incoming calls.
--auto-loop Automatically loop-back call to itself.
--auto-conf Automatically put calls in the conference mode.
--rec-file=WAVFILE Add file recorder port to the conference bridge. The recorder port can be used to record any ports in the conference bridge.
--auto-rec Automatically record conversations.
--quality=N Set media quality according to CPU usage requirements. Values are 1-10, where 10 is the highest quality (default: 6).
--ptime=MSEC Override codec ptime to MSEC (default=specific).
--no-vad Disable silence detector/voice activity detector. Useful sometimes to work around NAT problems.
--ec-tail=MSEC Set echo canceller tail length (default is 800ms). Set to zero to disable echo cancellation.
--ilbc-mode=MODE Set iLBC codec mode to MODE (20 or 30). Default is 30.
--capture-dev=ID Specify the device index for sound capture device. Use sndinfo from the samples directory to get the list of detected sound devices in the system.
--playback-dev=ID Specify the device index for sound playback device. Use sndinfo from the samples directory to get the list of detected sound devices in the system.
--capture-lat=MSEC Set the sound input buffer size/latency in msec. Setting the value to lower value will lower the latency but may affect the sound stability. Default is 100 msec.
--playback-lat=MSEC Set the sound output buffer size/latency in msec. Setting the value to lower value will lower the latency but may affect the sound stability. Default is 100 msec.
--snd-auto-close=SEC Automatically close the sound device when it is idle after SEC seconds (and automatically open the sound device when it is to be used). Setting this to zero will disable the feature, and sound device will be open all the time. Default is 0.
--no-tones Disable the creation and usage of ringback tones.

 

Media Transport Options

--use-ice Enable ICE. Say yes!
--ice-no-host Do not include ICE host candidates (only used for testing).
--rtp-port=N Set the start RTP port. Default is 4000.
--rx-drop-pct=PCT Drop PCT percent of incoming RTP packet (for packet lost simulation, default: 0).
--tx-drop-pct=PCT Drop PCT percent of outgoing RTP packet (for packet lost simulation, default: 0).
--use-turn Enable TURN relay. The following TURN settings must also be set.
--turn-srv=HOSTDOM Specify the TURN server domain name or hostname. The format is either "DOMAIN:PORT" or "HOST:PORT". When nameserver setting is set, the domain/host part will be first resolved with DNS SRV, and it will fallback to host resolution using the specified PORT if DNS SRV resolution fails.
--turn-tcp Use TCP to communicate with the TURN server rather than UDP. Default is no.
--turn-user=USERNAME Specify the username to authenticate against the TURN server.
--turn-passwd=PASSWD Specify the plaintext password to authenticate against the TURN server.

 

Buddy List

--add-buddy=url Add the url to the buddy list. This option can be specified multiple times to add more than one buddies.

 

User Agent Options

--auto-answer=code Automatically answer incoming calls with the specified code, e.g. 200 to automatically answer incoming calls. Default is to answer with 100 (Trying).
--max-calls=N Maximum number of concurrent calls. Default is 4. Note that the maximum calls number is also limited by PJSUA_MAX_CALLS macro in pjsua.h, which by default is 32.
--thread-cnt=N Set number of SIP worker thread. Default is 1 (since the main thread will be blocked to wait for console input so a worker thread is needed)
--duration=SEC Set maximum call duration to SEC seconds (default is no limit). Useful when running pjsua as test server to prevent dangling calls.
--norefersub Suppress event subscription when transfering calls by including norefersub tag in outgoing REFER requests.
--use-compact-form Use compact form of SIP headers to minimize the packet size.

 

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

m

Make new call Make a new call/INVITE. The application will ask the URL of the remote peer to contact.

M

Make multiple calls Make multiple calls to the same destination.

a

Answer call Send 100-699 response to current call. The application will ask which status code to send. Note that current call MUST be an incoming call. Current call can be selected with "]" or "[" command.

h

Hangup call Hangup current call. This command will work regardless of the state of the current call (e.g. it may send CANCEL, 603 (Decline), BYE, etc depending on the state of the call).

H

Hold call Put the current call on-hold by sending inactive SDP. Note that incoming call hold request will be acted automatically.

v

Re-Invite (release hold) Send active SDP with current call. If the call is currently on-hold, this will effectively release the hold. You can also change the local codec preference with Cp command before sending the offer.

U

Send UPDATE request Send UPDATE with new offer. You can also change the local codec preference with Cp command before sending the offer.

]

Select next call If application has more than one calls, this command will select the next call in the list as current call.

[

Select previous call If application has more than one calls, this command will select the previous call in the list as current call.

x

Transfer call (xfer) Transfer current call (i.e. send outgoing REFER). The application will ask the URL to which remote party should contact. Note that transfering current call DOES NOT cause pjsua to hold or disconnect currentcall. User should use the hold and hangup command to hold and terminate the call accordingly. Note that incoming call transfer request will be processed automatically.

#

Send DTMF with RFC 2833 Send DTMF digits as RFC 2833 events in current call. The application will ask the digit strings to send.

*

Send DTMF with SIP INFO Send DTMF digits as SIP INFO for current call. The application will ask the digit strings to send.

dq

Dump (call) quality Print media statistic (packet loss, duplicate, jitter, end-to-end delay, etc) of currently selected call.

S

Send arbitrary request Send an arbitrary request to remote host. You will be asked about the SIP method and destination to send the request. Useful for example to send OPTIONS.

IM and Presence Commands

+b

Add buddy Add a new buddy URL to the buddy list.

-b

Delete buddy Delete a buddy from the buddy list.

i

Send IM Send outgoing MESSAGE. The application will ask the URL of the remote peer to send the message to, and the contents of the message.

s

Subscribe presence Subscribe to presence subscription of an URL in the buddy list. The buddy's online presence status will be monitored by the application.

u

Unsubscribe presence Unsubscribe existing presence subscription.

t

Toggle online state Toggle local presence's online status. If there are subscribers to our presence, NOTIFY messages will be sent to those subscribers. Note that application automatically accepts presence subscription request.

T

Specify custom presence text Specify enhanced presence status text (such as "Be Right Back") with this command.

Account Commands

+a

Add account Add a new account (not implemented yet).

-a

Delete account Delete account (not implemented yet).

!a

Modify account Modify account (not implemented yet).

rr

Re-Register Send REGISTER request for this account to register or to refresh registration.

ru

Unregister Send REGISTER request to unregister the account registration.

>

Select next account Select the current account to be used for sending outgoing requests.

<

Select prev account Select the current account to be used for sending outgoing requests.

Conference Commands

cl

Conference List List all the ports registered to the conference bridge, and show the interconnection among these ports.

cc

Conference Connect Create a unidirectional connection between two ports. For example, if you have a WAV player connected at slot #1 and a call connected at slot #2, you can stream WAV file to the call by specifying this command: cc 1 2.

cd

Conference Disconnect Disconnect a unidirectional connection between two ports. Example: cd 1 2.

V

Adjust volume Make adjustment to the audio level of a particular media port.

Cp

Arrange codec priorities Arrange the codec priorities. Useful for example to set the prefered codec before sending re-INVITE ("v" command) or UPDATE ("U" command).

Status and Config Commands

d

Dump status Dump the contents of endpoint, transaction table, dialog table, invite sessions, etc to the screen.

dd

Dump detailed status Dump detailed status (each transaction, each call, including call/media quality etc.)

dc

Dump configuration Dump current configuration to screen.

f

Write settings Write current configuration to file.

Other Commands

q

Quit Quit application. All current calls, subscriptions, and registrations will be terminated.

sleep MSEC

Suspend keyboard input Suspend keyboard input for the specified miliseconds. Useful when piping commands to pjsua.

echo [0|1|TXT]

Control command echo Use echo 0 or echo 1 to disable or enable command echo (default is disabled). Use echo TXT (where TXT is any text) to output the text to stdout.

n

Detect network type Initiate NAT type detection. The result will be printed to stdout and log.

 

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:

 

$ ./pjsua

This command below will initiate outgoing call to some SIP URL:

 

$ ./pjsua sip:192.168.0.10

 

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:

 

$ ./pjsua --id sip:alice@example.com

 

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 --id sip:alice@example.com --registrar sip:example.com \
          --realm * --username alice --password secret

Some explanation about the commands above:

  --id sip:alice@example.com This sets the identification of the user, and will be used in the From: header of all requests sent by pjsua.
  --registrar sip:example.com This sets the address of the server where REGISTER request will be sent to.
  --realm example.com The realm of the credential to authenticate against the server. The value here MUST match the realm sent by the server in WWW-Authenticate or Proxy-Authenticate header in the 401/407 response. Alternatively, wildcard (*) can be specified to make PJSIP responds to any realms in the challenge.
  --username alice Set the username for authentication. Normally the value will be the same as the username part of the From: header, but pjsua does not require this to be the same.
  --password secret Set the plain-text password for authentication.

 

 
Note:

The realm setting must match the realm in the challenge, or otherwise PJSIP_ENOCREDENTIAL error will occur. If the realm isn't known beforehand, you can put wildcard ('*') as the realm, to make PJSIP responds to any realms in the challenge.

 

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

 

$ ./pjsua --id sip:bob@provider1.com --registrar sip:provider1.com \
          --realm provider.1.com --username bob --password secret \
          --next-account \
          --id
sip:bob@provider2.com --registrar sip:provider2.com \
          --realm provider2.com --username bob --password secret

 

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

 

$ ./pjsua --id sip:alice@example.com --registrar sip:example.com \
          --proxy outbound.home.com \
          --realm example.com --username alice --password secret --next-cred \
          --realm outbound.home.com --username blah --password blahblah

  

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.

This command below will start pjsua with IPv6 transports:

 

$ ./pjsua --ipv6

To force pjsua to use a specific IPv6 address (fec0::2, a site local address):

 

$ ./pjsua --ipv6 --bound-addr fec0::2 --no-tcp

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.

A simple IPv6 registration (assuming server is at IPv6 IP address fec0::1):

 

$ ./pjsua --ipv6 --id sip:myself@[fec0::1] --registrar sip:[fec0::1] \
    --username myself --realm "*" --password secret

  

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):

 

$ pjsua --play-file PROMPT.WAV --auto-answer 200 --auto-play --auto-loop \
        --max-calls 100

 

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:

 

# This is a comment in the config file.
--id sip:alice@example.com
--registrar sip:example.com
--realm *
--username alice
--password secret

And to use the config file:

 

$ ./pjsua --config-file alice.cfg