Pjsip

Overview

pjsip 는 오픈소스로 제작된 멀티미디어 통신 라이브러리이다. pjsip 에서 제공하는 라이브러리를 이용하면 자동 SIP 콜 테스트 프로그램 등을 쉽게 제작할 수 있다.

Library 뿐만 아니라, pjsip 설치시 함께 컴파일되는 모듈 중에 pjsua 라는 모듈이 있는데 이는 CLI(Command line interface) 지원하는 SIP 클라이언트 프로그램이다.
즉, library 를 제공하는 것 뿐만 아니라 CLI 기반 클라이언트 프로그램도 같이 제공한다.

그리고 Library 모듈 중, Python 모듈은 Python 을 이용한 스크립트 제작을 가능하게 해준다. 즉, Python 으로 동작하는 SIP 자동 테스트 같은 프로그램을 제작할 수 도 있는 것이다.

지원 OS

다음의 OS 들을 지원한다.

Windows
Linux
Mac OS
Android
IOS

Installation

Ubuntu/Debian

apt-get 을 통한 패키지 설치를 지원하지 않는다. 소스를 다운받아 컴파일 하는 방식으로 설치가 가능하다.

$ wget http://www.pjsip.org/release/2.3/pjproject-2.3.tar.bz2
$ tar xf pjproject-2.3.tar.bz2
$ cd pjproject-2.3
$ ./configure
$ make dep
$ make
$ sudo make install

• 실수로 make dep 를 하기 전에 make 를 먼저 했을 경우, 에러가 발생하는 문제가 있었다. 이후에 다시 make dep 를 하고 make 를 해도 같은문제가 발생했다. make distclean & make clean 후, 다시 make dep & make 실행 후 정상적으로 컴파일이 되었다.

Others

기타 다른 설치는 이곳<ref>http://trac.pjsip.org/repos/wiki/Getting-Started</ref> 을 참조하면 된다.

Pjsua

pjsua 실행 모습

pjsua 는 pjsip 에서 제공하는 CLI 기반 SIP Client 이다. 자세한 사용 설명은 이곳<ref>http://www.pjsip.org/pjsua.htm</ref> 에서 확인할 수 있다.

기본 명령어 옵션

pchero@mywork:~/workspace/Study/Program/pjsip/scripts$ pjsua --help
11:01:27.842 os_core_unix.c !pjlib 2.3 for POSIX initialized
11:01:27.843 sip_endpoint.c  .Creating endpoint instance...
11:01:27.843          pjlib  .select() I/O Queue created (0xdf67e0)
11:01:27.843 sip_endpoint.c  .Module "mod-msg-print" registered
11:01:27.843 sip_transport.  .Transport manager created.
11:01:27.843   pjsua_core.c  .PJSUA state changed: NULL --> CREATED
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)
  --log-append        Append instead of overwrite existing log file.

  --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)
  --no-stderr         Disable stderr

SIP Account options:
  --registrar=url     Set the URL of registrar server
  --id=url            Set the URL of local ID (used in From header)
  --realm=string      Set realm
  --username=string   Set authentication username
  --password=string   Set authentication password
  --contact=url       Optionally override the Contact information
  --contact-params=S  Append the specified parameters S in Contact header
  --contact-uri-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 300)
  --rereg-delay=SEC   Optional auto retry registration interval (default 300)
  --reg-use-proxy=N   Control the use of proxy settings in REGISTER.
                      0=no proxy, 1=outbound only, 2=acc only, 3=all (default)
  --publish           Send presence PUBLISH for this account
  --mwi               Subscribe to message summary/waiting indication
  --use-ims           Enable 3GPP/IMS related settings on this account
  --use-srtp=N        Use SRTP?  0:disabled, 1:optional, 2:mandatory,
                      3:optional by duplicating media offer (def:0)
  --srtp-secure=N     SRTP require secure SIP? 0:no, 1:tls, 2:sips (def:1)
  --use-100rel        Require reliable provisional response (100rel)
  --use-timer=N       Use SIP session timers? (default=1)
                      0:inactive, 1:optional, 2:mandatory, 3:always
  --timer-se=N        Session timers expiration period, in secs (def:1800)
  --timer-min-se=N    Session timers minimum expiration period, in secs (def:90)
  --outb-rid=string   Set SIP outbound reg-id (default:1)
  --auto-update-nat=N Where N is 0 or 1 to enable/disable SIP traversal behind
                      symmetric NAT (default 1)
  --disable-stun      Disable STUN for this account
  --next-cred         Add another credentials

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

Transport Options:
  --set-qos           Enable QoS tagging 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=FORMAT   Set STUN server host or domain. This option may be
                      specified more than once. FORMAT is hostdom[:PORT]

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

Audio 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 idle for N secs (default=1)
                      Specify N=-1 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)
  --extra-audio       Add one more audio stream

Media Transport Options:
  --use-ice           Enable ICE (default:no)
  --ice-regular       Use ICE regular nomination (default: aggressive)
  --ice-max-hosts=N   Set maximum number of ICE host candidates
  --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 transferring 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,
                      2: follow + replace To header (default), 3: ask

CLI options:
  --use-cli           Use CLI as user interface
  --cli-telnet-port=N CLI telnet port
  --no-cli-console    Disable CLI console


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

11:01:27.845   pjsua_core.c  Shutting down, flags=0...
11:01:27.845   pjsua_core.c  PJSUA state changed: CREATED --> CLOSING
11:01:27.845   pjsua_call.c  .Hangup all calls..
11:01:27.845  pjsua_media.c  .Call 0: deinitializing media..
11:01:27.845  pjsua_media.c  .Call 1: deinitializing media..
11:01:27.845  pjsua_media.c  .Call 2: deinitializing media..
11:01:27.846  pjsua_media.c  .Call 3: deinitializing media..
11:01:27.846   pjsua_pres.c  .Shutting down presence..
11:01:28.849   pjsua_core.c  .Destroying...
11:01:28.849  pjsua_media.c  .Shutting down media..
11:01:28.849 sip_endpoint.c  .Destroying endpoing instance..
11:01:28.849 sip_endpoint.c  .Module "mod-msg-print" unregistered
11:01:28.849 sip_transport.  .Destroying transport manager
11:01:28.849 sip_endpoint.c  .Endpoint 0xdeba48 destroyed
11:01:28.849   pjsua_core.c  .PJSUA state changed: CLOSING --> NULL
11:01:28.849   pjsua_core.c  .PJSUA destroyed...

Config 파일

Pjsua 사용시, PBX 계정 정보를 config 파일에 설정해 놓고, pjsua 실행시 마다 자동으로 Registration 하게 할 수 있다. 설정가능한 옵션 내용은 CLI 의 옵션과 동일하다. 하나 이상의 계정정보를 등록해 놓을 수 있다. 주의사항으로 하나 이상의 계정 정보를 등록하기 위해서는 --next-account 구문을 추가해야한다.

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

--next-account
--id sip:202@127.0.0.1
--registrar sip:127.0.0.1
--realm *
--username 202
--password a9564ebc3289b7a14551baf8ad5ec60a

Using configfile

미리 계정을 설정해 놓은 Config file 을 사용할 수 있다.

$ pjsua --config-file=test.cfg

or

$ pjsua --config-file test.cfg

Pjsua 메뉴

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

Make call

+=============================================================================+
You have 0 active call
>>> m
(You currently have 0 calls)
Buddy list:
 -none-

Choices:
   0         For current dialog.
  -1         All 0 buddies in buddy list
  [1 - 0]    Select from buddy list
  URL        An URL
  <Enter>    Empty input (or 'q') to cancel
Make call: sip:501@127.0.0.1

Make call 시, sip:<sip_url> 구문을 입력해야 한다. 단순히 sip_url 입력만으로는 발신이 되지 않으니 참고하자.

이상하게 pjsua로 make call 실행 시, 사운드가 노트북 내장 스피커로 연결되어 굉장히 이상한 소리가 나는 현상이 있다.(Lenovo E540, ubuntu-14.04) -> 전체 재컴파일 후, 정상적으로 소리가 안나오는 문제 해결. 하지만 도킹시스템을 통한 외장 스피커 출력이 되지 않는다. 노트북에 있는 오디오 output 으로만 출력이 되는 현상 발생. 아마도 pjsua 는 gnome 스피커 출력 API 를 사용하지 않고 바로 출력 Device 잡고 나가기 때문에 발생하는 현상으로 보인다. 특별히 버그나 문제라고 볼 수는 없기에 그냥 넘어가기로 한다.

References

<references />