sipster

A pjsip binding for node.js

Usage no npm install needed!

<script type="module">
  import sipster from 'https://cdn.skypack.dev/sipster';
</script>

README

Description

A pjsip (or more accurately a pjsua2) binding for node.js.

Familiarity with pjsip/pjsua2 is a plus when using this binding.

Requirements

  • Non-Windows OS
  • pjsip -- v2.4.5 or newer
  • node.js -- v0.10 or newer

Install

npm install sipster

Examples

  • UAS set up as a SIP trunk (no registration):
var sipster = require('sipster');

// initialize pjsip
sipster.init();

// set up a transport to listen for incoming connections, defaults to UDP
var transport = new sipster.Transport({ port: 5060 });

// set up a SIP account, we need at least one -- as required by pjsip.
// this sets up an account for calls coming from 192.168.100.10
var acct = new sipster.Account({
  idUri: 'sip:192.168.100.10'
});

// watch for incoming calls
acct.on('call', function(info, call) {
  console.log('=== Incoming call from ' + info.remoteContact);

  // watch for call state changes
  call.on('state', function(state) {
    console.log('=== Call state is now: ' + state.toUpperCase());
  });

  // listen for DTMF digits
  call.on('dtmf', function(digit) {
    console.log('=== DTMF digit received: ' + digit);
  });

  // audio stream(s) available
  call.on('media', function(medias) {
    // play looping .wav file to the first audio stream
    var player = sipster.createPlayer('sound.wav');
    player.startTransmitTo(medias[0]);

    // record the audio of the other side, this will not include the audio from
    // the player above.
    var recorder = sipster.createRecorder('call.wav');
    medias[0].startTransmitTo(recorder);
    // to include the player audio, you can mix the sources together simply
    // by transmitting to the same recorder:
    //   player.startTransmitTo(recorder);
  });

  // answer the call (with default 200 OK)
  call.answer();
});

// finalize the pjsip initialization phase ...
sipster.start();

API

Exported static methods

  • init([< object >endpointCfg]) - (void) - Starts the initializion of the pjsip library (libInit()). This is to be done only once. endpointCfg is an EpConfig-like object for if you need to change any global options from the library defaults.

  • start() - (void) - Finalizes the initialization of the pjsip library (libStart()). This is generally called once you've got everything configured and set up.

  • hangupAllCalls() - (void) - Hangs up all existing calls.

  • createRecorder(< string >filename[, < string >format[, < integer >maxSize]]) - Media - Creates an audio recorder that writes to the given filename. format can be one of 'ulaw', 'alaw', or 'pcm' (default is 'ulaw'). maxSize is the maximum file size (default is no limit).

  • createPlayer(< string >filename[, < boolean >noLoop]) - Media - Creates an audio player that reads from filename. Set noLoop to true to disable looping of the audio. When noLoop is true, an 'eof' event will be emitted on the Media object when it reaches the end of playback.

  • createPlaylist(< array >filenames[, < boolean >noLoop]) - Media - Creates an audio player that sequentially reads from the list of filenames. Set noLoop to true to disable looping of the playlist. When noLoop is true, an 'eof' event will be emitted on the Media object when it reaches the end of the playlist.

Exported properties

  • version - object - (Read-only) Contains information about the pjsip library version (libVersion()):

    • major - integer - The major number.
    • minor - integer - The minor number.
    • rev - integer - The additional revision number.
    • suffix - string - The version suffix (e.g. '-svn').
    • full - string - The concatenation of major, minor, rev, and suffix (e.g. '2.2.1-svn').
    • numeric - integer - The major, minor, and rev as a single integer in the form 0xMMIIRR00 where MM is major, II is minor, and RR is rev.

  • config - object - (Read-only) Returns the entire current (EpConfig) config for pjsip.

  • state - string - (Read-only) Returns the state of the library/endpoint (libGetState()). For example: 'created', 'init', 'starting', 'running', or 'closing'.

  • mediaActivePorts - integer - (Read-only) Returns the total number of active Media ports.

  • mediaMaxPorts - integer - (Read-only) Returns the maximum number of Media ports permitted.

Additionally any needed pjsip library constants (may be needed when creating and passing in config objects) are exported as well.

Exported types

  • Transport - Represents an underlying (network) interface that Calls and Accounts use.

  • Account - An entity used for identification purposes for incoming or outgoing requests.

Transport methods

  • (constructor)([< object >transportConfig]) - Creates and returns a new, enabled Transport instance. transportConfig is a TransportConfig-like object for if you need to change any transport options from the library defaults.

  • unref() - (void) - Detaches the Transport from the event loop.

  • ref() - (void) - Attaches the Transport to the event loop (default upon instantiation).

  • getInfo() - object - Returns information (TransportInfo) about the transport:

    • type - string - Transport type name.
    • info - string - Transport string info/description.
    • flags - integer - Transport flags (e.g. PJSIP_TRANSPORT_RELIABLE, PJSIP_TRANSPORT_SECURE, PJSIP_TRANSPORT_DATAGRAM).
    • localAddress - string - Local/bound address.
    • localName - string - Published address.
    • usageCount - integer - Current number of objects currently referencing this transport.

  • disable() - (void) - Disables the transport. Disabling a transport does not necessarily close the socket, it will only discard incoming messages and prevent the transport from being used to send outgoing messages.

  • enable() - (void) - Enables the transport. Transports are automatically enabled upon creation, so you don't need to call this method unless you explicitly disable the transport first.

Transport properties

  • enabled - boolean - (Read-only) Indicates if the transport is currently enabled or not.

Account methods

  • (constructor)(< object >accountConfig) - Creates and returns a new Account instance. accountConfig is an AccountConfig-like object.

  • unref() - (void) - Detaches the Account from the event loop.

  • ref() - (void) - Attaches the Account to the event loop (default upon instantiation).

  • modify(< object >accountConfig) - (void) - Reconfigure the Account with the given accountConfig.

  • getInfo() - object - Returns information (AccountInfo) about the account:

    • uri - string - The account's URI.
    • regIsConfigured - boolean - Flag to tell whether this account has registration setting (reg_uri is not empty).
    • regIsActive - boolean - Flag to tell whether this account is currently registered (has active registration session).
    • regExpiresSec - integer - An up to date expiration interval for account registration session.

  • setRegistration(< boolean >renew) - (void) - Update registration or perform unregistration. You only need to call this method if you want to manually update the registration or want to unregister from the server. If renew is false, this will begin the unregistration process.

  • setTransport(< Transport >trans) - (void) - Lock/bind the given transport to this account. Normally you shouldn't need to do this, as transports will be selected automatically by the library according to the destination. When an account is locked/bound to a specific transport, all outgoing requests from this account will use the specified transport (this includes SIP registration, dialog (call and event subscription), and out-of-dialog requests such as MESSAGE).

  • makeCall(< string >destination) - Call - Start a new SIP call to destination.

Account properties

  • valid - boolean - (Read-only) Is the Account still valid?

  • default - boolean - (Read/Write) Is this the default Account for when no other Account matches a request?

Account events

  • registering() - The registration process has started.

  • unregistering() - The unregistration process has started.

  • registered() - The registration process has completed.

  • unregistered() - The unregistration process has completed.

  • state(< boolean >active, < integer >statusCode) - The account state has changed. active indicates if registration is active. statusCode refers to the relevant SIP status code.

  • call(< object >info, < Call >call) - An incoming call request. info contains:

    • srcAddress - string - The ip (and port) of the request.
    • localUri - string - Local SIP URI.
    • localContact - string - Local Contact field.
    • remoteUri - string - Remote SIP URI.
    • remoteContact - string - Remote Contact field.
    • callId - string - The Call-ID field.

Call methods

  • answer([< integer >statusCode[, < string >reason]]) - (void) - For incoming calls, this responds to the INVITE with an optional statusCode (defaults to 200) and optional reason phrase.

  • hangup([< integer >statusCode[, < string >reason]]) - (void) - Hangs up the call with an optional statusCode (defaults to 603) and optional reason phrase. This function is different than answering the call with 3xx-6xx response (with answer()), in that this function will hangup the call regardless of the state and role of the call, while answer() only works with incoming calls on EARLY state.

  • hold() - (void) - Puts the call on hold.

  • reinvite() - (void) - Releases a hold.

  • update() - (void) - Sends an UPDATE request.

  • transfer(< string >destination) - (void) - Transfers the call to destination.

  • dtmf(< string >digits) - (void) - Sends DTMF digits to the remote end using the RFC 2833 payload format.

  • unref() - (void) - Detaches the Call from the event loop (default).

  • ref() - (void) - Attaches the Call to the event loop.

  • getStatsDump([< boolean >inclMediaStats[, < string >indent]]) - string - Returns formatted statistics about the call. If inclMediaStats is true, then statistics about the Call's media is included (default is true). indent is the string to use for indenting (default is two spaces).

Call properties

  • connDuration - double - (Read-only) Call connected duration in seconds (zero when call is not established).

  • totalDuration - double - (Read-only) Total call duration in seconds, including set-up time.

  • hasMedia - boolean - (Read-only) True if the Call has active media.

  • isActive - boolean - (Read-only) True if the call has an active INVITE session and the INVITE session has not been disconnected.

Call events

  • state(< string >state) - The call state has changed. state is one of: 'calling', 'incoming', 'early', 'connecting', 'confirmed', or 'disconnected'.

  • dtmf(< string >digit) - A DTMF digit has been received from the remote end.

  • media(< array >medias) - The list of Medias associated with this call have changed and the current list is available in medias.

Media methods

  • startTransmitTo(< Media >sink) - (void) - Starts transmitting to sink.

  • stopTransmitTo(< Media >sink) - (void) - Stops transmitting to sink.

  • adjustTxLevel(< float >val) - (void) - Adjust the signal level of the audio sent from this Media by making it louder or quieter: a val of 1.0 means no level adjustment and a val of 0 means to mute.

  • adjustRxLevel(< float >val) - (void) - Adjust the signal level of the audio sent to this Media by making it louder or quieter: a val of 1.0 means no level adjustment and a val of 0 means to mute.

  • close() - (void) - Immediately closes the Media. This can be useful to do explicitly since v8's garbage collector is quite lazy. After calling this, using this particular Media instance (and its methods) is useless.

Media properties

  • dir - string - Returns the direction of the media from our perspective. The value is one of: 'none', 'inbound', 'outbound', 'bidirectional', or 'unknown'.

  • rtpAddr - string - Returns the remote address (and port) of where the RTP originates.

  • rtcpAddr - string - Returns the remote address (and port) of where the RTCP originates.

  • rxLevel - integer - Returns the last received signal level.

  • txLevel - integer - Returns the last transmitted signal level.

Media events

  • eof() - This is only applicable to player or playlist Media objects and indicates that the end of the file or end of playlist has been reached.