Web Call Server - Specification2
© 2016 Flashphoner, LLC
0
Contents
Part I Deployment diagram 4
Part II Environment prerequisites 7
................................................................................................................................... 71 Browser
................................................................................................................................... 82 SIP server, VoIP hardware
................................................................................................................................... 83 SIP, VoIP devices
................................................................................................................................... 84 Web Server
................................................................................................................................... 95 IP camera or RTSP server
Part III Specification 11
Part IV Functions 15
Part V Program interfaces 20
................................................................................................................................... 201 WCS JavaScript API
................................................................................................................................... 212 WCS RESTful API
Part VI Control interfaces 24
0
Web Call Server - Specification
© 2016 Flashphoner, LLC
4Deployment diagram4
1 Deployment diagram
Web Call Server has two main applications - a browser-based messenger integrated to the existing SIP-hardware and a streaming video server able to exchange video streams by means of WebRTC and playvideo streams from standalone IP-cameras. Depending on the application, one of the followingdeployment diagrams can be used:
Web-messenger
This diagram illustrates deployment of a browser-based telephone or a messenger to integrate with theexisting equipment and to allow users making and receiving SIP calls and messages from a web-browser without installing any third-party software.
Diagram subjects:
Browser of a user.Web Call Server.SIP, VoIP hardware of the Operator.Web Server.SIP, VoIP devices or telephones to establish communication with from a browser.
© 2016 Flashphoner, LLC
5Deployment diagram
Streaming video Web server
The streaming video server performs exchange of video streams from browsers and playing videostreams from IP cameras via WebRTC.
Diagram subjects:
Browser of a user.Web Call Server.IP-camera or RTSP server
Therefore, a deployment diagram can involve up to six types of subjects, and each one should supportthe required set of protocols and technologies to fulfill telephony and streaming video tasks:
1. Browser of a user.2. Web Call Server.3. SIP, VoIP hardware.4. Web Server.5. SIP, VoIP devices or telephones to establish communication with from a browser.6. IP-camera or RTSP server.
© 2016 Flashphoner, LLC
7Environment prerequisites
2 Environment prerequisites
For successful operation of the system, the environment should meet certain conditions.
2.1 Browser
Supported browsers
Web Call Server works with the latest versions of the following browsers:
Win Lin Android Mac
Chrome WebRTC WebRTC WebRTC WebRTC
Firefox WebRTC WebRTC WebRTC WebRTC
Opera WebRTC WebRTC WebRTC WebRTC
IE Flash
Safari Flash Flash
HTML5 Websocket and WebRTC technologies are used to provide operation of the system in a browser.Safari and IE browsers do not support the WebRTC technology, therefore Flash Player is used totransmit and play audio and video in them.
If a user browser supports neither Flash nor WebRTC, the user should install a WebRTC plugin for thebrowser or the latest version of Flash Player to be able to work with audio and video in the browsercorrectly.
Browser-side technologies
The list of technologies used at the browser-side:HTML5 WebsocketsWebRTCFlashJQueryJavaScript
Browsertechnology
Description
HTML5Websockets
Serves for signaling, that is, for non-streaming data exchange between the browserand the server. Basically, the following information is exchanged:
commands (connect, disconnect, call, call rejection, answer, send message andothers).events (incoming call, incoming message).status events (incoming call status changed, message is delivered, messagedelivery failed and so on).
WebRTC Sends streaming audio and video to the server and back via the secure SRTP
Web Call Server - Specification
© 2016 Flashphoner, LLC
8Environment prerequisites8
Browsertechnology
Description
protocol, performs compression, decoding of audio and video signals, videoplayback, echo cancellation and other DSP functions. Main supported codecs are:G.711, Opus, VP8.
Flash The WebRTC technology is a preferable way to transmit streaming data. However, ifa browser does not provide WebRTC support, the Flash technology will be used totransmit audio and video via the secure RTMFP protocol. Flash also has a stack ofDSP technologies to work with audio and video. Main supported codecs are: G.711,Speex, H.264.
JQuery A popular web development framework used in WCS API for cross-browser workingwith HTML5 Websockets and AJAX requests.
JavaScript /CSS
Technologies to build and manage user interfaces. Front-end developers can makeapplications with their own design using JavaScript and CSS via the clientJavaScript-powered WCS API.
2.2 SIP server, VoIP hardware
The main prerequisite to SIP hardware is the support for SIP and RTP protocols and the compatible setof codecs. You can learn protocols and codecs supported by your SIP server in the specification to yourSIP hardware or software. If you use a third-party SIP-provider, you can request this information from it.Protocols and codecs WCS supports are listed in the Specification section.
WCS was tested with many SIP proxy and PBX servers including:
AsteriskOpenSIPsFreeswitchCommunigate ProCisco Call ManagerGenesysSamsung IMSand others ...
Sometimes a SIP-server is configured in a special way resulting in certain WCS integration problems.Web Call Server offers a number of settings to configure WCS for normal operation on virtually any givenSIP-server as long as this software or hardware complies to SIP specifications. For more information onconfiguring WCS, please refer to Web Call Server - Administrator manual.
2.3 SIP, VoIP devices
The end-point VoIP devices have the same requirements as SIP server and VoIP hardware, that is,codecs must be compatible and the support for SIP and RTP protocols is required.
2.4 Web Server
WCS interacts with a Web-server via REST / HTTP API. The Web-server should support HTTP andHTTPS protocols. Any server technology can be used on the web-server side.
Examples of server-side technologies
© 2016 Flashphoner, LLC
9Environment prerequisites
PHPJSPASPCGIRails
Web-servers
ApacheIISNginxTomcatetc.
2.5 IP camera or RTSP server
WCS can fetch a video stream from an IP camera or an RTSP server via RTSP / RTP protocols. To playsuch a stream correctly, the IP camera or the RTSP server should support RTSP and RTP protocols andhave a WCS-compatible set of codecs.
© 2016 Flashphoner, LLC
11Specification
3 Specification
System requirements
Web Call Server is a server-side software that can be deployed under 64-bit OS Linux x86_64.
Minimum requirements to server configuration are:Linux x86_64512 MB of RAM1 GB of disk space1 CPU coreNetwork card
Recommended requirement to the working server:16 GB of RAM2 x CPU Xeon, 4-6 cores for each CPU100 GB of disk spaceSSD disk
Specification
The table below lists all supported technologies, specifications, protocols and codecs divided onto fivesections:
Browser interactionSIP hardware and devices interactionIP-camera and RTSP-server interactionWeb-server interactionCodecs
Technolgoy Specifications
Browser interaction
HTML5 RFC6455 - Websockets
WebRTC
RFC5245 - ICERFC4347 - DTLSRFC3711 - SRTPdraft-ietf-rtcweb-rtp-usage - RTP usage webrtc draftdraft-ietf-rtcweb-audio - Audio usage webrtc draftdraft-ietf-rtcweb-jsep - jsep webrtc draft
FlashRFC7016 - RTMFPamf-file-format-spec - AMF3
SIP hardware and devices interaction
VoIP
SIP
RFC3261 - SIPRFC4566 - SDP
Web Call Server - Specification
© 2016 Flashphoner, LLC
12Specification12
Technolgoy Specifications
RFC2976 - SIP INFORFC3264 - Offer / AnswerRFC3265 - Specific EventRFC3515 - SIP REFER
SIP Messaging
RFC3428 - SIP MESSAGERFC3860 - CPIMRFC5438 - IMDNRFC4975 - MSRP Server
RTP
RFC3550 - RTPRFC3551 - RTP / AVPRFC4961 - Symmetric RTPRFC2833 - DTMF
RTP Audio
RFC5391 - G.711 RTPRFC5574 - Speex RTPdraft-spittka-payload-rtp - Opus RTP
RTP Video
RFC4629 - H.263 RTPRFC6184 - H.264 RTPdraft-ietf-payload-vp8 - VP8 RTP
IP-camera and RTSP-server interaction
RTSP Client RFC2326 - RTSP
RTP См. VoIP.
Web-server interaction
Web
RFC2616 - HTTPRFC2818 - HTTPSREST - Representational State TransferJSON - JavaScript Object Notation
Codecs
© 2016 Flashphoner, LLC
13Specification
Technolgoy Specifications
Audio G.711, Opus,Speex, G.722, G.729
Video VP8, H.264
© 2016 Flashphoner, LLC
15Functions
4 Functions
The description of Web Call Server functions is divided onto four parts:
WebRTC Audio Calls, SIP, MessagingWebRTC Video CallsFlash Video CallsWebRTC Broadcasting
Function Description Purpose Limitation
WebRTC Audio Calls, SIP, Messaging
1. Browser- BrowserG.711,Opus calls
Calls between twoWebRTC-compatiblebrowsers can beestablished both via aSIP server and withoutit.
Browser-browser call service without apossibility to call to SIP devices oraccepting calls from SIP devices. A simpleaudio chat.
Audio codecs:G.711, Opus inthe proxy mode(no transcoding).
2. Browser- SIP / GSMG.711,Opus calls
Calls between aWebRTC browser and aSIP device including asoftphone, a stationaryphone, a mobile phoneand any othercompatible deviceconnected to SIP orVoIP hardware.
Outgoing calls from a browser to SIPdevices, stationary and mobile telephones.Calls to telephones are supported as longas the VoIP operator allows that. Also,there's no difference between a SIP deviceand a mobile phone for a browser. SIP/RTPto GSM conversion is performed by theintermediate gate. WCS talks to this gatevia the standard SIP/RTP protocols.
Audio codecs:G.711, Opus inthe proxy mode(no transcoding).
3. Browser- SIP/GSMG.729 calls
Supports calls between SIP devices, whereG.729 is the only compatible codec toestablish a call.
Audio codec:G.729 in the G.711-G.729transcodingmode forcompatibilitywith WebRTC,where G.729 isnot supported.
4. PlainInstantMessaging
Sending of shortmessages incompliance with rfc3428specification bothbetween browsers andbetween a browser anda SIP device or atelephone.
Text chat, messenger, broadcasting ofmessages from a browser to SMSmessage at the operator side.
The text/plainformat of themessage
5. SIPSIMPLEInstantMessaging
Extended support formessages thanks toSIP SIMPLE, CPIM,IMDN, MSRP
An extended profile to work with messages,one-to-many message sending, support fordelivery notifications, gathering of deferredmessages from a server via MSRP, text/
Currently, thereis no support forSIP Presence
Web Call Server - Specification
© 2016 Flashphoner, LLC
16Functions16
Function Description Purpose Limitation
specifications. xml messages processing.
6. Hold andTransfer
Hold and transfer ofcalls. Supports rfc3515SIP REFER
Out a call on hold, resume a call, transfer ofa call to another subscriber working in aweb-browser or from a SIP device.Processing of holds and transfers initiatedby devices the call is established with.
7. DTMFRFC 2833and SIPINFO
Usage of 'tone dialing' towork with IVRinteractive voice menus.DTMF-signal can besent using one of twoways: SIP INFO as aSIP-message andrfc2833 as RTPpackets.
Used to work with voice menus.
For example: "Press 3 to connect to theoperator".
When the specified button is pressed onthe side of the telephone interface, theserver receives the DTMF command andmenu responds.
"You have selected the third command andwill be redirected to the operator".
8. AudioCallRecording
Recording audio call inthe wav format.
Usually calls are recorded on the side ofthe SIP-server. In addition, recording of acall on the side of WCS is also available.The settings specify a folder on the serverto store calls - audio files of all calls in theraw wav format.
Currently, thisfeature is still indevelopment andis available uponrequest.
9. FlashFallback.
Automatic switching ofaudio calls to Flash forthose browsers that donot support WebRTC.
WebRTC is not supported in IE and Safaribrowsers. In that case two options areavailable:Offer a user to download and install aWebRTC plugin for the given browser or usethe built-in Flash Player to call.
The ‘Flash Fallback’ function providesautomatic switching to Flash Player. It isonly available for audio calls (functions 1, 2,3, 6, 8).
Supports thelatest version ofFlash Playeravailable for thegiven browserand OS.
WebRTC Video Calls
Function Description Purpose Limitation
1. Browser- BrowserVP8 calls
Calls between twoWebRTC-compatiblebrowsers. See 'Browser- Browser G.711, Opuscalls'.
A video call service.
Videocodec:VP8 inthe proxy mode(no transcoding).2. Browser
- SIP VP8Calls between aWebRTC browser and a
Outgoing video calls from a browser to SIPdevices.
© 2016 Flashphoner, LLC
17Functions
Function Description Purpose Limitation
calls SIP device. See 'Browser - SIP / GSMG.711, Opus calls'.
3. Browser- SIP VP8 -H.264 calls
Transcoded VP8-H.264calls between aWebRTC browser and aSIP device.
Transcoded calls are necessary when abrowser on one side and a SIP device oranother browser to connect on the otherside use different video codecs and there isno way to select the same codec andtherefore avoid transcoding. For example, ifan Android WebRTC-compatible browsercalls to a SIP device that supports onlyH.264, there is no option to use the samecodec, and therefore VP8-H.264transcoding is required.
VP8 - H.264transcoding forcompatibilitybetween devicesand softwarethat do not havea codec theyboth share.
Flash Video Calls
Function Description Purpose Limitation
1. Browser- BrowserH.264 calls
Calls between twoFlash browsers. See'Browser - BrowserG.711, Opus calls'.
A video call service. Video codec:H.264 in thetranscodingmode (notranscoding).
2. Browser- SIP H.264calls
Calls between a Flashbrowser and a SIPdevice using H.264video. See 'Browser -SIP / GSM G.711,Opus calls'.
Outgoing video calls from a browser to SIPdevices.
Video codec:H.264.Transcoding tothe compatibleFlash format ifnecessary.
WebRTC Broadcasting
Function Description Purpose Limitation
1. WebRTCBroadcastingBetweenWebBrowsers
Publishing and playingof WebRTC audio andvideo streams.
WebRTC one-to-many audio and videobroadcasting, video chat or videoconferences with several participants.
Only forWebRTC-compatiblebrowsers.
2. WebRTCBroadcastingBetweenRTSP IPCam andBrowsers
Playing video fromstationary IP-camerasvia the RTSP/RTPprotocol. Video form IP-cameras is played in aWebRTC browser.
WebRTC online broadcasting from IP-cameras and surveillance systems througha central server.
Supportedcodecs:
Video: VP8,H.264Audio: G.711,Opus
3. WebRTC Playing WebRTC video WebRTC online broadcasting, when the Supported
Web Call Server - Specification
© 2016 Flashphoner, LLC
18Functions18
Function Description Purpose Limitation
Broadcasting UsingArbitraryThird partyRTSPserver.
from RTSP servers. source of the video is an arbitrary RTSP-server broadcasting a video stream.
codecs:
Video: VP8,H.264Audio: G.711,Opus
Web Call Server - Specification
© 2016 Flashphoner, LLC
20Program interfaces20
5 Program interfaces
Web Call Server has two program interfaces: WCS JavaScript API on the side of a browser and WCSRESTful API on the side of a Web-server. These program interfaces are synchronized. This means whenyou invoke the 'connect' method of WCS JavaScript API, the same method with the same parameters isinvoked on the web-server using the RESTful API:
Another example is as follows. Let us say, an incoming call to the Web-server is received. Acorresponding event object OnCallEvent containing all required data about the incoming call is receivedthen via the REST API. And the same event is passed to the browser through the WCS JavaScript API:
All methods, events and parameters of WCS JavaScript API and WCS RESTful API are explained in alldetails in Web Call Server - Call Flow.
5.1 WCS JavaScript API
This program interface is designed for front-end development and contains a number of functions tomanage calls, messages, broadcasting and playing of video streams. Using Javascript API you can buildany user interface required. API builds and the source code are available at these URLs:
Builds - http://flashphoner.com/downloads/builds/flashphoner_client/wcs_api/Source code - https://github.com/flashphoner/flashphoner_client/tree/wcs_api
© 2016 Flashphoner, LLC
21Program interfaces
5.2 WCS RESTful API
This API provides for a deeper integration to the back-end and to the database of the web-system thatSIP calls and stream video functions provided by the WCS server integrate to.
This program interface is optional and can be turned off. Besides, it offer a flexible configuration of theWCS REST API and enabling this interface only for certain method invocations. For instance, REST APIcan be turned on only for authentication procedure in the 'connect' method, while for all other methodsincluding 'call', 'sendMessage' and others it can be turned off. If REST API is off, WCS uses data passedto it by the web-client using the WCS JavaScript API. To configure WCS JavaScript API on and offsettings, please refer to Web Call Server - Administrator Manual.
Statistics
This program interface allows Web Call Server to interact with the web-server representing a back-end ofthe system with a database. All WCS JavaScript API invocations as well as all WCS-server events(incoming SIP call, SIP call status change, incoming message etc.) are transmitted to the web-server viathe REST / HTTP / HTTPS protocol. Therefore, the back-end of the system receives information about allprocesses running on the WCS-server. For example, the web-server can keep statistics of what andwhen a user connected/disconnected from the server, when and where the calls were made, whatmessages and streams passed through the server.
Authentication
The very first connection with a WCS-server upon invocation of the 'connect' method on the side of WCSJavaScript API goes through authentication on the web-server. If the web-server doesn't allow theconnection, it isn't established.
Authorization
The next important function of WCS RESTful API after establishing connection and authentication isauthorization, that is an ability to permit or prohibit activity based on inner rules. The Web-server, aback-end of the system can reject any call from WCS JavaScript API, for example, an incoming call,message, stream broadcast and so on. An incoming SIP call or message can also be rejected by theWeb-server with the appropriate error status sent to the calling party.
Web Call Server - Specification
© 2016 Flashphoner, LLC
22Program interfaces22
Sending arbitrary parameters
Invocation to the Web-server is performed by means of REST / JSON objects. This allows passing anyadditional parameters from WCS JavaScript API to the Web-server. For instance, a front-end developercan pass information about the browser, OS and other data available on a web page to the back-endwhen the connection is established as individual parameters. Data are passed to a Web-server by thefollowing path: WCS JavaScript API > WCS сервер > Web-server.
Redefining data
Another REST API function is redefining of data, received from the WCS-server. For example, when thecall({to:'to'}) function is invoked from WCS JavaScript API to make an outgoing SIP call, you can redefinethe 'to' parameter on the side of the Web-server and replace it with the real number of a callee. This canbe used to hide the callee number from the user of the service. Another example is adding an informationblock to all messages sent. In this case, the Web-server redefines sendMessage({text:'text'}) andreplaces the original text with the text of an information block.
Data exchange
A user of a browser connects to a WCS server using the Websockets protocol. REST API can perform acallback to send arbitrary data from the Web-server to this particular user. There is the sendData({})method available in WCS JavaScript API for direct invocation. Therefore, a web-developer can implementhis own data exchange, for example, create a video chat with its own signaling not tied to SIP.
Web Call Server - Specification
© 2016 Flashphoner, LLC
24Control interfaces24
6 Control interfaces
The command line interface is used to control Web Call Server, as well as direct access to configurationfiles, start and stop scripts of a server. The following functions are available in the control interface:
user managementaccess permission managementapplication managementREST API settings managementstopping and restarting the server
WCS server command line can be accessed by SSH. The complete list of command and command lineinterface configuration is available in Web Call Server - Administrator Manual.