Instant TotalRecorder¶

TotalRecorder is Instant Solution’s display recording solution. The easiest way to use it is together with InstantVoice, but this is by no means a requirement. ITR is a stand alone solution which can be used alongside any PBX or even no PBX at all.

The first part of this document covers the installation procedure. The second part is about the basic configuration which will be needed in any case.

The third part talks about integration with InstantVoicei. If you plan to use a different PBX, feel free to skip directly to the fourth part, that has an extensive description of our SDK.

Installation¶

Server Installation¶

Note

We currently only provide binaries as RPMs to RHEL/CentOS 5.x/6.x. If you need to install on other plaftorms, contact our technical team.

Setting up an IV box¶

We strongly suggest that you use a fresh InstantVoice3.5 install to host the ITR server. If you prefer to use a vanilla CentOS 5 server, you may skip these steps.

To do this, install a fresh InstantVoice of the same version you are using, access the localadmin interface and disable all services in Local/Services.

After that you will need to re-enable the default CentOS yum repos by creating the file /etc/yum.repos.d/CentOS.repo and pasting the following content in it:

[CentOS5base]
name=CentOS-5-Base
mirrorlist=http://mirrorlist.centos.org/?release=5&arch=$basearch&repo=os
gpgcheck=0
enabled=1
gpgkey=http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5

[CentOS5updates]
name=CentOS-5-Updates
mirrorlist=http://mirrorlist.centos.org/?release=5&arch=$basearch&repo=updates
gpgcheck=0
enabled=1
gpgkey=http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5

[CentOS5plus]
name=CentOS-5-Plus
mirrorlist=http://mirrorlist.centos.org/?release=5&arch=$basearch&repo=centosplus
gpgcheck=0
enabled=1
gpgkey=http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5

Now we remove the package instantvoice-mpg123 to avoid a dependency conflict in the next step. Open a shell and, as root, execute the following:

rpm -e instantvoice-mpg123 --nodeps

Installling TotalRecorder¶

First we need to install ITR’s dependencies. For that, we will need both rpmforge and epel enabled.

To add rpmforge go to http://packages.sw.be/rpmforge-release/ and dowload the latest release for CentOS 5 32bit. Then install it by running the following command as root on a terminal:

rpm -i rpmforge-release-<version>.el5.rf.i386.rpm

Now we need to enable EPEL, go to http://epel.gtdinternet.com/5/i386/repoview/epel-release.html, download the latest release and run as root:

rpm -i epel-release-<version>.noarch.rpm

Now we can finally install Instant TotalRecorder Server and it’s dependencies. Enter the Linux shell as root and run the following commands:

yum install ffmpeg mencoder python-webpy-0.36 wine-1.2.3 mod_wsgi xorg-x11-server-Xorg
yum install itr

Or, in case you’re updating a previous installation:

rpm -Fvh itr-<version>.rpm

With “version” corresponding to the file you were provided.

Upon installation, the ITR Encoding Service is registered under the Daemontools mechanism. If Daemontools is not installed, you have to start the encoding service by running the script /opt/instant/itr/itrencodemaster – you can make it start automatically by calling it from /etc/rc.local (or whichever other startup script your distribution uses). Include this line in the script:

/opt/instant/itr/itrencodemaster >/dev/null 2>&1 &

Note

The ITR Encoding Service sends its log and debug messages to syslog.

If a reboot is required (upgrade only) the installation command will display a message to instruct you so.

Note

ITR Server runs under the Apache web server (httpd); therefore, the httpd service must be running. It is recommended to restart httpd after installing TotalRecorder, if it was running beforehand.

Client Installation¶

Note

You will need to repeat those steps on every machine that will be recorded.

Double-click the ITRSetup.msi file and follow the installation steps. You will need administrator priveleges.

TotalRecorder Configuration¶

Server Configuration¶

For the server portion, ITR provides a web based interface for configuration. To access it, point your browser to http://<your-server>:8080/itr/admin. The default login is: itradmin and the password: itrapi. It is recommended that you change those right away.

Note

You will need to reboot the server for those changes to take effect.

API Parameters¶

Those are the basic API parameters. If you are going to follow the integration with InstantVoice path, there’s no need to worry about these. For those writing their own integrations, a more in depth description is available in the SDK portion of this document.

Field	Description
User	This is the username to be used for the http authentication for all api calls.
Password	This is the password to be used for the http authentication for all api calls. Defaults to itrapi.
Admin User	This is the username used to access this configuration interface.
Admin Password	This is the password used to access this configuration interface. Defaults to itrapi.

Database Parameters¶

You will need to create the following tables on a MySQL database and point ITR to this database using the parameters explained below.

Note

Currently, ITR only works with MySQL as the backend database. Support for other databases is planned for future versions.

CREATE TABLE `audiotracks` (
  `varname` varchar(64) NOT NULL,
  `varvalue` varchar(64) NOT NULL,
  `audiouri` varchar(64) NOT NULL,
  `registered` datetime NOT NULL,
  `retrieved` datetime DEFAULT NULL,
  PRIMARY KEY (`varname`,`varvalue`)
);

CREATE TABLE `captures` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `capturefile` varchar(512) NOT NULL,
  `videofile` varchar(512) DEFAULT NULL,
  `audiouri` varchar(64) DEFAULT NULL,
  `newaudiouri` varchar(64) DEFAULT NULL,
  `received` datetime NOT NULL,
  `requested` datetime DEFAULT NULL,
  `encodeproc` int(11) DEFAULT NULL,
  `hasaudio` tinyint(1) NOT NULL DEFAULT '0',
  `lasterr` text,
  PRIMARY KEY (`id`)
);

CREATE TABLE `metadata` (
  `capture` int(11) NOT NULL,
  `varname` varchar(64) NOT NULL,
  `varvalue` varchar(64) NOT NULL,
  PRIMARY KEY (`capture`,`varname`),
  KEY `varname` (`varname`,`varvalue`)
);

Field	Description
Host	The host of the MySQL database to be used.
Database	The database in which the ITR tables can be found.
User	A user that needs to have full read and write privileges to all ITR tables.
Password	The password for the user above.

This schema is provided by the installation package in /opt/instant/itr/itr.sql and can be installed with the following commands:

mysql -u root -e "CREATE USER 'USER'@'localhost' IDENTIFIED BY 'PASS';"
mysql -u root -e "GRANT ALL PRIVILEGES ON *.* TO 'USER'@'%' WITH GRANT OPTION";
mysql -u root -e "GRANT ALL PRIVILEGES ON *.* TO 'USER'@'localhost' WITH GRANT OPTION";
mysql -uUSER -pPASS -e "CREATE DATABASE YOUR-ITR-DB-NAME"
mysql -uUSER -pPASS YOUR-ITR-DB-NAME < /opt/instant/itr/itr.sql

Video Parameters¶

These parameters define the video quality. Sane defaults are written on install, so generally there’s no need to worry with them.

Field	Description
Frames per second	The amount of frames per second in the recordings. The default value is 24; the same of classic TV.
Max. Width	The maximum width a recorded video can have. If the recorded screen is smaller, this parameter won’t affect the final recording. The default value is 1280; for smaller, faster to retrieve video files, you may experiment smaller values like 1152, 1024, or even 800. However, don’t make it much smaller than the workstations’ native resolution.

Audio Parameters¶

TotalRecorder can also mix audio recordings together with the screen recordings if you provide an HTTP, HTTPS or FTP path for it to fetch those audio files. InstantVoice provides a way to do this through the ACD brick of your installation which will be described below.

Field	Description
Reference Field	This is the metadata field to be used as a key to match the audio recording.
URL	This is the URL ITR will use to fetch the audio file to be mixed into the screen recording. Insert ‘%s’ wherever you want the reference field data to be placed. Example: If the URL is “http://localhost:999/rec/%s.wav”, and the reference field is “callid”, ITR will first fetch the value of metadata variable “callid” for the capture it is currently processing. Presuming that variable has the value “37824678326”, ITR will convert that value to Base64, and replace the “%s” in the URL. It will then fetch the resulting URL, which in this case will be “http://localhost:999/rec/Mzc4MjQ2NzgzMjY=.wav” .
User	The user name needed if the URL above requires http authentication.
Password	The password needed if the URL above requires http authentication.

Client Configuration¶

If you installed the ITR client, you will find in your start menu a folder named Instant Solutions and the TotalRecorder Configuration inside of it.

Uploads Tab¶

Field	Description
ITR Server URL	This is the URL ITR will use to POST the capture file back to the server. You will want to change the ip address to point to your server but leave the rest of the URL intact.
ITR Server Username	This is the username to be user for the http auth as defined in the server web interface.
ITR Server Password	This is the password to be user for the http auth as defined in the server web interface.

Captures Tab¶

Field	Description
Client API Password	This is the password the third-party client software must use when connecting to ITRClient.
Capture Folder	This is the local folder where the recordings will be stored before being sent to the server.

Disclaimer Tab¶

Field	Description
Show disclaimer on Windows logon	TotalRecorder can display a small popup message coming from the tray icon on startup to inform the user that their actions might be recorded.
Display time	This is the amount of time in seconds the message will be displayed.
Title	This is the title of the message.
Text	This is the text to be displayed on the body of the popup message.

InstantVoice Integration¶

Configuring InstantVoice¶

On your installation’s web interface, chose Integration/TotalRecorder. There are two main parameter groups, TotalRecoder and Audio Tracks.

TotalRecoder¶

Field	Description
Hostname	Hostname or ip address of the TotalRecorder server.
Port	Port in which the TR web services are running.
User name	Username to be used for the http auth.
Password	Password to be used for the http auth.

Audio Tracks¶

Instantvoice provides an easy way for TotalRecorder to fetch the audio files to be mixed in the screen recordings. First define here a username and password.

Field	Description
User name	Username to be used in the http auth for the audio file retrieval method.
Password	Password to be used in the http auth for the audio file retrieval method.

After that, go back to the ITR server web configuration and in the Audio portion insert the following:

Reference Field: uniqueid
URL: http://<your-acd>/recordings/%s
User: The username defined above
Password: The password defined above

Configuring IVClient¶

As described in the Integration portion of the documentation, in IVClient’s configuration you will find a section called TotalRecorder Integration Configuration. There you should enter the following values:

Port: 5800
Password: The CLient API Password defined in the ITR client configuration

Retrieving Capture Videos¶

InstantVoice’s integration with TotalReocord makes extremely easy to retreive the screen capture videos. Simply search in the Advanced Reports for the call as you would to retriver the voice recording. The calls that have had it’s screen captures will have this new icon which links to the video file:

Instant TotalRecorder SDK¶

TotalRecorder Server API¶

This portion of the document describes the Application Program Interface for TotalRecorder Server. It is an HTTP REST API; therefore this document presumes familiarity, on the part of the reader, with HTTP protocol terminology (e.g. Request/Response Header/Body, Content-Type, GET, POST etc.) as well as with the XML data format.

TotalRecorder Server is deployed within a Web server like Apache. Therefore, all access will be through HTTP URIs that will have a common prefix; in our examples we will use <http://itrserver/itr> and the command URIs will consequently be of the form <http://itrserver/itr/commandname>.

Note

All XML data must have a charset of UTF-8. That means the Content-Type header must be ‘text/xml; charset=UTF-8’.
Calls that dowload files will return a file name with a sensible suffix in the Content-Disposition header. Browsers like that.

GET /captures - Obtain a list of video captures¶

Request body: None.

Query parameters (optional):

ts - A timestamp in SQL format (YYYY-MM-DD HH:MM:SS)
tsopt - Comparison operator to which the value of ts applies (‘=’, ‘>’, ‘<’, ‘>=’, ‘<=’ or ‘<>’)
vd - 0 to search for not-yet-encoded captures; 1 to search for encoded captures
f1 - First metadata field to search
o1 - Operator to apply on first metadata field (‘=’, ‘>’, ‘<’, ‘>=’, ‘<=’, ‘<>’, ‘LIKE’)
v1 - Value upon which to make the comparison with the field whose name is in f1 Analogously for f2-o2-v2, f3-o3-v3 etc.

For example, to list all captures in which (1) the metadata EMPLOYEE is equal to 041070, (2) the metadata CUST contains the string “BigCo”, (3) were made prior to May 19, 2012, and (4) there’s encoded video available, one would issue the following GET request:

GET /captures?vd=1&ts=2012-05-19%2000:00:00&tsopt=%3C&f1=EMPLOYEE&o1=%3D&v1=041070&f2=CUST&o2=LIKE&v2=%25BigCo%25

Note that the values of parameters in the query string are URL-encoded; for instance “=” becomes “%3D”.

Status codes:

400 Bad Request
500 Server Error
200 OK - XML list of matching captures in response body

Response body layout example:

<captures>
    <capture id="172">
        <videofile hasaudio="1">OK</videofile>
        <received>2012-06-05 15:39:02</received>
        <metadata>
            <var name="callid">1338998327.45234</var>
            <var name="operator">sford</var>
            <var name="customerid">142348952</var>
            <var name="_h">864</var>
            <var name="_w">1152</var>
        </metadata>
    </capture>
    <capture id="173">
        <videofile hasaudio="1">OK</videofile>
        <received>2012-06-05 15:42:57</received>
        <metadata>
            <var name="callid">1338998719.49834</var>
            <var name="operator">ahall</var>
            <var name="customerid">208548754</var>
            <var name="_h">864</var>
            <var name="_w">1152</var>
        </metadata>
    </capture>
</captures>

GET /audio/VarName/VarValue - Obtain audio track URI by metadata¶

Request body: None.

Query parameters: None

Status codes:

400 Bad Request
404 Not Found
500 Server Error
200 OK - XML description of matching audio track in response body

Response body layout example:

<audio>
   <uri>http://pabx.mycompany.com/calls/2012/05/17/971282.wav</uri>
</audio>

POST /audio - Associate audio track URI with metadata¶

Request body: XML detailing an audio URI and the metadata name/value pair it should be associated with.

Layout example:

<audio key=”UNIQUEID” value=”1334105250.768”>
    <uri>http://pabx.mycompany.com/calls/1334105250.768.wav</uri>
</audio>

Status codes:

400 Bad Request
500 Server Error
201 Created - Association was successfully stored in the database

GET /capture/id - Obtain capture information by id¶

Request body: None.

Query parameters: None

Status codes:

400 Bad Request
404 Not Found
500 Server Error
200 OK - XML information about capture in response body

Response body layout example:

<capture id="173">
    <videofile hasaudio="1">OK</videofile>
    <received>2012-06-05 15:42:57</received>
    <metadata>
        <var name="callid">1338998719.49834</var>
        <var name="operator">ahall</var>
        <var name="customerid">208548754</var>
        <var name="_h">864</var>
        <var name="_w">1152</var>
    </metadata>
</capture>

GET /capture/VarName/VarValue - Obtain capture information by metadata¶

Request body: None.

Query parameters: None

Status codes:

400 Bad Request
404 Not Found
500 Server Error
200 OK - XML description of matching audio track in response body

Response body: same as with GET /capture/id

Note

if there are multiple captures with the queried metadata variable having the same value, only the most recent one is returned.

POST /capture - Upload a capture generated by TotalRecorder Workstation¶

Request body: Raw content of a .ITR capture file

Status codes:

400 Bad Request
500 Server Error
201 Created - Success

Note

This call will not typically be issued by user code, but rather by the TotalRecorder Workstation Upload Agent.

GET /capturefile/id - Download capture file by id¶

Request body: None.

Query parameters: None

Status codes:

400 Bad Request
404 Not Found
500 Server Error
200 OK - Raw content of capture file in response body. This is the exact same binary that was uploaded with the POST /capture call.

GET /videofile/id - Download AVI encoded capture by id¶

Request body: Optional - an XML request body may be passed.

Query parameters: None

Status codes:

400 Bad Request
404 Not Found
500 Server Error
200 OK - Raw content of .AVI of encoded capture file in response body.
202 (Queued/Encoding) - This is a request for a valid video, but the encoding service hasn’t processed it yet. The X-ITR-EncodeStatus response header contains a description of the encoding status. This text is also in the status line comment; hence the server will return, for example, “202 Queued (3)” instead of the default “202 Accepted”.
- Queued (N) - There are N captures in front of the requested one waiting to be processed
- Queued - There are an unknown number of captures in front of the requested one waiting to be processed
- Encoding - The server is processing the video right now

TotalRecorder Workstation API¶

This portion of the document describes the API calls used to interface with TotalRecorder’s client portion known as ITRClient or ITR Workstation.

There are only two things you need to inform the client, when to start a capture and when to stop. Those are done by doing an HTTP POST to the following address <http://localhost:5800/capture> .

All information for those requests go as web form fields. Which means setting the mime-type for the request to “application/x-www-form-urlencoded” and that the message body consists of a correctly URL-enconded string of ‘varname=var’ pairs separated by ‘&’.

There are two predefined fields:

cmd - which defines the action to be taken by the client, START or STOP.
pw - This is the Client API Password defined in the TotalRecorder client configuration.

Additionally, in the START call you can add as many more fields as you wish prefixed with ‘m_’ which will be saved with this capture as metadata. There is also a special case, you can send the field ‘m_audiooffset’ ( in miliseconds ) and this is will cause TotalRecorder during the mixing of the capture and audio files to play this amount of time of the audio before starting to play the video. This is useful in cases your audio recording includes the receiver’s phone ringing before the call is picked up.

A very basic example of an HTML page which implements this form is:

<HTML>
    <HEAD><TITLE>TotalRecorder Workstation POST test</TITLE>
        <META HTTP-EQUIV="Pragma" CONTENT="no-cache" />
        <META HTTP-EQUIV="Expires" CONTENT="-1" />
        <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" />
    </HEAD>
    <BODY BGCOLOR="#FFFFC0">

        <H3>VNC Server POST test</H3>
        <FORM ACTION="http://localhost:5800/control" METHOD="POST">
            Command: <INPUT TYPE="TEXT" NAME="cmd"><br>
            Field 1: <INPUT TYPE="TEXT" NAME="m_field1"><br>
            Field 2: <INPUT TYPE="TEXT" NAME="m_field2"><br>
            Checkbox 1? <INPUT TYPE="CHECKBOX" NAME="m_cbox1"><br>
            Option 1:<SELECT NAME="m_order">
              <OPTION VALUE="_opt1" SELECTED>First</OPTION>
              <OPTION VALUE="_opt2">Second</OPTION>
              <OPTION VALUE="_opt3">Third</OPTION>
              <OPTION VALUE="_opt4">Fourth</OPTION>
            </SELECT><br>
            <br>
            Password: <INPUT TYPE="PASSWORD" NAME="pw"><br>
            <br>
            <INPUT TYPE="SUBMIT" NAME="submit" VALUE="Submit">
            <INPUT TYPE="RESET" NAME="clean" VALUE="Clean">
        </FORM>
    </BODY>
</HTML>

Documentation for release 4.6

InstantVoice

Navigation

Related Topics

Instant TotalRecorder¶

Installation¶

Server Installation¶

Setting up an IV box¶

Installling TotalRecorder¶

Client Installation¶

TotalRecorder Configuration¶

Server Configuration¶

API Parameters¶

Database Parameters¶

Video Parameters¶

Audio Parameters¶

Client Configuration¶

Uploads Tab¶

Captures Tab¶

Disclaimer Tab¶

InstantVoice Integration¶

Configuring InstantVoice¶

TotalRecoder¶

Audio Tracks¶

Configuring IVClient¶

Retrieving Capture Videos¶

Instant TotalRecorder SDK¶

TotalRecorder Server API¶

GET /captures - Obtain a list of video captures¶

GET /audio/VarName/VarValue - Obtain audio track URI by metadata¶

POST /audio - Associate audio track URI with metadata¶

GET /capture/id - Obtain capture information by id¶

GET /capture/VarName/VarValue - Obtain capture information by metadata¶

POST /capture - Upload a capture generated by TotalRecorder Workstation¶

GET /capturefile/id - Download capture file by id¶

GET /videofile/id - Download AVI encoded capture by id¶

TotalRecorder Workstation API¶