sipster v0.1.0
Description
A pjsip (or more accurately a pjsua2) binding for node.js.
Familiarity with pjsip/pjsua2 is a plus when using this binding.
Requirements
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
. SetnoLoop
to true to disable looping of the audio. WhennoLoop
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
. SetnoLoop
to true to disable looping of the playlist. WhennoLoop
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
, andsuffix
(e.g. '2.2.1-svn'). - numeric - integer - The
major
,minor
, andrev
as a single integer in the form 0xMMIIRR00 where MM ismajor
, II isminor
, and RR isrev
.
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 optionalreason
phrase.hangup([< integer >statusCode, < string >reason]) - (void) - Hangs up the call with an optional
statusCode
(defaults to 603) and optionalreason
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 aval
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 aval
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.