opensips-js

v0.1.36

Published

6 days ago

The JS package for opensips

0High
0Medium
0Low

shlomi.gutman

regani

title: Getting started description: The Opensips JS library and its expansive ecosystem offer developers a powerful and flexible solution for integrating Opensips protocol functionalities into a multitude of applications. navigation: title: Getting Started

Getting started

Installation

Using npm:

$ npm i opensips-js

Using via CDN:

You can include the OpensipsJS library directly in your HTML file using a CDN like UNPKG or jsDelivr. This is especially useful for quick prototyping or when you don't want to set up a build environment.

Add the following script tag to your HTML file:

<script src="https://cdn.opensipsjs.org/opensipsjs/v0.1.1/opensips-js.iife.js"></script>

This will load the library and attach the OpensipsJS class to the global window object as OpensipsJS.

Usage

Using npm (ES Modules):

Firstly lets import the library and create the OpenSIPS instance:

import OpenSIPSJS from 'opensips-js'

const openSIPSJS = new OpenSIPSJS({
    configuration: {
        session_timers: false,
        uri: 'sip:extension_user@domain',
        // --- Use password or authorization_jwt to authorize
        password: 'password',
        // or
        authorization_jwt: 'token',
    },
    socketInterfaces: [ 'wss://domain' ],
    pnExtraHeaders: {
        'pn-provider': 'acme',
        'pn-param': 'acme-param',
        'pn-prid': 'ZH11Y4ZDJlMNzODE1NgKi0K>'
    },
    sipDomain: 'domain',
    sipOptions: {
        session_timers: false,
        extraHeaders: [ 'X-Bar: bar' ],
        pcConfig: {},
    },
    modules: [ 'audio', 'video', 'msrp' ]
})

// Then you can work with the appropriate modules
opensipsJS.audio
opensipsJS.video
opensipsJS.msrp

Using via CDN:

After including the script via CDN, you can access the OpensipsJS class directly from the global scope.

<!DOCTYPE html>
<html>
<head>
  <title>OpensipsJS CDN Usage</title>
</head>
<body>
  <!-- Include the library via CDN -->
  <script src="https://cdn.opensipsjs.org/opensipsjs/v0.1.1/opensips-js.iife.js"></script>

  <script>
    // Create an instance of OpensipsJS
    const opensipsJS = new OpensipsJS({
      configuration: {
        session_timers: false,
        uri: 'sip:extension_user@domain',
        // --- Use password or authorization_jwt to authorize
        password: 'password',
        // or
        authorization_jwt: 'token',
      },
      socketInterfaces: ['wss://domain'],
      pnExtraHeaders: {
        'pn-provider': 'acme',
        'pn-param': 'acme-param',
        'pn-prid': 'ZH11Y4ZDJlMNzODE1NgKi0K>',
      },
      sipDomain: 'domain',
      sipOptions: {
        session_timers: false,
        extraHeaders: ['X-Bar: bar'],
        pcConfig: {},
      },
      modules: ['audio', 'video', 'msrp'],
    });

    // Now you can use the modules
    opensipsJS.audio;
    opensipsJS.video;
    opensipsJS.msrp;
  </script>
</body>
</html>

Note: When using the library via CDN, ensure that you replace 'sip:extension_user@domain', 'password', 'token', and other placeholders with your actual configuration values.

Using ES Modules via CDN:

If you prefer using ES modules in the browser and your environment supports them, you can import the ES module build directly from the CDN.

<!DOCTYPE html>
<html>
<head>
  <title>OpensipsJS ES Module CDN Usage</title>
</head>
<body>
  <script type="module">
    import OpensipsJS from 'https://cdn.opensipsjs.org/opensipsjs/v0.1.1/opensips-js.es.js';\

    const opensipsJS = new OpensipsJS({
        configuration: {
            session_timers: false,
            noiseReductionOptions: {
                mode: 'dynamic',
                noiseThreshold: 0.004
                checkEveryMs: 500
                noiseCheckInterval: 2000
            },
            uri: 'sip:extension_user@domain',
            // --- Use password or authorization_jwt to authorize
            password: 'password',
            // or
            authorization_jwt: 'token',
        },
        socketInterfaces: ['wss://domain'],
        pnExtraHeaders: {
            'pn-provider': 'acme',
            'pn-param': 'acme-param',
            'pn-prid': 'ZH11Y4ZDJlMNzODE1NgKi0K>',
        },
        sipDomain: 'domain',
        sipOptions: {
            session_timers: false,
            extraHeaders: ['X-Bar: bar'],
            pcConfig: {},
        },
        modules: ['audio', 'video', 'msrp'],
    });

    // Use the modules as before
    opensipsJS.audio;
    opensipsJS.video;
    opensipsJS.msrp;
  </script>
</body>
</html>

Important: When using ES modules via CDN:

Ensure your browser supports ES modules.
The type="module" attribute is necessary in the <script> tag.

OpensipsJS

OpensipsJS instance methods

begin(): OpensipsInstance - start opensips
on(event: OpensipsEvent, callback): void - remove event listener
subscribe({type: String, listener: function}): void - subscribe to an event. Available events: new_call, ended, progress, failed, confirmed
removeIListener(type: String): void - remove event listener

OpensipsJS events

| Event | Callback interface | Description | |---------------------------------|----------------------------------------------------------|-------------------------------------------------------| | ready | () => {} | Emitted when opensips is initialized | | changeActiveCalls | (calls: { [key: string]: ICall }) => {} | Emitted when active calls are changed | | callAddingInProgressChanged | (callId: string / undefined) => {} | Emitted when any call adding state is changed | | changeAvailableDeviceList | (devices: Array<MediaDeviceInfo>) => {} | Emitted when the list of available devices is changed | | changeActiveInputMediaDevice | (deviceId: string) => {} | Emitted when active input device is changed | | changeActiveOutputMediaDevice | (deviceId: string) => {} | Emitted when active output device is changed | | changeMuteWhenJoin | (value: boolean) => {} | Emitted when mute on join value is changed | | changeIsDND | (value: boolean) => {} | Emitted when is DND value is changed | | changeIsMuted | (value: boolean) => {} | Emitted when mute value is changed | | changeActiveStream | (stream: MediaStream) => {} | Emitted when active stream was changed | | changeCallVolume | (callId: string, volume: number) => {} | Emits the volume meter's value for each participant | | currentActiveRoomChanged | (number / undefined) => {} | Emitted when active room is changed | | addRoom | ({room: IRoom, roomList: {[id: number]: IRoom}}) => {} | Emitted when new room was added | | updateRoom | ({room: IRoom, roomList: {[id: number]: IRoom}}) => {} | Emitted when room was updated | | removeRoom | ({room: IRoom, roomList: {[p: number]: IRoom}}) => {} | Emitted when room was deleted |

WebrtcMetricsConfigType

| Parameter | Type | Default | |----------------|-----------|-------------| | refreshEvery | number | undefined | | startAfter | number | undefined | | startAfter | number | undefined | | verbose | boolean | undefined | | pname | string | undefined | | cid | string | undefined | | uid | string | undefined | | record | boolean | undefined | | ticket | boolean | undefined |

Also, there are next public fields on OpensipsJS instance:

OpensipsJS instance fields

sipDomain: String - returns sip domain

Audio

Audio methods

initCall(target: String, addToCurrentRoom: Boolean, holdOtherCalls: Boolean): void - call to the target. If addToCurrentRoom is true then the call will be added to the user's current room
holdCall(callId: String, automatic?: Boolean): Promise<void> - put call on hold
unholdCall(callId: String): Promise<void> - unhold a call
terminateCall(callId: String): void - terminate call
moveCall(callId: String, roomId: Number): Promise<void> - Same as callChangeRoom. Move call to the specific room
transferCall(callId: String, target: String): void - transfer call to target
mergeCall(roomId: Number): void - merge calls in specific room. Works only for rooms with 2 calls inside
mergeCallByIds(firstCallId: string, secondCallId: string): void - merge 2 calls by their ids
answerCall(callId: String): void - answer a call
mute(): void - mute ourself
unmute(): void - unmute ourself
muteCaller(callId: String): void - mute caller
unmuteCaller(callId: String): void - unmute caller
setMicrophone(deviceId: String): Promise<void> - set passed device as input device for calls
setSpeaker(deviceId: String): Promise<void> - set passed device as output device for calls
setActiveRoom(roomId: Number): Promise<void> - switch to the room
setMicrophoneSensitivity(value: Number): void - set sensitivity of microphone. Value should be in range from 0 to 1
setSpeakerVolume(value: Number): void - set volume of callers. Value should be in range from 0 to 1
setDND(value: Boolean): void - set the agent "Do not disturb" status
setMetricsConfig(config: WebrtcMetricsConfigType): void - set the metric config (used for audio quality indicator)
setVADConfiguration(options: Partial<Omit<NoiseReductionOptions, 'vadModule'>>): void - update noise reduction configuration at runtime. Requires vadModule to be passed in the constructor, otherwise throws an error

Audio instance fields

sipOptions: Object - returns sip options
getActiveRooms: { [key: number]: IRoom } - returns an object of active rooms where key is room id and value is room data
sipDomain: String - returns sip domain
sipOptions: Object - returns sip options
getInputDeviceList: [] - returns list of input devices
getOutputDeviceList: [] - returns list of output devices
currentActiveRoomId: Number - returns current active room id
selectedInputDevice: String - returns current selected input device id
selectedOutputDevice: String - returns current selected output device id
isDND: Boolean - returns if the agent is in "Do not disturb" status
isMuted: Boolean - returns if the agent is muted

Noise Reduction Options (VAD)

Important: Voice Activity Detection (VAD) is an optional feature that requires installing an additional peer dependency. It is NOT compatible with React Native.

Critical: VAD Module Must Be Passed to Constructor

If you plan to use noise reduction features (including setVADConfiguration in runtime), you MUST pass vadModule to the OpenSIPSJS constructor during initialization.

✅ Required: Pass vadModule in the constructor if you want to use noise reduction
❌ Will throw error: Calling setVADConfiguration() without vadModule in the constructor will throw an error
⚠️ Cannot be changed later: The vadModule cannot be set after initialization - it must be provided in the constructor

For Web Applications (with VAD support)

Install the VAD library:

npm install @ricky0123/vad-web
# or
yarn add @ricky0123/vad-web

Then import and inject it in your configuration during initialization:

import OpenSIPSJS from 'opensips-js'
import * as VAD from '@ricky0123/vad-web'

const opensipsJS = new OpenSIPSJS({
  configuration: {
    // ... other configuration
    noiseReductionOptions: {
      mode: 'dynamic', // or 'enabled'
      vadModule: VAD,  // ⚠️ REQUIRED: Must be passed here if you plan to use noise reduction
      noiseThreshold: 0.004,
      checkEveryMs: 500,
      noiseCheckInterval: 2000
    }
  },
  // ... rest of configuration
})

// ✅ Now you can use setVADConfiguration
opensipsJS.audio.setVADConfiguration({
  mode: 'enabled',
  noiseThreshold: 0.005
})

For Chrome MV3 Extensions

Chrome Manifest V3 extensions block dynamic imports from external sources at the browser level. To use VAD in a Chrome MV3 extension, you must bundle the VAD assets locally.

1. Copy required files to your extension:

From node_modules/@ricky0123/vad-web/dist/:

silero_vad_legacy.onnx
silero_vad_v5.onnx
vad.worklet.bundle.min.js

From node_modules/onnxruntime-web/dist/:

ort-wasm-simd-threaded.mjs
ort-wasm-simd-threaded.wasm

Place them in your extension directory (e.g., assets/vad/ and assets/onnx/).

Note: The exact ONNX files needed may vary depending on browser capabilities. If you encounter loading errors, you may also need ort-wasm-simd-threaded.jsep.wasm or other variants from the onnxruntime-web/dist/ folder.

2. Configure OpenSIPSJS with local paths:

import OpenSIPSJS from 'opensips-js'
import * as VAD from '@ricky0123/vad-web'

const opensipsJS = new OpenSIPSJS({
  configuration: {
    // ... other configuration
    noiseReductionOptions: {
      mode: 'dynamic',
      vadModule: VAD,
      // Point to locally bundled assets
      baseAssetPath: browser.runtime.getURL('assets/vad/'),
      onnxWASMBasePath: browser.runtime.getURL('assets/onnx/')
    }
  },
  // ... rest of configuration
})

Note: If your extension page is opened via browser.windows.create() or similar (extension's own context), you don't need web_accessible_resources. The extension can access its bundled files directly.

For React Native Applications (VAD not supported)

Simply omit the VAD module and disable noise reduction:

import OpenSIPSJS from 'opensips-js'

const opensipsJS = new OpenSIPSJS({
  configuration: {
    // ... other configuration
    noiseReductionOptions: {
      mode: 'disabled'  // or omit noiseReductionOptions entirely
    }
    // NO vadModule needed
  },
  // ... rest of configuration
})

See VAD_USAGE.md and EXAMPLES.md for detailed usage examples.

Configuration Parameters

| Parameter | Type | Default | Description | |----------------------|----------------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | mode | disabled \| enabled \| dynamic | disabled | Noise reduction mode. Note: enabled and dynamic modes require vadModule to be provided | | vadConfig | Partial<RealTimeVADOptions> | {} | VAD configuration | | noiseThreshold | number | 0.004 | Noise threshold | | noiseCheckInterval | number | 2000 | The interval, used to check if we need to disable/enable outgoing audio every N-milliseconds | | checkEveryMs | number | 500 | The interval, used inside noiseCheckInterval loop, checks current noise state every N-milliseconds, to define the average noise level. Then on every noiseCheckInterval iteration, the values getting on checkEveryMs will be summed, then divided by it's number and compared to noiseThreshold | | baseAssetPath | string | https://cdn.jsdelivr.net/npm/@ricky0123/[email protected]/dist/ | Base path for VAD web assets. For Chrome MV3 extensions, use local bundled path via browser.runtime.getURL() | | onnxWASMBasePath | string | https://cdn.jsdelivr.net/npm/[email protected]/dist/ | Base path for ONNX runtime WASM files. For Chrome MV3 extensions, use local bundled path via browser.runtime.getURL() |

MSRP

MSRP methods

initMSRP(target: String, body: String): void - initialize connection with target contact. Body is the initial message to this target.
sendMSRP(sessionId: String, body: String): Promise<void> - send message
msrpAnswer(sessionId: String) - accept MSRP session invitation
messageTerminate(sessionId: String) - terminate message session

MSRP instance fields

getActiveMessages: { [key: string]: IMessage } - returns an object of active message sessions where key is session id and value is message session data.

Video

Video methods

joinRoom(roomId: String, displayName: String, mediaConstraints: Object): void - join conference room
hangup() - exit room
startVideo() - turn on camera
stopVideo() - turn off camera
startAudio() - mute
stopAudio() - unmute
startScreenShare() - start screen sharing
stopScreenShare() - stop screen sharing
enableScreenShareWhiteboard(enable: boolean, stream: MediaStream) - enable screen share whiteboard. stream parameter is screen share stream
enableBokehEffectMask(): Promise<MediaStream> - enable bokeh mask effect
enableBackgroundImgEffectMask(): Promise<MediaStream> - enable background image mask effect
disableMask(): Promise<MediaStream> - turn off mask effect. Returns stream without masking
restartMasking(): Promise<void> - rerun mask effect
setupMaskVisualizationConfig(config: VisualizationConfigType) - setup mask config
startNoiseFilter() - start noise filter
stopNoiseFilter() - stop noise filter
setBitrate(bitrate: number) - set bitrate for video
enableWhiteboard(mode: 'whiteboard' | 'imageWhiteboard', enable: boolean, base64Image?: string) - enable whiteboard. if mode is 'imageWhiteboard' then third parameter base64Image is required
setupDrawerOptions(options: KonvaDrawerOptions) - setup option for drawer
setupScreenShareDrawerOptions(options: KonvaScreenShareDrawerOptions) - setup option for screen share drawer

VisualizationConfigType

| Parameter | Type | Default | |-----------------------|----------|---------| | foregroundThreshold | number | 0.5 | | maskOpacity | number | 0.5 | | maskBlur | number | 0 | | pixelCellWidth | number | 10 | | backgroundBlur | number | 15 | | edgeBlur | number | 3 |

KonvaDrawerOptions

| Parameter | Type | |-------------|----------| | container | number | | width | number | | height | number |

KonvaScreenShareDrawerOptions

| Parameter | Type | |---------------|----------| | strokeWidth | number | | strokeColor | string |

Video events

| Event | Callback interface | Description | |--------------------------|--------------------|-------------------------------------------| | member:join | (data) => {} | Emitted when new member is joined | | member:update | (data) => {} | Emitted when member data is changed | | member:hangup | (data) => {} | Emitted when member leaves the conference | | hangup | () => {} | Emitted when we leave the conference | | screenShare:start | () => {} | Emitted when we share a screen | | screenShare:stop | () => {} | Emitted when we stop a screen sharing | | reconnect | () => {} | Emitted when reconnecting | | mediaConstraintsChange | () => {} | Emitted when media constraints change | | metrics:report | () => {} | Emitted on metric report | | metrics:stop | () => {} | Emitted when metrics are stopped |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

title: Getting started description: The Opensips JS library and its expansive ecosystem offer developers a powerful and flexible solution for integrating Opensips protocol functionalities into a multitude of applications. navigation: title: Getting Started

Getting started

Installation

Using npm:

Using via CDN:

Usage

Using npm (ES Modules):

Using via CDN:

Using ES Modules via CDN:

OpensipsJS

OpensipsJS instance methods

OpensipsJS events

OpensipsJS instance fields

Audio

Audio methods

Audio instance fields

Noise Reduction Options (VAD)

Critical: VAD Module Must Be Passed to Constructor

For Web Applications (with VAD support)

For Chrome MV3 Extensions

For React Native Applications (VAD not supported)

Configuration Parameters

MSRP

MSRP methods

MSRP instance fields

Video

Video methods

Video events