Académique Documents
Professionnel Documents
Culture Documents
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)
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-srv-name Specify TLS server name for multi-hosting server (optional)
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)
When URL is specified, pjsua will immediately initiate call to that URL
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
--app-log-level=(0- Set maximum logging verbosify that will be displayed on screen/console. Default is 4.
6)
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-
Set optional timeout (i.e. Expires header) for SIP account registration, in seconds.
timeout=SECOND
Default is 55.
S
--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-
Allow changing contact header if necessary to work with symmetric NAT. Default is 1.
nat=N
--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=stri Set authentication user ID.
ng
--
password=stri Set authentication password (clear text).
ng
--next-cred Specify additional credential for this account.
Transport Options
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-
Set local port for SIP transport. Default is 5060 for UDP and TCP, and 5061 for TLS.
port=PORT
--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- Note: added in v1.2
addr=IP
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.
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.
Media Options
--add- Set codec NAME to have higher priority to use. The NAME is the standard name for the
codec=NAME 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-
Disable codecs with matching NAME.
codec=NAME
--clock-rate=HZ Set the clock rate of the conference bridge. Default is 16000.
--snd-clock- Set the clock rate of the sound device. By default the sound device will be opened at the
rate=HZ 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- Add file port to play WAV file to the conference bridge. File MUST be single
file=WAVFILE 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- Add a tone generator to the conference bridge. FORMAT is "FREQ1,FREQ2,ON,OFF"
tone=FORMAT 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- Add file recorder port to the conference bridge. The recorder port can be used to record
file=WAVFILE 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-
Set iLBC codec mode to MODE (20 or 30). Default is 30.
mode=MODE
--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- Specify the device index for sound playback device. Use sndinfo from the samples
dev=ID directory to get the list of detected sound devices in the system.
--capture- Set the sound input buffer size/latency in msec. Setting the value to lower value will lower
lat=MSEC the latency but may affect the sound stability. Default is 100 msec.
--playback- Set the sound output buffer size/latency in msec. Setting the value to lower value will
lat=MSEC lower the latency but may affect the sound stability. Default is 100 msec.
--snd-auto- Automatically close the sound device when it is idle after SEC seconds (and automatically
close=SEC 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.
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.
--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 Make a new call/INVITE. The application will ask the URL of the remote peer to contact.
call
M Make Make multiple calls to the same destination.
multiple
calls
a Answer Send 100-699 response to current call. The application will ask which status code to send.
call Note that current call MUST be an incoming call. Current call can be selected with "]" or "["
command.
h Hangup Hangup current call. This command will work regardless of the state of the current call (e.g.
call 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 Send active SDP with current call. If the call is currently on-hold, this will effectively
(release release the hold. You can also change the local codec preference with Cp command before
hold) sending the offer.
U Send Send UPDATE with new offer. You can also change the local codec preference with Cp
UPDATE command before sending the offer.
request
] Select next If application has more than one calls, this command will select the next call in the list as
call current call.
[ Select If application has more than one calls, this command will select the previous call in the list
previous as current call.
call
x Transfer Transfer current call (i.e. send outgoing REFER). The application will ask the URL to which
call (xfer) 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 Send DTMF digits as RFC 2833 events in current call. The application will ask the digit
DTMF strings to send.
with RFC
2833
* Send Send DTMF digits as SIP INFO for current call. The application will ask the digit strings to
DTMF send.
with SIP
INFO
dq Dump Print media statistic (packet loss, duplicate, jitter, end-to-end delay, etc) of currently selected
(call) call.
quality
S Send Send an arbitrary request to remote host. You will be asked about the SIP method and
arbitrary destination to send the request. Useful for example to send OPTIONS.
request
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 Subscribe to presence subscription of an URL in the buddy list. The buddy's online
presence presence status will be monitored by the application.
u Unsubscribe Unsubscribe existing presence subscription.
presence
t Toggle online Toggle local presence's online status. If there are subscribers to our presence, NOTIFY
state messages will be sent to those subscribers. Note that application automatically accepts
presence subscription request.
T Specify Specify enhanced presence status text (such as "Be Right Back") with this command.
custom
presence text
Account Commands
> Select next Select the current account to be used for sending outgoing requests.
account
< Select prev Select the current account to be used for sending outgoing requests.
account
Conference Commands
cl Conference List all the ports registered to the conference bridge, and show the interconnection
List among these ports.
cc Conference Create a unidirectional connection between two ports. For example, if you have a WAV
Connect 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 a unidirectional connection between two ports. Example: cd 1 2.
Disconnect
V Adjust Make adjustment to the audio level of a particular media port.
volume
Cp Arrange Arrange the codec priorities. Useful for example to set the prefered codec before sending
codec re-INVITE ("v" command) or UPDATE ("U" command).
priorities
d Dump status Dump the contents of endpoint, transaction table, dialog table, invite sessions, etc to
the screen.
dd Dump detailed Dump detailed status (each transaction, each call, including call/media quality etc.)
status
dc Dump Dump current configuration to screen.
configuration
f Write settings Write current configuration to file.
Other Commands
q Quit Quit application. All current calls, subscriptions, and registrations will be terminated.
sleep Suspend Suspend keyboard input for the specified miliseconds. Useful when piping commands
MSEC keyboard to pjsua.
input
echo Control Use echo 0 or echo 1 to disable or enable command echo (default is disabled).
[0|1| command Use echo TXT (where TXT is any text) to output the text to stdout.
TXT] echo
n Detect Initiate NAT type detection. The result will be printed to stdout and log.
network type
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
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:
--id
This sets the identification of the user, and will be used in the From: header of all
sip:alice@example.
requests sent by pjsua.
com
--registrar
This sets the address of the server where REGISTER request will be sent to.
sip:example.com
--realm The realm of the credential to authenticate against the server. The value here MUST
example.com 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:
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:
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.
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.
$ ./pjsua --ipv6
To force pjsua to use a specific IPv6 address (fec0::2, a site local address):
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: