Quick Overview

This page aims to be a comprehensive guide to the AVChat platform. We’ll cover topics such as getting AVChat up and running on different media servers, configuring AVChat, customizing the way AVChat works and looks, security and troubleshooting.

All the AVChat documentation is on this page so if you’re looking for something specific just hit Ctrl+F on your browser.

If you cannot find the answer you’re looking for here, we encourage you to try the AVChat discussion forum.

How AVChat works

AVChat uses a media server to send audio, video and text chat between desktop users and text chat to and from mobile users.

alt text

If we were to break down the exact process here is every step:

  1. User goes to your web site and visits the page with the video chat on it.
  2. The chat client (Flash swf on desktop) is loaded by the users browser, it initializes and it loads avc_settings.php from your web server together with other config files: the language file, the emoticons files, etc..
  3. Once everything is loaded the user is asked for a user name and gender (if AVChat’s not integrated).
  4. Once the user provides that info the chat client attempts to connect to the media server using an rtmp connection over port 1935.
  5. Once connected to the media server the user can join rooms, send text messages, view other user’s streams and start publishing their own audio video stream.
  6. All data (audio, video, text) is sent from the user to the media server and from there it’s directed as needed to all other users.

Requirements

To run AVChat 3 on your website you will need:

  1. Web hosting for your chat/website
  2. A media server

Your chat users need a modern Internet browser with Flash Player 11.1 or above installed.

The need for Flash Player 11.1 starts with AVChat build 2330 of AVChat which adds H.264 encoding support.

Web hosting for your chat/website

A web hosting account with PHP or ASP.NET support is needed. This is where the chat files will be placed and most probably where your web site is already located.

A media server

AVChat (and all Flash based video chat apps including the peer to peer ones) needs a media server to transport data (audio, video and text chat) betweenusers.

AVChat supports the 3 major media servers:

AVChat (desktop) is compatible with:

  • Red5 1.0.5+
  • Wowza 1.7.x -> Wowza Streaming Engine 4
  • Adobe Media Server 5 Starter, Professional and Extended and Flash Media Server 2, 3, 3.5, 4 and 4.5

AVChat (mobile) is compatible with:

  • Red5 1.0.5+

Other compatibility notes:

  • AVChat versions up to and including 3.5.2 are compatible with Red5 0.8 and 1.0RC1.
  • Red5 1.0.5 needs at least Java JDK version 1.8
  • Adobe Media Server Standard and Flash Media Streaming Server are not supported

Setting up your own media server

You can can install the above media server software on any VPS or dedicated/cloud server.

Any VPS, dedicated server or cloud server will work. If you don’t have one yet we recommend getting one from these companies:

Each media server has it’s own installation instructions. We can also install a media server for you, on your server, through our Media Server Installation Service ($99).

Media server porvided by us

We’re also offering VPS servers with Red5 pre-installed and configured for AVChat starting with $14.99/month. We can use servers in Toronto, San Francisco, New York, London, Amsterdam, Frankfurt and Singapore.

Configuration files

On the web server

Main config file

avc_settings.xml is the main configuration file for AVChat. You will find it in your AVChat installation folder on your web server.

avc_settings.xml has been introduced in build 2060 when all the settings from avc_settings.php and avc_settings.aspx.cs were removed from those 2 files and grouped into one single file: avc_settings.xml.

For simple ASP avc_setting.asp is still used before and after build 2060.

Audio video quality

The audio video quality files are located in the audio_video_quality_profiles folder.

Here you will find the following default profiles with which AVChat ships:

  • 96k_high_quality_sound.xml
  • 128k_high_motion_low_picture_quality.xml
  • 256k_high_motion_low_picture_quality.xml
  • 512k_high_motion_medium_picture_quality_high_sound_quality.xml
  • 768k.xml

For more details about using and configuring the profiles see chapter Audio Video Quality

Themes

The themes are located in the themes folder.

AVChat ships with 2 default themes: dark and light each with its own style.xml configuration file.

For more details about configuring and customizing your own theme see chapter Themes

Translations

Language files are located in the translations folder.

Here you will find the default language XML with which AVChat ships, en.xml.

For more details one how to edit or add your own translations to AVChat see chapter Translating AVChat

On the media server

Red5

avchat3.properties, you will find it in Red5/webapps/avchat30

Wowza

avchat3.properties , you will find it in Wowza/conf/avchat30

Adobe Media Server

settings.asc , you will find it in AMS/applications/avchat30

AVChat File Structure

AVChat ships as a zip archive that contains the following file/folder structure:

  • folder icon Files to upload to your website
    • folder icon audio_video_quality_profiles (folder containing audio video quality files in .xml format)
    • folder icon codebird-js
    • folder icon emoticons (folder containing sets of emote icons)
    • folder icon gender_icons
    • folder icon report_snaps
    • folder icon sounds (folder containing sounds used in the video chat in mp3 format)
    • folder icon themes (subfolders dark and light each with a style.xml)
    • folder icon tokens
    • folder icon translations (folder containing UI translations in .xml)
    • folder icon uploadedFiles (folder where files uploaded by users will go)
    • admin.html (html file that embeds admin.swf)
    • admin.swf (admin interface)
    • ajax-loading.gif
    • avc_settings.asp
    • avc_settings.aspx
    • avc_settings.aspx.cs
    • avc_settings.php
    • avc_settings.xml has been added started with build 2060
    • badnicks.xml (xml file containing the bad usernames that are now allowed in the chat)
    • badwords.xml (xml file containing the bad words that are banned in the chat)
    • bg.png
    • channel.html
    • dataEncryption.php
    • favicon.ico
    • file_types.xml has been added starting with build 2060
    • fonts.xml (list of fonts that can be used in the chat)
    • fullStar.png (default logo image that is shown over all video stream to prevent them from being rebroadcasted)
    • genders.xml
    • getRecordedVideosInfo.aspx
    • getRecordedVideosInfo.aspx.cs
    • getRecordedVideosInfo.php
    • gift.png
    • index.html (html file that embeds index.swf)
    • index.swf (user interface)
    • Mobile_Detect.php
    • mobile-icon.png
    • mod_icon.png
    • nowebcam.png
    • ppvIcon.png
    • ppvUpdate.aspx
    • ppvUpdate.aspx.cs
    • ppvUpdate.php
    • Preview.swf (old background)
    • report_snapshot_upload.aspx
    • report_snapshot_upload.aspx.cs
    • report_snapshot_upload.php
    • rotate_messages.aspx
    • rotate_messages.aspx.cs
    • rotate_messages.php
    • search-14px.png
    • search-icon.png
    • sendgift.aspx
    • sendgift.aspx.cs
    • sendgift.php
    • sendReport.aspx
    • sendReport.aspx.cs
    • sendReport.php
    • style.aspx
    • style.aspx.cs
    • style.php
    • style.css (old css file that controls the colors and fonts used throughout the video chat). Starting with build 2060 style.css has been replaced with style.xml for users with PHP, style css is still used for users with ASP.NET and ASP
    • swfobject.js
    • tinycon.min.js
    • token_request.aspx
    • token_request.aspx.cs
    • token_request.php
    • token_verify.aspx
    • token_verify.aspx.cs
    • token_verify.php
    • upload.asp
    • upload.aspx
    • upload.aspx.cs
    • upload.php
    • uploadclass.asp
    • warning.png
    • wget.aspx
    • wget.aspx.cs
    • wget.php
    • writeuserslist.aspx
    • writeuserslist.aspx.cs
    • writeuserslist.php
  • folder icon Files to upload to your media server (FMS/AMS)
  • folder icon Files to upload to your media server (Red5 0.8)
  • folder icon Files to upload to your media server (Wowza)

Installation Instructions

AVChat 3 standalone installation instructions

First you need to download the AVChat archive from the client/trial area on nusofthq.com to your computer and extract it’s contents.

There are 2 sets of files in the AVChat archive:

  • the chat client files which go on your web server
  • the server side avchat30 app for each media server (Red5/AMS/Wowza)

Setting up the avchat30 application on the media server

Upload the avchat30 folder from the Files to upload to your media server (Red5) folder to your Red5's webapps folder (C:\Program Files\Red5\webapps on Win, /opt/red5/webapps/ on Linux).

On Linux, chmod the new avchat30 folder to 666.

For versions of Red5 1.0.7 or higher one additional change needs to be made:

  1. Go to /Your_Red5_Install_Directory/webapps/avchat30/WEB-INF
  2. Open red5-web.xml with any text editor
  3. Uncomment line 37

Restart the Red5 server.

Upload the avchat30 folder (you will find it in your AVChat archive in the Files to upload to your media server (FMS) folder) to the applications folder of your AMS installation.

On Linux, chmod the new avchat30 folder to 666.

Upload the applications, lib and conf folders from the Files to upload to your media server (Wowza) folder to the root folder of your Wowza Media Server installation.

Restart the Wowza server.

Installing AVChat standalone in a folder on your web site

  1. Create a new chat folder in your web site and upload the contents of Files to upload to your web site from the AVChat archive to it.
  2. Edit avc_settings.xml with a text editor, and set the <value> of the first XML tag - <connectionstring> to: <value>rtmp://my-media-server.com/avchat30/_definst_</value> where my-media-server.com is the domain name or ip of the server where your media server is installed.
  3. CHMOD the uploadedFiles and tokens folder to 777 (otherwise the upload adn token authentication functions might not work).
  4. Go to http://yoursite.com/chat/, enter the chat and, when prompted, enter the license key.
  5. To access the admin interface go to http://yoursite.com/chat/admin.html.

If you’re using ASP.NET on the web server, and it doesn’t run PHP, you need to configure AVChat to use the .aspx server side files.

Switching between the PHP and ASPX configuration files in AVChat

AVChat ships with 2 sets of server side files, once for PHP (the default) and one for ASP.NET .

You have the possibility to switch the type of the configuration files used by AVChat to communicate with the web server (load the settings, request tokens, etc…).

Switching to other types of config files (like the .aspx ones also provided with AVChat) can be done via the sscode flash var explained below.

By default AVChat uses the PHP set of files (avc_settings.php, token_request.php, etc.) so we need to tell it to use the .aspx set of files. To do that we will use the sscode flash var.

  1. Open up index.html and admin.html in a text editor and find the following variable: sscode :"php", and replace with: sscode :"aspx", like this:
  2. Edit avc_settings.xml and set the and set the <value> of the <stylecssurl> tag to style.aspx like this <value>style.aspx</value>:

The sscode flash var, if not specified, defaults to php.

Instead of aspx you can use any other extension (.rb, .asp, etc) as long as the corresponding files exist in the video chat folder.

Connecting different AVChat installations to the same media server.

When you have AVChat installed in 2 different locations (different folders or different websites) there are 3 ways to connect them to the same media server:

  1. Connect them to the same app and app instance (users from one location will interact with users from a different location)
  2. Connect them to the same app but different instance (separate rooms and users but same sahred application level config file)
  3. Connect them to a different avchat30 app (totally independent)

Solution 1: Using the same app instance for 2 or more AVChat 3 installations

As long as you use the same connection string, users from different installations of AVChat can interact with each other in the same rooms.

Solution 2: Using different app instances for 2 or more AVChat 3 installations

There is a quick way of setting up multiple separate installations of AVChat to work with the same media server app. It involves using application instances and can be used the same way with all 3 media-servers (AMS, Wowza and Red5).

The default application instance for all media servers is _definst_ . To force AVChat to connect to a new instance simply edit the connection string and change _definst_ to any other instance name like siteB or userK, the new connection string should look like rtmp://my-media-server.com/avchat30/siteB.

Solution 3: Using different apps for 2 or more AVChat 3 installations (totally independent)

Adobe Media Server

On AMS the process is pretty straight forward. All the app files are placed inside the AMS/applications/avchat30 folder. To create a new avchat30 app:

  1. duplicate the avchat30 folder
  2. rename the new one to avchat30_siteX (or to any other name that fits you).

You should now have 2 folders application folders:

  • avchat30
  • avchat30_siteX

To connect the second installation of AVChat to the new Red5 webapp use this connection string in avc_settings.xml: rtmp://my-media-server.com/avchat30_siteX/_definst_.

Red5

All the app files for AVChat are placed inside the Red5/webapps/avchat30 folder. To create a new avchat30 app:

  1. duplicate the avchat30 folder and
  2. rename the new one to avchat30_siteX (or to any other name that fits you).

Now in the avchat30_siteX/WEB_INF/ folder:

  1. edit red5-web.properties and change: webapp.contextPath=/avchat30 to webapp.contextPath=/avchat30_siteX
  2. edit web.xml and change

     <context-param>
     <param-name>webAppRootKey</param-name>
     <param-value>/avchat30</param-value>
     </context-param> to
     <context-param>
     <param-name>webAppRootKey</param-name>
     <param-value>/avchat30_siteX</param-value>
     </context-param>
    
  3. rename logback_avchat30.xml located in Red5/webapps/avchat30_siteX/WEB-INF/classes/ to logback_avchat30_siteX.xml
  4. now edit it and change:

     <jmxConfigurator contextName="avchat30" /> to
    
     <jmxConfigurator contextName="avchat30_siteX" /> and
    
     <fileNamePattern>log/avchat30.%d{yyyy-MM-dd}.log</fileNamePattern> to
    
     <fileNamePattern>log/avchat30_siteX.%d{yyyy-MM-dd}.log</fileNamePattern>
    

Steps 3 and 4 will ensure we will get separate logs for each app.

To connect AVChat to the new Red5 app use the following connection string in avc_settings.xml : rtmp://my-media-server.com/avchat30_siteX/_definst_ .

Wowza

This one is very simple:

  1. duplicate the Wowza/applications/avchat30 folder and rename it to avchat30_siteX.
  2. duplicate the Wowza/conf/avchat30 folder and rename it to avchat30_siteX.

To connect AVChat to the new Wowza app use the following connection string in avc_settings.xml : rtmp://my-media-server.com/avchat30_siteX/_definst_ .

How to change the license key

Here are 3 setiations where you will have to change the AVChat license key:

  • Switch from trial to non-trial key or to a new trial key.
  • Switch the domain on which the software will be used.
  • Upgrade from Lite (20 users) to Basic (40 users).

What do I have to do?

  1. Log in the video chat using the admin interface (admin.html or admin.swf)
  2. Click the Settings button at the top
  3. In the window that shows up, delete the old key from the text field and insert the new key
  4. Press the Change Key button
  5. If successful, you should now see the new limits/expiration date/domain above the license key text field

How to reset the license key

If something goes awfully wrong and you find yourself locked out of the video chat (you’ve inserted a key for a domain to which you do not have yet access or has not yet been registered ) you can reset the license key by following these simple steps:

  1. Delete this file
    • on Red5: red5/webapps/avchat30/persistence/SharedObject/_definst_/licensekey.red5
    • on AMS: fms/applications/avchat30/sharedobjects/_definst_/licensekey.fso
    • on Wowza: wowza/applications/avchat30/sharedobjects/_definst_/licensekey.rso
  2. Restart Red5, AMS or Wowza
  3. Enter the video chat and you will be asked for the key again.

What AVChat version and build do I have installed?

To see what AVChat version and build you have installed you need to right click any element in the video chat. The first item in the menu that shows up conatins the version number (3.6 in this case) and the build number (3648):

alt text

Why is the build number important?

The build number allows you to check if you have the latest version of our software. If your build number is 3078 and on the blog we announce a new release with the build number 3097, then it means you should consider upgrading your installation.

Each increment in the build number might represent any of the following things:

  • bug fix
  • new feature
  • new file
  • new entry in the translation file
  • new setting in the config files

You should check the release notes for the exact new features and bug fixes in each build.

Build numbers on our live AVChat demo

Our online AVChat demo is frequently updated, so even tough the latest build available for download might be 3097, the demo might have a higher build number. We update the demo more frequently to test new features and UI changes before we release these changes to customers.

What we need to install AVChat 3

Here’s what we need to install AVChat:

  1. FTP access to the web site (or folder) where AVChat will be installed
  2. If you’ve purchased an integration kit we will need admin acess to the admin area of your CMS (Joomla!, Drupal, etc.).
  3. root ssh access to the vps/dedicated server where the media server (Red5/AMS/Wowza) is installed (on Windows servers Remote Desktop access will do)

If you don’t have a media server we offer VPS media server hosting services starting from $14.99/month. More info here.

Please open a support ticket from your client area and send us the data. Our team will handle the installation.

AVChat installations are generally made in the same day if all the data above is correct and complete.

What we need to install a media server

We offer Media Sever Installation Service for a $99 one time fee.

Here’s what we need to install a media server:

  1. root ssh access to the vps/cloud server where you want the media server (Red5/AMS/Wowza) to be installed if have a Linux Server, or Remote Desktop if you have a Windows server.
  2. AMS or Wowza license key if any.

Please send the data to support after purchase.

Media server installations are generally made in the same day if all the data provided is correct and complete. Our tech support hours are 8am to 6:3pm GMT.

Switching from a trial version of AVChat 3 to a purchased version

If you have a trial version of AVChat installed and have purchased a license, switching to production is very easy:

  1. Download the purchased version of AVChat and unzip it
  2. Copy and replace index.swf and admin.swf from the extracted archive to your trial AVChat installation folder.

Also don’t forget to replace the trial license key, with the purchased one.

That’s it! You are now running the licensed version of AVChat.

Installing the mobile version of AVChat 3

AVChat 3.6 and newer

Starting with AVChat 3.6 the mobile version of AVChat only works on Red5 1.0.5 and up. The new mobile HTML 5 client introduced in AVChat 3.6 uses WebSockets to communicate and Red5 is the only media server supporting this technology.

Here’s how to set it up:

On the media server/Red5:

  1. Download json-smart-2.0-RC3.jar library from here and put in the Red5/plugins folder (applies to both Red5 1.0.5 and 1.0.6)
  2. Open Red5/conf/red5.properties and scroll dow to the #WebSocket section
  3. Change the ws.host default value (0.0.0.0) with your media server IP address
  4. Save the file and restart Red5

On the webserver:

  1. Download the mobile archive from your private client area at https://nusofthq.com and unzip
  2. Copy the ws folder to your AVChat installation directory.

AVChat 3.5 and older

On the media server side, inside the settings file, the web server IP needs to be defined.

Here’s how to set it:

On Adobe Media Server:

  • open settings.asc file (you will find it in AMS/applications/avchat30)
  • search for webServerIP
  • replace the existing IP (127.0.0.1) with your website’s IP (use this tool to find out the ip)

On Red5:

  • open avchat3.properties file (you will find it in /Red5/webapps/avchat30)
  • search for webServerIP
  • replace the existing IP (127.0.0.1) with your website’s IP (use this tool to find out the ip)

Design

Themes

Starting with version 3.5 AVChat ships with 2 themes: light and dark. Both themes are located in the new themes folder. The light theme is the default one.

You can make your own theme by simply creating a new folder inside the themes folder and putting a customized style.xml inside it.

Switching between the default light and dark themes

To switch between themes, either the default ones or to your custom created theme, you need to take the following steps:

Change theme

  1. Open style.php or style.aspx.cs depending on wether you run AVChat using PHP or ASPX
  2. Edit the $pathToTheme var and change the theme folder in the path. By default it will look like this: themes/light/style.xml. If you want to switch to the dark theme it should look like this themes/dark/style.xml.
  3. Save and exit.

Change background color

  1. Next we need to change the background color and it can only be changed from the index.html and admin.html files.
  2. Edit index.html and search for bgcolor JS parameter which by default will be bgcolor : "#F1F1F1", and change the hex value to #101622 which is the correct dark theme bacground color.
  3. Save and exit. Do the same for admin.html.

See below for details.

Background color of AVChat

The background color of AVChat is defined in the HMTL web page that embeds the AVChat swf file. In case of the sandalone version of AVChat, it ships with 2 HTML pages:

  • index.html for the user interface, embeds index.swf
  • admin.html for the admin/moderator interface, embeds admin.swf

In order to change the color of the user interface you will need to open index.html in a text editor and find the following lines:

var params = {
  quality : "high",
  bgcolor : "#272727",
  play : "true",
  loop : "false",
  allowFullScreen : "true"
};

Replace the default bgcolor value (#272727) with your desired color.

Hint: Use a color picker to find the perfect color.

Save and upload the modified index.html to your web site. Do the same with admin.html.

Background image

AVChat can display a .jpg/.png image or .swf animation as it's background.

To add a background image open the style.xml file with a text editor (found inside your themes folder for AVChat 3.5 and up) and at the beginning, you’ll see this xml code:

<backgroundArea>
  <backgroundImageUrl></backgroundImageUrl>
  <backgroundImageScale>stretch</backgroundImageScale>
  <backgroundImageAlpha>100</backgroundImageAlpha>
</backgroundArea>

Rename the bg.jpg with the name of your image uploaded on your AVChat installation folder.

Transparency

You can also change the transparency of this background image by changing the value of the backgroundImageAlpha xml tag in the theme’s style.xml. By default it’s set to 100 (no transparency). If set to a lower value the background color will be visible through the transparent background image. 0 means fully transparent.

The image will automatically tile to fit the size of the video chat software.

Sounds used in AVChat

You can change the sounds used throughout AVChat with your own sounds. AVChat currently uses 6 .mp3 sounds which you can find in the sounds folder:

  • alert.mp3 (used when a text chat message kicks in)
  • private.mp3 (used when receiving private messages)
  • videorequest.mp3 (used whena request to view your private stream comes in)
  • buzz.mp3 (used when someone gives you a buzz)
  • online.mp3 (used when someone joins a room)
  • offline.mp3 (used when someone leaves a room)

How to change them: Just replace the existing mp3’s with your own mp3’s. Try to keep their size as small as possible because these sounds are loaded at runtime.

To disable the sounds just delete the mp3’s.

Changing the size of AVChat

You can change the size of the AVChat user and admin interfaces to better fit within your website pages.

The size of the AVChat user and admin interfaces is defined in the HMTL pages that embed these index.swf and admin.swf files. By default AVChat ships with 2 HTML pages: index.html (that embeds the user interface index.swf) and admin.html ( that embeds the admin interface admin.swf).

In order to change the size of the AVChat user interface you will need to edit index.html with a text editor and and find the following line:

swfobject.embedSWF("index.swf", "myContent", "100%", "100%", "10.3.0", "", flashvars, params, attributes);

and replace "100%", "100%" with your desired dimensions (first width, second height). Save and upload the modified index.html to your web site, and refresh. Do the same to admin.html.

Customizing AVChat windows

The theme’s style.xml file controls (among other things) the looks of the windows inside AVChat. By editing style.xml you can change the following:

  • the color of the windows
  • if the windows have rounded corners or not (set to 0 for straight corners)
  • the space between the windows
  • the space between the margin of the windows and its content
  • if the windows cast shadows
  • the border color

Here is the actual windows tag from style.xml:

<windows>
	<margin>4</margin>
	<padding>6</padding>
	<backgroundcolor>#FFFFFF</backgroundcolor>
	<cornerradius>4</cornerradius>
	<windowsCastShadows>false</windowsCastShadows>
	<borderColor>#E9E9E9</borderColor>
</windows>

Fonts

The theme’s style.xml file also controls the fonts used throughout the video chat. By editing the style.xml file you can change for every group of fonts (like titles, side menu links, etc…):

  • the font face (fontfamily:_sans)
  • the size of the font (fontsize:16)
  • the font weight (fontweight:bold)
  • the color of the text (color:#ffffff)

Gender icons

Starting with build 1880 AVChat supports any number of genders through the use of the new genders.xml.

Customizing genders:

  1. Upload your new gender icons to the gender_icons folder located in your AVChat installation.
  2. Open the genders.xml file and edit the lines, for example:
<gender id="cat" label="Cheshire Cat" iconUrl="gender_icons/cheshire_cat_32.png" adminOnly="false" sortPriority="b" outlineColor ="0x577ce5" />
  1. Rename the id, label and iconUrl corresponding to your new gender and it will become:
<gender id="polar_bear" label="Polar Bear" iconUrl="gender_icons/polar_bear.png" adminOnly="false" sortPriority="b" outlineColor ="0x577ce5" />

Starting with AVChat 3.5 you can also specify the color (through the new outlineColor parameter) to be used for the left line element that is drawn in the users list on mouse over the user item.

Audio Video Quality

AVChat (through Flash Player) captures raw audio and video data from your web cam and microphone, encodes it, and sends it to the media server from where it is sent to the other users. AVChat puts no limits on the audio video quality experienced by your users and in that spirit it opens up all the available audio and video settings for you to play with. You can change the video resolution, picture quality, frame rate, sound rate and a lot more.

For encoding video AVChat can use the Sorenson Spark and H.264 codecs. For encoding audio AVChat can use the Speex and Nellymoser ASAO audio codecs.

Audio/video quality profile files explained

In the installation folder of AVChat you will find a folder named audio_video_quality_profiles. It contains several XML files. We call these XML files audio video quality profiles because they define a certain set of audio and video quality settings.

Each XML file contains the parameters (resolution, frames per second, picture and sound quality, etc.) used to encode the video/audio data that’s coming from your computer’s webcam and microphone. AVChat ships with several such profile files that you can use out of the box each configured to give you the best possible audio and video quality at several data rates from 96kbits/s to 768kbits/s.

The default audio/video profile used by AVChat is 512k_high_motion_medium_picture_quality_high_sound_quality.xml. This profile will consume (for one stream) maximum 469kbits/s for video and 42 Kbits/s for audio, total: 511kbits/s.

To make AVChat standalone use another audio/video quality profile file you need to change the value of the miccamsettingsurl variable inside avc_settings.xml to point to the XML file of your choice. You can also make your own quality profiles or edit the existing ones.

Editing existing quality profile files

Each of the quality profile files has the exact same XML structure:

<item>
   <nm>128 ISDN</nm>
   <df>0</df>
   <bytes>16000</bytes>
   <q>0</q>
   <fps>7</fps>
   <kfps>28</kfps>
   <w>200</w>
   <h>150</h>
   <displayWidth>256</displayWidth>
   <displayHeight>192</displayHeight>
   <snd>speex6</snd>
   <sndSilencelevel>0</sndSilencelevel>
   <vcodec>sorenson</vcodec>
</item>

Each node/value pair explained:

Video settings

bytes
The maximum amount of bytes that the video (excluding audio) can use per second. If set to 0, the video encoder will allocate as much data/s as possible to maintain the picture quality. Multiply by 8 to get the value in bits.
q
The picture quality. If set to 0 the encoder will use as much quality as possible, without exceeding the **bytes** value. Maximum is 100 but that will consume excessive bandwidth. A value between 85-95 will result in great picture quality without the high bandwidth usage.
fps
The video frame rate. 10, 15, 30 fps, etc... . Some old web cams can only capture up to 15fps.
kfps
Key frames. This tells AVChat that every **kfps** frames a full frame will be encoded in the video stream. The rest of the frames contain just the changes from the previous frame.
w
The desired width of the captured video in pixels
h
The desired height of the captured video in pixels
displayWidth
The desired width of the video display
displayHeight
The desired height of the video display
othersDisplayScale
controls the scale of the video that is represented by an incoming stream ( the stream you are watching). By default it size of the video window will be that of the native resolution the broadcaster is transmiting in. If that size creates a window too large for example ( 1280 x 720 ), this can be scaled down by using a lower value for othersDisplayScale i.e. 0.25
vcodec

The video codec used to encode the live stream, with possible values being sorenson or h264. Use the h264 value to encode video with H.264 video codec (Main Profile with Level 3_1 are used

Audio settings

snd

The snd tag controls the audio codec and sample rate/bandwidth of audio. Flash Player supports encoding sound in 2 codecs:

  • Nellymoser ASAO
  • Speex

When using the Nellymoser ASAO codec you can choose between five different microphone sample rate values: 5, 8, 11, 22 and 44.

Speex on the other hand has a fixed sampling rate of 16kHz. Speex allows control of the quality by offering us 11 different encoding quality options, from 0 to 10. Each setting translates to a different bitrate.

Possible values for snd:

  • 44 : Nellymoser, 44kHz sample rate (highest quality for Nellymoser)
  • 22 : Nellymoser, 22kHz sample rate
  • 11 : Nellymoser, 11kHz sample rate
  • 8 : Nellymoser, 8kHz sample rate (low quality)
  • 5 : Nellymoser, 5kHz sample rate (lowest quality)
  • speex10 : Speex, default value for this profile, highest quality, uses 42.2kbits/s of bandwidth
  • speex9 : 34.2kbits/s
  • speex8 : 27.8kbits/s
  • speex7 : 23.8kbits/s
  • speex6 : Speex, uses 20.6kbits/s of bandwidth
  • speex5 : 16.8kbits/s
  • speex4 : 12.8kbits/s
  • speex3 : Speex, low quality, lowest usable quality, uses 9.80kbits/s
  • speex2 : 7.75kbits/s
  • speex1 : 5.75kbits/s
  • speex0 : Speex, lowest quality, not really usable, uses 3.95kbits/s
sndSilencelevel
Takes values from 0 to 100. Flash Player will consider any sound that is lower than the value of this tag as "silence" and thus will not send any data to the media server. Use 100 if you want to never send audio to the media server. Use 0 if you always want to send to the media server whatever the mic captures (even noise). We recommend using 0 since if you use the default (10) Flash Player will stop broadcasting sound when you stop speaking. Even though this seems like a cool feature that cuts bandwidth in reality the listeners will frequently get the feeling that you've been cut off.

To edit a quality profile file open it in Notepad or any other text editor, change the value that you want to change, save it back to the web server. Now reload AVChat in the browser and start your webcam, you should now see the changes.

Making your own quality profile file

To make your own audio video quality profile, duplicate one of the existing XML quality files, give it a unique name and edit it with a text editor. To use it, upload it to your web server and set the value of the miccamsettingsurl variable in avc_settings.xml configuration file to it.

Security

How to turn on token based authentication in AVChat

Starting with build 900, AVChat 3 introduces a new security feature called token based authentication.

When enabled this feature prevents 3’rd party swf files (hosted on other web sites than your own or by malicious users) to connect to your media server. There are other security measures in place to prevent this, however, token based authentication is the most secure.

This feature is turned off by default because with it enabled:

  • we can’t make it work out of the box, it needs to be configured manually
  • it takes slightly more time for users to connect to the media server
<watermarkForOtherPeoplesStreams>
  <title>watermarkForOtherPeoplesStreams</title>
  <name>Watermark for other people streams</name>
  <type>string</type>
  <desc>path to a png, gif or jpeg file to show over other peoples cameras, this feature has been introduced for blocking users from rebroadcasting other peoples stream using screen sharing software. Use this to put your logo over the video streams.</desc>
  <default>fullStar.png</default>
  <value>fullStar.png</value>
</watermarkForOtherPeoplesStreams>

How to enable it

Once you have AVChat installed, enabling this feature is simple:

  1. Edit the settings file on the media server:
    • on Red5 its Red5/webapps/avchat30/avchat3.properties
    • on Wowza its Wowza/conf/avchat30/avchat3.properties
    • on AMS its AMS/applications/avchat30/settings.asc
  2. Set the value of the tokenUrlLocation variable to the absolute url/path to token_verify.php (token_verify.php is located in the AVChat installation folder on your webserver). Good example: http://avchat.net/demos/av30/token_verify.php . If your AVChat installation uses ASPX instead of PHP put the path to token_verify.aspx instead.
  3. Restart the media server.

Protection against video streams being rebroadcasted (watermarking)

Some of our clients had issues with users joining their video chat rooms and re-broadcasting streams to other sites using screen sharing software.

To protect against that we ended up putting the logo of our client (a watermark) over all the video streams.

By default AVChat uses a little star (fullStar.png). You can view it in our AVChat demo and on your (default) installation. To change the star with your own logo edit avc_settings.xml and change the value of the watermarkForOtherPeoplesStreams xml tag.

The watermark will be added to the top left of all the video streams.

RTMPS and RTMPE for encrypted communications

AVChat supports both RTMPS and RTMPE for encrypted data transfer between the users and the media server but depending on your media server you can use one or both:

  • Red5 supports only RTMPS
  • AMS and Wowza support both RTMPS and RTMPE

To enable RTMPS or RTMPE check with your media server documentation. We can also enable it for you through the AVChat Securitization service.

Enabling SWF Verification on AMS

Adobe Media Server, starting with Flash Media Server 3, has this very cool security feature called SWF Verification where you can tell it to only accept connections from known swf files. How does he know the swf files? Well… you upload them to the AMS server. Simple and brilliant!

This feature can protect you from custom made swf files attempting to connect to your media server. Together with token based authentication it would make the most secure setup someone can wish for.

To to turn it on you need to do two things:

  • First, change the <SWFVerification enabled="false"> to "true" in your applications/avchat30/Application.xml file to turn on the feature.
  • Create a new folder: applications/avchat30/SWFs and put the index.swf and admin.swf with which AVChat ships.
  • Having changed the server configuration, you are going to need to restart your media server.

If you’re passionate about this stuff there’s a more detailed article explaining SWF Verification in more depth on the adobe.com web site: adobe.com/devnet/flashmediaserver/articles/

Unfortunately SWF Verification is only available with FMS3 or later. Red5 and Wowza do not have this feature.

Limiting IPs from which admins can connect and execute admin functions

Because we give free trials to just about anyone, our script gets into a lot of hands, some of them are not well intended.

One of the easiest ways to protect your AVChat from malicious users is to limit the ip’s from which admins can connect through the admin interface (admin.swf) and execute admin functions.

You just have to edit the settings file on the media server:

  • on Red5 its Red5/webapps/avchat30/avchat3.properties
  • on Wowza its Wowza/conf/avchat30/avchat3.properties
  • on AMS its AMS/applications/avchat30/settings.asc

And search for the adminsAllowedFromTheseIps variable. Set its value to your IP or to the range of IPs from which admins will be allowed to connect.

Starting with build 1144 the verification is done every time an admin executes an admin function (kick, ban, change license key, etc.) not just on connection.

Allowing connections from AVChat files installed on localhost

Because of security reasons you can not connect to the avchat30 application on the media server with AVChat client side files (html/swf) hosted on localhost. When you try to do that you will get a connection error.

To allow connections from AVChat installed on localhost you need to edit the settings file on the media server:

  • on Red5 its Red5/webapps/avchat30/avchat3.properties
  • on Wowza its Wowza/conf/avchat30/avchat3.properties
  • on AMS its AMS/applications/avchat30/settings.asc

And search for the allowLocalhostConnections variable. Set it to true and restart the media server.

Manually removing the banned IPs file

If you’ve banned yourself (by ip or username) out of the video chat you will need to manually delete the banned IPs and usernames file and restart the media server.

Red5

Delete the bannedips.red5 and bannedusernames.red5 files from the following folder:

  • Red5 0.8: Red5/webapps/avchat30/persistence/SharedObject/_definst_
  • Red 1.0.5: Red5/webapps/avchat30/persistence/persistence/SHARED_OBJECT/avchat30/_definst_

Adobe Media Server

Delete the bannedips.fso and bannedusernames.fso files from AMS/applications/avchat30/sharedobjects/_definst_.

Wowza

Delete the bannedips.rso and bannedusernames.rso files from Wowza/applications/avchat30/sharedobjects/_definst_.

Features

Bandwidth usage explained

The bandwidth usage/month depends on many factors and can never be guessed without several days of actual running the video chat software on your website:

  • number of people online watching cams and how much time they spend watching
  • number of people online broadcasting cams and how much time they spend broadcasting
  • how many cams a user can see at once
  • audio/video quality (128,256,512kbits/s etc…)

For example a user broadcasting its webcam for 30 minutes at 256kbits/s will use 57Mbytes of bandwdith (256kbits/s * 60 seconds * 30 minutes=57Mbytes).

Another user viewing the first one for 30 minutes will use the same amount: 57Mbytes. Total: 114Mbytes for a 30 minute 1 to 1 video chat session.

Reducing bandwidth usage

AVChat 3 offers several ways to reduce the monthly bandwidth used on the media server:

Delay/Latency display for live video streams

In the side menu for other people’s web cams, AVChat 3 now shows an estimation of how much it takes for the video and audio data to travel from the broadcaster to the viewer (through the media server) . We call this value round-trip time but its also known as latency.

The value is not always 100% exact but it is a really good estimation!

For one to many broadcasts the trip time value is not important, live TV broadcasts generally have a 5-15 seconds delay to give broadcasters time to censor any audio needing censorship

A low trip time is really important when the audio/video communication goes both ways, for example when 2 people are in a video conference. Imagine what would happen if when talking with someone over the phone it would take 5 seconds for your voice to travel from you to the other person.

The trip time in AVChat 3 is influenced by:

  • How close the broadcaster and the viewer are to the media server
  • Sound quality (paradoxically the higher the better)
  • The Internet connection of the broadcaster and the viewer

Round-trip time values you are likely to get when your video chat users are close to the media server and have good, low latency, Internet connections:

  • 200 ms on audio+video streams
  • 50ms on video only streams

This showing of the round-trip time is controlled by showVideoFpsInfo from avc_settings.xml. By default it is disabled.

How to hide the who-is-typing box

In avc_settings.xml you will find the following setting:

<showWhoIsTyping>
	<title>showWhoIsTyping</title>
	<name>Show who is typing</name>
	<type>boolean</type>
	<desc>if set to 0, the who is typing bar in the text chat area will not be shown anymore</desc>
	<examples>0 for hidden , 1 for visible</examples>
	<default>1</default>
	<value>1</value>
</showWhoIsTyping>

Set it to 0 and the who-is-typing box will not be shown anymore in the chat.

How to close the pop up containing AVChat when clicking the Leave button

When AVChat 3 is opened in a pop up window you can use the Leave button to close the pop up window:

  1. Edit avc_settings.xml
  2. Set disconnectButtonEnabled <value> to 1;
  3. Set disconnectButtonLink <value> to javascript:window.close();

By default clicking Leave takes you to a new web page instead of closing the window.

Recording the video streams

AVChat 3 uses a media server (like Red5, AMS/FMS and Wowza) to stream audio and video between users. The audio and video data travels from the broadcaster user to the media server and from there to the receiver/viewer. While it passes through the media server the audio and video data can be captured and stored in .flv file, or, starting with build 2330, in .mp4 files. The file type that will be created depends on the video codec being used (Sorenson Spark or H.264).

Codecs being used

The audio data will be encoded with the NellyMoser or Speex codec (depending on your audio settings) and the video data will be encoded with the Sorenson Spark video codec. Starting with build 2330 the H.264 codec has also been added for video encoding.

The audio and video encoding is done by Flash Player (before it sends the data to the media server) and Flash Player can only encode with those codecs. Flash Player 11.1 or above is required for H.264 support.

So when the audio and video data hits the media server it is already encoded, the media server just saves the data into .flv or .mp4 files depending on the video codec.

Enabling audio/video streams recording

The feature is disabled by default because it tends to use large amounts of space over the time.

On Red5:

  1. Edit avchat30/avchat3.properties
  2. Set recordAudioVideoStreams=true
  3. Restart Red5

You will find the new .flv files in Red5/webapps/avchat30/streams/_definst_

The .flv files are named like this: username+ “_”+ unique user id assigned by Red5 + “_”+ timestamp (from when the user started publishing ).

On AMS/FMS

  1. Edit avchat30/settings.asc
  2. Set recordAudioVideoStreams=true
  3. Reload the avchat30 AMS/FMS application using the AMS/FMS Management Console (or restart AMS/FMS)

FMS 3.5 or higher is required for recording in .mp4 format and streaming with H.264 encoding.

You will find the new .flv/.mp4 files in FMS/applications/avchat30/streams/_definst_.

The flv/mp4 files are named like this: username+ “_”+ unique user id assigned by AMS/FMS + “_”+ timestamp (from when the user connected to AMS/FMS).

On Wowza

  1. Edit Wowza/conf/avchat30/Application.xml
  2. On line 25 change live-lowlatency with live-record and save
  3. Restart Wowza

Wowza will by default record in .mp4 format. But in order for the recording to work properly you have to encode the video with H.264. See Editing existing quality profile files.

If you wish to have your recordings in .flv format you will need to take the following steps:

  1. Go to http://WOWZA_SERVER_ADDRESS:8088/enginemanager/</li>
  2. From the top menu click the Server page
  3. In Server Setup click Edit
  4. Change Default Stream Prefix from mp4 to flv
  5. Save

Doing this will no longer require to encode the stream with H.264 and you can leave the audio quality profile unchanged.

You will find the new .flv/.mp4 files in this folder: Wowza/content/.

As oppsed to AMS/FMS and Red5, by default, the flv/mp4 files are not grouped in folders by application and application-instance like this:

  • Wowza/content/avchat30/_definst_
  • Wowza/content/avchat30/_siteB

To group them like that you need to:

  1. Edit Wowza/conf/avchat30/Application.xml
  2. On line 26 change the default folder path ${com.wowza.wms.AppHome}/content with ${com.wowza.wms.AppHome}/content/${com.wowza.wms.context.Application}/${com.wowza.wms.context.ApplicationInstance}
  3. Save and restart Wowza.

The .flv/.mp4 files are named like this: username+ “_”+ unique user id assigned by Wowza.

Audio video quality

The media server records whatever gets sent from the client .swf file, so to increase the audio/video quality of the recordings you need to increase the audio/video quality used inside the video chat software.

Because you are recording audio/video streams that are destined for live viewing, the quality of the recordings is not as high as the quality that you get with a dedicated Flash video recording software like our Flash Video Recorder. Live streams are maintained as “live” as possible by Flash Player and the media server by dropping video frames and even stopping the video data from being sent to the media server because audio data has higher priority than video data (this will only happen over slow connections tough where audio+video data just doesn’t fit through in a “live” way).

When you have auto bandwidth reduction turned on (it’s on by default) streams are passed through the media server only when there is someone watching the respective stream. So even tough user X is broadcasting, his stream will only be recorded if he has one or more viewers. The stream recording process will also stop when user X has no more viewers. You can turn off auto bandwidth reduction.

H.264 vs Sorenson Spark

Advantages:

  1. H.264 requires less bandwidth than Sorenson Spark
  2. H.264 causes less delay when streaming between the broadcaster and the receiver
  3. H.264 provides better image quality, smoother framerates and sharper edges and details.

Disadvantages:

H.264 is more CPU intensive than Sorenson Spark. Having a lot of streams running at once may cause the AVChat client to have performance drawbacks for users with slower hardware.

Playing back the recorded files

FLV

To play back the .flv or .mp4 files on your desktop you can use VLC.

To play back the .flv or .mp4 files on your website directly from the media server you can use any flash video player for websites that supports streaming. We recommend JW Player or Flow Player. You can also move the video files from your media server to your web server and deliver them to your users via progressive download.

MP4 files recorded with Adobe Media Server

Flash Media Server version 3.5 and later and Adobe Flash Media Live Encoder 3 and later can record content in MPEG-4 (F4V) format using an industry-standard recording technology known as “fragments” or “moof atoms.” Some MPEG-4 compatible tools and players do not support moof atoms and therefore cannot recognize files recorded by Adobe Media Server (previously known as Flash Media Server). The F4V Post Processor tool aggregates the information from all the moof atoms into a single moov atom and outputs a new file. Use the F4V Post Processor tool to prepare F4V files for editing in Adobe Premiere® Pro software, delivery over HTTP, or in video players that support H.264 and AAC formats. This tool can be used in Windows or Linux.

Playing back the files locally before passing them through the F4V Post Processor tool might not work.

FLV files with no meta data

Because of the way they are recorded, some .flv files will end up having no duration metadata, thus resulting in funny playback. To fix this run those flv files through flvmdi or flvtool2.

You can also use FFmpeg which provides a lot of functionality and it’s quickly becoming the go to tool for video processing.

Dynamic bandwidth usage reduction explained

AVChat 3 , as all the other flash video chats out there, uses a media server (like Red5 and AMS) to stream audio and video between users. The audio and video data travels from the broadcaster user to the media server and from there to the receiver user.

Even tough there is no receiver (if there is no one watching) the stream still travels from the broadcaster to the media server, thus consuming bandwidth on the media server and on the broadcaster’s Internet connection.

This is where AVChat 3’s dynamic bandwidth usage reduction kicks in. When this feature is activated (it is on by default) the broadcaster streams audio and video to the media server ONLY WHEN IT HAS VIEWERS.

Here is bandwidth usage graph explaining how this feature works:

  1. Users enters chats.
  2. User starts the webcam and microphone but no audio and video data is sent yet to the media server.
  3. Someone starts watching the broadcast and audio and video data starts being sent to the media server to be routed to the viewer.
  4. The viewer stops watching the broadcast and the streaming of audio and video ends as well.

This feature will save a lot of bandwidth over time both on your media server (or media server hosting account) and on your users Internet connections.

To disable it (now why would you want to do that? :) ) edit avc_setting.xml and search for the automaticallyReduceBandwidthUsage variable. Set it to 0 to disable it.

Ghost users and detection mechanism explained

Ghost users are a known issue with all media servers.

What is a ghost user?

A ghost user is a user who’s disconnection from the media server has not been detected by the media server, thus the media server thinks he is still connected.

In a chat you will know there are ghost users when you see 2-3 persons in the users list having the same user name or persons staying for unusual lenghts of time in the chat without activity.

What causes ghost users?

They happen when a user suddenly disconnects from the Internet while connected to a media server (for example by suddenly disconnecting your Ethernet cable or loosing WiFi signal) but in other occasions too like when the user is over a slow connection (mobile connections) or behind some weird combination of network hardware + server software. IE and the way it handles Flash content might also produce ghost users.

How is AVChat 3 dealing with ghost users?

  1. Every 3 seconds the client (swf file) sends a ping to the media server (this value can not be changed)
  2. Every 10 seconds the media server (Red5/Wowza/AMS/FMS) check if all clients have sent a ping within the last 10 seconds (already 3 pings should have been sent by every client) and disconnects everyone who has not.

This means that no ghost user will ever stay in the chat for more than 20 seconds.

Starting with build 741 (April) you can control the above mechanism by changing the value of the checkForGhostConnectionsEveryXSeconds and ghostUsersAreIdleForYSeconds variables in settings.asc (AMS/FMS) or avchat3.properties (Red5 and Wowza). If your users seem to get disconnected for no apparent reason increase the value of ghostUsersAreIdleForYSeconds to 20 seconds for example. Both variables are set by default to 10 seconds.

External users list

Overview

In order to show on your website who is logged in the video chat, AVChat 3 generates 2 external files in the folder where it is installed:

  • users__definst_.txt -> a text file containing the number of unique users connected to the video chat
  • users__definst_.xml -> an XML file containing the list of rooms and users in each room

You will see these files ONLY AFTER THE FIRST USER (NOT ADMIN) LOGS IN THE VIDEO CHAT!

Starting with build 2768 the external users list is generated even if someone joins the chat through the admin interface.

You can use these 2 files to show on your website how many clients are logged in, the room structure or which clients are logged in.

How to actually code/do that is outside the scope of this documentation but anyone with minimum PHP or .NET experience should be able to parse the XML/text file and post the contents on the website.

How it works

In detail:

  1. User joins the video chat via index.swf, the path to the writeuserslist.php is automatically detected.
  2. User joins a room, the media server sends the new rooms/users structure to writeuserslist.php via POST (using the path detected at step 1).
  3. writeuserslist.php receives the new info via POST and creates the 2 files on the web server.

One some of our integration kits admin.swf and writeuserslist.php are placed in separate folders, that’s why admins logging in do not trigger an attempt to detect the path to writeuserslist.php.

Admins and users are properly listed in the external .xml file as long as at least a user has logged in in the past so that the media server knows where writeuserslist.php is located.

You can also set the path manually (via the settings.asc/avchat3.properties files on the media server) and you should when:

  • You’re using writeuserslist.asp (or any other scripting language) instead of writeuserslist.php.
  • You’ve moved writeuserslist.php to a separate folder.
  • You have troubles with the external users list not being generated.

Troubleshooting

If the 2 files refuse to appear do these tasks in this order:

  1. Log in the video chat through the user interface (not the admin interface/area)
  2. Make sure the folder containing writeuserslist.php is chmoded to 755 so that writeuserslist.php can write/crate new files
  3. Make sure calls to the new info is POST-ed from the media server to the web server (check Apache logs)
  4. Make sure the folder where writeuserslist.php is located is not password protected!
  5. Hard code the path to writeuserslist.php in settings.asc (on AMS/FMS ) or in avchat3.properties (on Wowza/Red5) and restart the media server
  6. Contact support: support@nusofthq.com

Turning the feature off

On AMS/FMS edit applications/avchat30/settings.asc, set application.writeUsersLists=false and restart AMS/FMS.

On Red5 edit webapps/avchat30/avchat3.properties, set writeUsersLists=false and restart Red5.

On Wowza edit conf/avchat30/avchat3.properties, set writeUsersLists=false and restart Wowza.

This will turn off the feature and stop the media server from making POST calls to the web server.

Where are the text chat transcripts

AVChat saves a history of all the text chat in all the rooms including private chats on the media server!

On AMS/FMS

They will be saved in the FMS/applications/avchat30/logs/ folder and the files have such names: _definst__r0_2010_12_20.txt, where _definst_ is the application instance name, r0 is the room id, and 2010_12_20 is the date.

To disable it edit applications/avchat30/settings.asc, set application.loggingEnabled=false and restart AMS or reload the app.

On Red5

They will be saved in Red5/webapps/avchat30/avchat3_transcripts/ folder and the files have such names: _definst__r0_2010_12_19_log.txt.

To disable it edit webapps/avchat30/avchat3.properties, set loggingEnabled=false and restart Red5.

On Wowza

They will be saved in Wowza\applications\avchat30\avchat3_transcripts folder and the files have such names: _definst__r0_2010_12_19_log.txt.

To disable it edit conf/avchat30/avchat3.properties, set loggingEnabled=false and restart Wowza.

How to delete the text chat logs

You have 2 options here.

First of them and the most easier is to access the AVChat admin interface and click the little broom button in the down-right corner.

This action will delete all the exisiting messages from all rooms instantly.

The second option is to connect to your server by SSH, access the text chat transcripts folder, delete the files manually and restart the media server.

You will find the text chat transcripts by the filename which is in the format r0textchat. The path to these files is:

  • avchat30/SharedObjects/_definst_ on Red5 0.8
  • avchat30/persistence/persistence/SHARED_OBJECT/avchat30/_definst_ on Red5 1.0.5 and up
  • avchat30/sharedobjects/_definst_ on FMS/AMS
  • applications/avchat30/sharedobjects/_definst_ on Wowza

The files extensions are:

  • .red5 on Red5
  • .fso on FMS/AMS
  • .rso on Wowza

How to delete empty rooms automatically

Starting with build 2160 the delete empty rooms mechanism has been redone:

The media server now constantly checks for empty rooms and if:

  • deleteRoomsWhenTheyBecomeEmpty = true
  • the room is not protected (not included in the doNotDeleteTheseRoomsWhenTheyBecomeEmptyarray) and
  • is inactive for more than the number of hours set in the option deleteEmptyInactiveRoomsOlderThan then the room is deleted.
AVChat can be set up to remove empty rooms automatically as soon as the last person leaves the room.

By default this feature is turned off. To turn it on you need to edit the config file on the media server (avchat3.properties on Red5/Wowza and settings.asc on AMS/FMS) and set

deleteRoomsWhenTheyBecomeEmpty=true

You can also use the doNotDeleteTheseRoomsWhenTheyBecomeEmpty option to protect some rooms (like the main Lobby) from being removed like this:

Red5 & Wowza

doNotDeleteTheseRoomsWhenTheyBecomeEmpty=r1,r2

FMS

application.doNotDeleteTheseRoomsWhenTheyBecomeEmpty=["r1","r2"]

More details about each of the above config options and the exact syntax are in the config files. The location of the config files is detailed here.

How to edit/add genders

Starting with build 1880 AVChat loads the genders from a genders.xml file. AVChat comes with a couple of predefined genders, but these can be edited or removed, and others can be added. As explained in the XML file, the only thing that should not be changed are the IDs of the male, admin, unknown and hidden genders, but other attributes of these genders can be changed such as the iconUrl or the sortPriority.

To add a new gender, simply add a new line in the XML file specifying all the attributes like so:

<gender id="female" label="Girl" iconUrl="gender_icons/girl.png" adminOnly="false" sortPriority="c" outlineColor ="0x577ce5" />

Login area

Starting with build 1880 AVChat 3 has a new and more customizable login area, with 2 main screens, which can be activated using the tab at the top : Enter as guest and Sign in & Register.

The default selected tab can be set using the setting in avc_settings.xml selectedTabInLoginScreen.

Also if the setting showLoginError is enabled the Enter as guest screen and corresponding tab disappear altogether.

The Enter as guest tab contains the textfield for the username, the gender selection that is customizable (see 6.12 for more details), the connect button and a new zone that allows the use of other existing accounts such as Facebook, for the authentication of users. This zone can also be enabled/disabled with enableOtherAccountOptions from avc_settings.xml.

The Sign in & Register tab contains the register and sign in buttons that redirect the users to the respective areas of the site.

To add the sign URL set loginPageURL in avc_settings.xml

To add the register URL set registerPageURL in avc_settings.xml.

Joining the chat using Facebook user profiles

Starting with build 1880 users can enter AVChat using their Facebook profiles.

Clicking the Facebook button in the login screen will open a popup asking for user’s Facebook email and password. If the user is already logged in in Facebook, AVChat will connect as soon as you press the Facebook button.

AVChat 3 will use the name, gender, profile picture and profile link from Facebook.

This feature is controlled by the enableOtherAccountOptions setting located in the avc_settings.xml file. If set to 0, the feature will be disabled.

Steps you need to take to allow users to enter using their Facebook profile:

  1. Go to: https://developers.facebook.com and sign in
  2. Create a new Facebook App (choose any Display Name and Category)
  3. Go to the app’s Settings > Basic
  4. Click on + Add Platform and select Website
  5. In the Site URL field type your website URL (make sure it’s correct) and click Save Changes
  6. Open up the index.html from the folder where you have AVChat installed
  7. Find the line where the appId is specified and replace the existing App ID with your App’s ID (it’s in Settings > Basic)
  8. Save the file.

The above setup is also needed for enabling the Share on Facebbook & Invite Facebook friends features from AVChat’s Share window.

Badnicks & Badwords

AVChat 3 has 2 configuration files containing usernames and words which are not allowed to be used as nicknames or in the text chat.

We’re talking about 2 separate files: badnicks.xml and badwords.xml. Both files can be found in the main AVChat 3 installation folder.

Bad nicks

badnicks.xml - contains 2 groups of XML elements:

  • <nicks> - the exact usernames defined there will not be allowed in chat
  • <widcards> - usernames containing that wildcard string will not be allowed in chat.

Any username found either in the <nicks> or in the <widcards> tags will not be allowed in chat.

Bad nick example: <bad>john</bad> - meaning that any user trying to connect with username “john” will not be allowed.

Wildcard example: <bad>adr</bad> - meaning any user trying to connect with an username containing “adr” (adrian, adrienne) will not be allowed.

Only the user interface (index.swf) will check the member’s username against the usernames in badnicks.xml. The admin interface (admin.swf) does not apply the check, so if the “admin” or “administrator” usernames are present in badnicks.xml they can be used in admin.swf but index.swf will not let users with these usernames go past the login screen.

Bad words

badwords.xml - contains 2 groups of XML elements as well:

  • <words> - words defined there will not be allowed in chat
  • <widcards> - words containing the wildcard will not be allowed.

If some user uses in chat a word from that list you have created, it will be replaced with asterisks (***).

Rotating messages feature

AVChat 3 has a feature which gives the possibility for the owner to add info messages, text ads with links or any announcements.

This feature was added in Build 1505 of AVChat 3 to give the website owner the ability to add info messages, text ads with links or any other announcements in the text chat.

In detail

The file which stores the messages is rotate_messages.php located in the AVChat 3 installation folder. It is called by AVChat 3 every rotatingMessageTime seconds (option in avc_settings.xml) and it sends to it a GET variable named count which stores the number of times it was called by that user.

The file comes by default with several messages. These can all be replaced and more can be added.

To replace the messages, open rotate_messages.php with a text editor and replace the text between the quotes, without affecting the PHP code.

Here’s the default file with the text that you should edit highlighted:

If you’ve edited the 6 default messages and you want to add more here’s what you need to do:

  • Duplicate the last case (case 0, lines 29-31 above) and replace 0 with 6 like this:
case 6:
echo "<font color='#999999' face='Tahoma' size='11' ><b>A new message.</b></font>";
break;
  • On line 13 change the number 6 with 7 like this: switch ($count%7)

As you can see, you can customize these messages using some HTML tags for color, font, size, etc. The supported list of HTML tags that can be used can be found here.

If you are an experienced web developer you can create your own rotate_messages.php file with messages being pulled out of a database, more complex logic, ads, etc. and point AVChat 3 to use it through the rotatingMessageUrl option located in avc_settings.xml.

Other notes

  • rotatingMessageUrl in avc_settings.xml contains the path to rotating_messages.php
  • To disable the feature open avc_settings.xml file with a text editor and set rotatingMessageTime to 0 (<value>0</value>)
  • To increase the time between calls to rotate_messages.php open avc_settings.xml file with a text editor and set rotatingMessageTime to 120 (<value>120</value>) which means 2 minutes between calls or any other value in seconds.

Register & Sign in tab disable/enable

You can disable the register tab using the setting enableRegisterTab and found in the avc_settings.xml file.

To disable the tab:

  1. Open the file with a text editor.
  2. Search for enableRegisterTab.
  3. Set it’s <value> tag to 0.
  4. Save the file and upload it back to the server.

Example:

<enableRegisterTab>
	<title>enableRegisterTab</title>
	<name>Enable register tab</name>
	<type>boolean</type>
	<desc>controls the status (enabled, disabled) of the Register and Sign-in tab (the second tab)</desc>
	<values>0 for disabled, 1 for enabled</values>
	<default>1</default>
	<value>0</value>
</enableRegisterTab>

You can also translate the tab’s label and it’s content to use it in some other purpose. The text used in this tab can be found in translations/en.xml file located in the AVChat installation folder.

Report user feature

Sending a report

Starting with build 2760 a user can be reported by any other user if necessary. This option is easily accessed by pressing the Report this user button located in a user’s side menu.

The same button can also be accessed directly from the user’s web-cam window.

Once pressed a window opens that allows the following:

  • Selecting a report reason
  • Adding more information of why the user is reported in the limit of 200 characters

Pressing Report will send the report, Cancel will cancel the sending.

Upon sending the report, automatically, two screenshots are taken:

  • A screenshot of the text-chat area
  • A screenshot of the reported user’s web-cam

These screenshots are sent to the web-server and can be found in the AVChat installation directory in the folder named report_snaps. The filename is composed of the user’s siteId and the screenshot type (CAM or TEXT), so a screenshot will be named like so: userSitedId_CAM.jpg and userSitedId_TEXT.jpg

All of the information of the report is also available through a PHP API, the file sendReport.php. This file can be configured to send an automatic email with the data of the reported user along with links to the two above mentioned screenshots. By default the code for the email sending is commented. It can also be customized to be used in any other way it is seen fit.

The email address will have to be set manually, by opening the file with any text editor and editing the following line of code: $to = "webmaster@example.com";

The default mail that it is sent will look similar to this:

Viewing a report

All of the reports can be seen using the AVChat administrator area -> Reports panel. The number between the parentheses is a notification for the total number of reports.

The notifications work in the following way: Upon entering the chat as admin, the Reports button will show the total number of reports like so: Reports (10). When a new reports is received and the reported users window is not opened, the total number of NEW reports will be displayed in the top right corner of the Reports button like so:

Pressing the Report button will open a new window and the notifications for the total number of NEW reports disappears. The new window displays all of the reports sent. Here you have the following options:

  • View the camera snapshot for a particular report (this is only active if a screenshot of the reported user’s webcam was taken).
  • View the text-chat snapshot for a particular report
  • Copy username (copy the username of the reported user)
  • Copy user IP (copy the IP of the reported user)
  • Remove a report
  • Close (closes the window)

Removing a report will permenantly delete it.

Additionally the report feature can be disabled by setting enableReportSending to 0. Also an admin can be blocked to see the reports by setting adminCanSeeReports to 0. By default they are both enabled (set to 1).

Pay Per View API

A new Pay Per View API has been introduced in build 3078. This API replaces the old freeVideoTime setting and functionality.

The API offers new functionalities that enable you to create and integrate a costum built payment pay per view solution based on several criteria like:

  • how much does a user stay in chat
  • how many minutes can he watch other streams
  • etc.

The API has 2 parts:

  • settings that can be controlled from the avc_settings.xml file
  • the actual JavaScript client side API and PHP + .NET server side API.

The avc_settings.xml settings

The API is intended to be used with an integrated version of AVChat and makes use of the following settings in avc_settings.xml:

  1. PPVEnabled - This setting controls whether or not the PPV feature is enabled. When disabled the PPV button is not shown in the status bar.
  2. PPVAmount - This setting holds the amount of time or credits. The PPVAmount starts to decrease as soon as the user enters the chat or as soon as he starts viewing a webcam (depending on PPVTrigger) with a ratio equal to PPVRatio/second. The remaining PPVAmount is then sent (every second) to the JS function onPPVUpdate - which can be found in index.html and admin.html - and to ppvUpdate.php ( or ppvUpdate.aspx if you’re one a ASP.NET server).
  3. PPVType - This setting controls what PPVAmount represents (time, money, credits). When set to time, the PPVAmount number will be shown in the chat formatted as time (i.e. 15:32).
  4. PPVTrigger - This setting indicates what triggers the PPVAmount to decrease. When set to viewing_webcams the PPVAmount starts to decrease as soon as you start viewing someone ( viewing 2 or more cams will NOT decrease the timer faster). When set to connected the PPVAmount starts to decrease as soon as you enter the chat.
  5. PPVRatio - This setting controls the ratio at which the PPVAmount is decreased every second. When set to 0.5 for example there will be a 0.5 credits or seconds decreased every second.
  6. PPVLink - This setting holds the URL for the page from which more time/credits may be purchased for more video stream access. Pressing the PPV button will open the PPV Link.
  7. PPVIcon - This setting provides the URL to the icon loaded in the PPV button located in AVChat’s top status bar. The icon size should be 16x16.

The PPV Button mentioned above is a new button added in the status bar that displays dynamically the amount of time/credits left when PPV is enabled. Here’s how it looks:

The API

The API itself covers both client side and server side:

  • a client side Javascript API, represented by the function onPPVUpdate (found in index.html and admin.html).
  • a PHP file ppvUpdate.php and a .NET file ppvUpdate.aspx

The JS function mentioned above and the 2 server side files, are called every second, by the AVChat client, while viewing a stream or being in chat (depending on the trigger set), with the following parameters/querystring variables:

  • ppvAmountLeft: the amount of time/money/credits left for a particular user after deducting PPVRatio.
  • ppvInitialAmount: the initial amount of time/money/credits that a user had.
  • ppvRatio: the rate at which the ppvAmountLeft is decreased.
  • userSiteId: the siteId value as sent by avc_settings.xxx
  • sessionTimeStamp: the timestamp from the last login.

Working with the API

All of this information needs to be sued to update the credits/time/money database of the site with which AVChat is integrated in a pay per view manner.

This is how a PPV operation would look like:

  1. Registered site user enters AVChat, the integration makes sure the user sees his correct credits/time/money in the AVChat top status bar.
  2. User enters a room and stars viewing a cam.
  3. AVChat starts sending PPV data to both the JS and server side API every second
  4. Parameters passed to the API will have to used to decrease the ammount of credits/time or money the user has.

Controlling the API

The API can be controlled by the setting PPVEnabled. Depending on the value set here just parts of the API can be enabled.

To only enable the JavaScript API set PPVEnabled to 1.

To only enable the PHP/.NET API set PPVEnabled to 2.

To enable both JavaScript and PHP/.NET API set PPVEnabled to 3.

How to setup AVChat for Twitter authentication

The Twitter authentication explained

Starting with build 2915 AVChat supports Twitter authentication.

This feature allows your users to connect to AVChat using their Twitter account.

Clicking the Twitter logo in the login screen will open up a popup asking for the user’s Twitter credentials in order the authorize the app for that particular account.

Upon given permission AVChat will automatically login using the user’s Twitter profile name and profile picture. Opening the user’s profile from the user side menu will lead you to the user’s Twitter profile.

This feature is controlled by the setting enableOtherAccountOptions located in the avc_settings.xml file. If set to 0, the feature will be disabled.

Setting it up

Here are the steps that will guide you on how to set this up:

  1. Go to https://dev.twitter.com/apps
  2. Create a Twitter application by clicking “Create a new application” (you must have a Twitter account, if not create one prior to this).
  3. Enter the Name, Description, Website URL (your website) and the Callback URL (this will be a placeholder for the actual callback URL but it is needed. You can enter the same website URL completed earlier).
  4. Agree with the terms, enter the CAPTCHA and click “Create your Twitter application”.
  5. You will receive a message at the top of the page that the application was succesfully created and be redirected to a new page that lists all the details for the created application.
  6. Open up index.html(that can be found in your AVChat installation folder) with any text editor.
  7. Find the lines similar to this: var consumerKey = "U3yvRmc...."; and var consumerSecret = "YtlvlqRTXjdjmK....."; and replace those values with the ones generated by Twitter for your own application (marked in the image above by the green rectangle).
  8. Find the line similar to this var pathToAVChat = "http://avchat.net/demos/avchat30"; and replace the value with the link to your AVChat installation.
  9. Save and close the file.

How to edit columns in the rooms panel

This feature allows you to edit the info displayed regarding a room in the rooms panel. The values represent the table heads for each column:

In the above image, you can see that small arrow icon. Users are able to sort the rooms in the rooms list by that option.

For example, clicking the name once (as in the example), will sort the rooms alphabetically, by name (from A to Z). Clicking it once again will reverse the sort (from Z to A).

Same procedure for the rest of the colums.

Also, you can remove some of the columns so that you will only display the name of the room, having only the “name” label in the <value> node, like: <value>name</value>

How to do it:

  • Open avc_settings.xml - you can find it in your AVChat installation folder.
  • Search for columnsInRoomsPanel (line 1116).
  • Based on the values in the <default> node (name, users, private, owner, created), set the <value> node to what you need.
  • Save the file and upload it back to the server.
<columnsInRoomsPanel>
   <title>columnsInRoomsPanel</title>
   <name>Columns in rooms panel</name>
   <type>string</type>
   <desc>a string that allows you to configure and edit the columns shown by the rooms list inside the rooms panel.</desc>
   <default>name users private owner created</default>
   <examples></examples>
   <value>name users private owner created</value>
</sortRoomListOn>

How to make the webcams auto start

Perhaps you’re using AVChat for live conferences where people will use audio/video by default and you want to eliminate some steps, to make AVChat more user friendly.

In this matter, you can set the webcams to open automatically for each user, after connecting.

There are 2 possibilities here:

After connecting, each user will start seeing all other public streams automatically.

How to set this:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • search for autoStartCameras (line 426)
  • set it’s <value> node to 1 which enables it
  • save the file and upload it back to the server
<autoStartCameras>
   <title>autoStartCameras</title>
   <name>Autostart cameras</name>
   <type>boolean</type>
   <desc>if set to 1 the user will start to view PUBLIC cams automatically as soon as they are started, admins with the permission to view private streams will also view private streams automatically</desc>
   <examples>0 for disabled, 1 for enabled</examples>
   <default>0</default>
   <value>1</value>
</autoStartCameras>

After connecting, each user will start streaming, with or without microphone.

How to set this:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • Search for autoStartMyCamera (line 435)
  • Set it’s <value> node to 1 which enables it
  • Save the file and upload it back to the server
<autoStartMyCamera>
   <title>autoStartMyCamera</title>
   <name>Autostart my camera</name>
   <type>eboolean</type>
   <desc>if set to 2, when a user has a webcam, immediatley after joining the first room, his camera will start broadcasting (the mic will start muted if the user has one).if set to 1, when a user has a webcam/microphone, immediatley after joining the first room, his camera/mic will start broadcasting. If set to 0, the user will have to press the 'Start my camera/mic' buttons to start it . This setting also takes into consideration the allowAudioStreaming and allowVideoStreaming variables</desc>
   <examples>0, 1, 2</examples>
   <default>0</default>
   <value>1</value>
</autoStartCameras>

Allowing/blocking audio and video streaming

AVChat acts like a group chat with audio and video, but you can disable one of these 2 functionalities anytime, for any of your purposes.

By default, both features are enabled. Here’s how to control both of them:

Disabling video streaming:

  1. Open avc_settings.xml with a text editor
  2. Search for allowVideoStreaming (line 110)
  3. Set it’s <value> node to 0
  4. Save the file and upload it back to the server

This way, users will be able to use only the microphone.

Disabling audio streaming:

  1. Open avc_settings.xml with a text editor
  2. Search for allowAudioStreaming (line 119)
  3. Set it’s <value> node to 0
  4. Save the file and upload it back to the server

This way, users will be able to use only the webcam, if allowVideoStreaming is enabled.

Having both disabled will make AVChat work as text chat only.

Restricting access from a desktop PC to the mobile version

The mobile version is HTML5 and Javascript based, so it can be easily be accessed from any browser including desktop browsers.

If you purchased the mobile version of AVChat and installed it and you want the users to be able to access the mobile version only from a mobile device, here are the steps needed to do so:

  • Open avc_settings.xml with a text editor
  • Search for enableHtmlClientForDesktopBrowser (line 1458)
  • Set it’s <value> node to 0
  • Save the file and upload it back to the server

How to disable the mobile version only

If you purchased the mobile version of AVChat and installed it, but you need to disable it for some reason, just remove or rename the ws folder from your AVChat installation folder.

Configure AVChat to function with audio and video only (AVChat 3.5.1 and older)

For more details on what has been changed you can read the blogpost.

AVChat can be set to function in video-only mode (just audio/video streams with no text-chat).

This feature is intended for users that want to utilize AVChat for specific seminars and presentations. When this is activated only the users-list will be available, and the user’s camera will automatically start.

Also user-side menu specific text-chat options will be no longer available.

This feature is controlled by the setting enableAudioVideoOnlyMode also present avc_settings.xml.

How to set it:

  • Open avc_settings.xml with a text editor
  • Search for enableAudioVideoOnlyMode (line 1548)
  • Set it’s <value> node to 1
  • Save the file and upload it back to the server

Configure AVChat to function with audio and video only (AVChat 3.5.2 and newer)

In AVChat 3.5.2 we’ve introduced a new setting hideTextChat which controls whether or not the text chat area is shown. The older setting enableAudioVideoOnlyMode has been removed completely, but it’s functionality can still be obtained combining some settings together including the newly added hideTextChat.

How to set it:

  • Open avc_settings.xml with a text editor
  • Search for hideTextChat
  • Set it’s <value> node to 1
  • Save the file and upload it back to the server

The idea behind this change was to eliminate any kind of possible conflicts that would’ve occurred if enableAudioVideoOnlyMode was activated and other settings like allowVideoStreaming was also set separately. To give you an idea on how AVChat can be setup to obtain the same or similar effects you can view the Live stream setup documentation.

How to hide/show some of the existing rooms

There might be a situation when you don’t want to show all the rooms to your users, but also not delete them, to prevent others joining some of your rooms.

This is easy, there are 2 possibilities here: hiding rooms or showing only some of them.

Also user-side menu specific text-chat options will be no longer available.

How to show only some of the existing rooms:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • Search for showOnlyRooms (line 1702)
  • Insert the room ID or rooms IDs you want to be shown in the <value> node (r0 for a single room and [r1,r2,r3] for multiple rooms)
  • Save the file and upload it back to the server

How to hide some of the existing rooms:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • Search for hideTheseRooms (line 1766)
  • insert the room ID or rooms IDs you want to be shown in the <value> node (r0 for a single room and [r1,r2,r3] for multiple rooms)
  • Save the file and upload it back to the server

Rooms music player

Every room can have it’s own music playlist with music tracks from Youtube.

Upon entering the respective room the music player will automatically start to play the songs.

This feature is controlled by the new setting enableMusicForRooms found in avc_settings.xml.

It comes enabled by default, here’s how to disable it:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • Search for enableMusicForRooms (line 1755)
  • Set it’s <value> node to 0
  • Save the file and upload it back to the server

How to enable webcam docking

Webcams can be aligned automatically above the text chat area when other streams are opened, like in the picture below:

This feature comes disabled by default, here’s how to enable it:

  • Open avc_settings.xml - you can find it in your AVChat installation folder
  • Search for enableWebcamDocking (line 1784)
  • Set it’s <value> node to 1
  • Save the file and upload it back to the server

How to setup Real-Time Translation with Google's Translate API

Starting with AVChat build 3396 we have implemented a mechanism that permits AVChat to detect the language the browser is setup for. Based on this and using Google’s Translate API you can now translate on the fly messages from another language, from a user that has the browser setup in french for example, to your preferred language, assuming as well that your browser is setup in your particular language.

A small translate link will appear on the side of the text message, pressing it will show the translation for that particular message in a smaller grey font beneath the original text, as shown in the images below:

French user’s message

English user’s message

But in order to achieve this you must first have a Google API Key. Here are the steps needed to obtain one:

  1. Go to https://console.developers.google.com and create a Google account if you don’t have one.
  2. After creating you account go to the Projects page by clicking on the Projects link in the left-side menu.
  3. Create a new project by clicking on the Create Project button and name it however you wish.
  4. Wait for a couple of seconds while the project is created.

Now that you’ve setup your project it’s time to enable the Translate API for it:

  1. With your project selected in the menu on the left, select API Manager.
  2. In the list of APIs, select Translate API from the Other popular APIs catergory, and make sure it is enabled.
  3. In the sidebar on the left, select Credentials.
  4. In this page click on the Create credentials button and select API Key.
  5. In the dialog box that opens up select Browser key.
  6. Http referers can also be setup like mentioned in the next window:
  7. Give it a name and specify the referers from which to accept request and then click Create
  8. An API Key will be generated. Copy it and set it in the avc_settings.xml setting googleAPIkey.
  9. Save and close avc_settings.xml.

There is one more thing that needs to be done before the setup is ready. Google Translate API v2 requires billing information for your account before you can start using the service. To enable billing for your project, do the following:

  1. With the project selected, in the sidebar on the left, select Billing.
  2. Select Enable billing
  3. Select your location and then fill in the form.

That’s it, now AVChat will translate text messages on the fly, provided the user’s browsers are setup for different languages.

How to setup AVChat for Live streaming

AVChat can be setup for live streaming of events or interactive courses for example. This is easily done when you have AVChat integrated with a CMS like Wordpress or Joomla, where you can setup a particular user group to be able to broadcast, and another “viewers” user group to only be able to view other streams. The particular settings you would need to setup will be detailed later.

In case you have a standalone installation of AVChat, the same effect can be achieved by having two different installation folders (two instances of AVChat installed on the webserver, connected to the same instance on the media server. One installation will fill the role of the broadcaster and the other of the viewer.

The following settings apply in both of the cases (integrated AVChat and standalone)

The broadcaster role will have the following setup:

  1. allowVideoStreaming set to 1
  2. allowAudioStreaming set to 1
  3. autoStartMyCamera set to 1
  4. autoStartCameras set to 0
  5. allowPrivateStreaming set to 0

The viewer role will have the following setup:

  1. allowVideoStreaming set to 0
  2. allowAudioStreaming set to 0
  3. autoStartMyCamera set to 0
  4. autoStartCameras set to 1

It is recommended that the cameras are set to be docked: enableWebcamDocking set to 1

Additional changes can be made. You can hide the users list for both broadcaster and viewer role by setting hideUsersList to 1.

Starting with AVChat 3.5.2 The entire text chat area can be hidden as well separately using the setting hideTextChat set to 1.

Accessing the videos via http from the avchat30/streams/_definst_ folder (Red5 only)

When recording using the Red5 media server the video files are created in Red5/webapps/avchat30/streams/_definst_. Starting with AVChat 3.6 the streams folder can be exposed - via Red5’s Tomcat web server - to be accessible via http (from the browser) at http://RED5_SERVER_ADDRESS:5080/avchat30/streams/

This will help you greatly if you want to:

  • Play the files through HTML5 or progressive download
  • Download the files locally
  • Move the files to a different server

You will need to do the following steps:

  1. Go to Red5/webapps/avchat30/WEB-INF/ on your media server.
  2. Open web.xml with a text editor.
  3. Delete the tag <security-constraint> along with it’s contents.
  4. Uncomment the other <security-constraint> tag, where it reads.
  5. Save and exit.
  6. Restart Red5.

If you now go to http://RED5_SERVER_ADDRESS:5080/avchat30/streams/ in your web browser you will see a list of all the video files. Clicking them will download them or play them in the browser.

This open directory listing can be a security issue (you don’t want to expose all the recorded videos to anyone snooping around). To turn off the directory listing do the following:

  1. Go to Red5/conf/ on your media server.
  2. Open web.xml with a text editor.
  3. Search for this code:

     <init-param>
        <param-name>listings</param-name>
        <param-value>true</param-value>
     </init-param>
    
  4. Set the listings value to false like this:

     <init-param>
        <param-name>listings</param-name>
        <param-value>false</param-value>
     </init-param>
    
  5. Save and exit.
  6. Restart Red5.

Directory listing will now be turned off.

You will still be able to access the file and download it or play it if you know it’s name (absolute http path).

How to setup AVChat's Stream Recording API (Red5 only)

Starting with AVChat 3.6 a new stream recording API is available. The API is represented by the getRecordedVideosInfo file (PHP or .NET variant) located on the webserver side in the AVChat installation folder.

The way this works is if the media server (Red5 in this case) is setup to record the live streams, each time a stream is started or closed, the media server calls the webserver side file getRecordedVideosInfo sending the following information about the stream: streamname, the siteId of the user that made the recorded videostream, the username of the user that made the recorded videostream.

This API is disabled by default as it is works together with the media-server side setting recordAudioVideoStreams

So in order to enable this feature you must do the following steps:

  1. Edit avchat30/avchat3.properties and set recordAudioVideoStreams to true.
  2. In the Red5 installation directory go to the conf folder and edit red5.properties.
  3. Search for the following setting fileconsumer.delayed.write and set it to false.
  4. Restart Red5.

By default Red5 tries to automatically detect the location of the getRecordedVideosInfo.php file. If the file is moved to any other folder other than the AVChat installation folder or if the .aspx file is used instead, the location needs to be set manually using the new media-server side setting sendRecordingsInfoScriptURL from avchat3.properties.

The auto-create rooms mechanism

Starting with AVChat 3.6.3 the mechanism for automatic room creation has changed. The server-side setting (Red5 and AMS) autoCreatedefaultRooms has been deprecated and removed. Its functionality has been integrated into the defaultRooms setting. Leaving the value of this setting empty will disable the auto-creation mechanism.

The defaultRooms setting comes with a predefined room, The Lobby, which will enable the creation of this room for all new instances of AVChat. Already existing instances will not have rooms created automatically.

To create rooms automatically you need to add ROOM OBJECTS to the defaultRooms settings. You can add one or multiple rooms.

On Red5

Example for one room:

defaultRooms=[The Lobby,Main room for everyone,,0,,This is an automated created room]

To create more than 1 default room add another room object to the defaultRooms array and separate the room objects with a semicolumn:

defaultRooms=[The Lobby,Main room for everyone,,0,,This is an automated created room];[Super Room, The description,1234,0,,This is an automated created room]

On AMS

Example for one room:

application.defaultRooms=[{name:"The Lobby(auto)",description:"The Main Room",password:"",maxusers:50,ownerName:"",ownerId:"",siteId:"",ip:"127.0.0.1",clientId:"",welcomeMessage:"This is an autocreated room",playListArray:""}];

To create more than 1 default room add another room object to the defaultRooms array and separate the room objects with a comma:

application.defaultRooms=[{name:"The Lobby(auto)",description:"The Main Room",password:"",maxusers:50,ownerName:"",ownerId:"",siteId:"",ip:"127.0.0.1",clientId:"",welcomeMessage:"This is an autocreated room",playListArray:""}, {...another room object...}]

Localization

Changing the welcome message

Edit the welcome message for the desktop version in 5 steps:

Quick painless way to change the welcome message that shows up in the first room you enter in AVChat:

  1. Edit this XML file on your web server AVChat installation folder: translations/en.xml
  2. Go to line 416, you will see the welcome message on that line
  3. Change it to whatever you want
  4. Save and upload the en.xml file back to your web server/site
  5. Reload AVChat in the browser (if the old message still shows up refresh a few times or clear your browser cache)

Translating AVChat

AVChat loads the words and phrases used in the admin and user interface from external XML files. You will find these XML files in the translations folder. AVChat by default ships only with the English translation: translations/en.xml.

en.xml is a plain XML file that can be edited with any text editor.

In order to change a word, to translate the entire interface in another language or to change the initial welcome message you just need to edit these files and change whatever you need.

The languagefile variable in avc_settings.xml controls which language file will be loaded. You can have several language files (en.xml, es.xml, fr.xml, etc.) and load one or another based on the user’s location, ip or language settings in the browser (this is not a feature built in AVChat but it’s something that’s possible).

Where to find and share translations?

There’s a special area in our AVChat forum dedicated to exchanging language files: http://discuss.avchat.net/c/translation-files. You need to sign up as a user to access the existing uploaded language files.

Switching to RTL

Switching to RTL is very simple.

Just edit avc_settings.xml and change the value of the rightToLeft variable to 1. This will cause all text fields, including the text chat area to become right aligned and part of the UI to be arranged from right to left.

Integration

Passing the user name and gender from your web site to AVChat (auto login)

The login screen in AVChat 3 shows up to ask the user for its username and gender. However if you provide these info’s via integration.php (or integration.aspx.cs) and block the user from modifying them the login screen is not needed anymore so it will be skipped.

So this is what you need to do in order to auto login users:

  1. Set $avconfig['username'] to the username of the person logged in the website (you can collect this info from cookies, sessions or from the database).
  2. Set $avconfig['gender'] to male or female ( the gender of the person logged in the website, you can collect this info from cookies, sessions or from the database). Starting with build 1880 make sure the genders are the same with the id attribute from the genders.xml file.
  3. Set $avconfig['changegender']=0 which means the user will not be given the chance to change its gender
  4. Set $avconfig['changeuser']=0 which means the user will not be given the chance to change its username

If all the 4 steps above are completed, the login screen will be skipped and users will be logged in directly in the video chat without them being asked for a user name or gender (confrmation).

You can also use $avconfig['disableGenderSelection'] to disable the gender selection altogether (everyone will get the unknown gender and will have no icon displayed).

Automatically dropping users in a certain room with AVChat

By default, when a user joins AVChat 3 he is presented with a list of existing rooms. He can choose one and join it. You can however skip that and drop users directly into the room of your choice.

What you need to do is edit avc_settings.xml and change the value of the dropInRoom variable with the id of the room you want users to automatically be dropped in.

Below you see the setting configured (<value> tag) to drop in the room with id r1

<dropInRoom>
	<title>dropInRoom</title>
	<name>Drop in room</name>
	<type>string</type>
	<desc>Use the interface administration window to see what ids each room has, then come back here and paste that id here. If left empty the rooms list window will be shown automatically after login. Example value for single id: r0. Example value for multiple room ids: [r0,r1,r2]</desc>
	<examples>any room id shown in the roms panel in the admin area of AVChat (admin.swf) </examples>
	<default></default>
	<value>r1</value>
</dropInRoom>

Starting with build 1880 the dropInRoom variable also supports an array of id’s so that the users will automatically join multiple rooms.

Example notice the <value>;

<dropInRoom>
	<title>dropInRoom</title>
	<name>Drop in room</name>
	<type>string</type>
	<desc>Use the interface administration window to see what ids each room has, then come back here and paste that id here. If left empty the rooms list window will be shown automatically after login. Example value for single id: r0. Example value for multiple room ids: [r0,r1,r2]</desc>
	<examples>any room id shown in the roms panel in the admin area of AVChat (admin.swf) </examples>
	<default></default>
	<value>[r1,r2,r3]</value>
</dropInRoom>

Every room in AVChat 3 has a unique id. When you log in the AVChat through the admin interface (admin.swf) the leftmost column in the rooms list shows the id of each room:

General integration guide

This is not a step by step guide because user management systems are different from a web site to another and from a CMS to another.

By integrating AVChat with your users database we understand that the users of your web site will have to login only once (through he normal login process on your web site) and have the same user name on the web site and in the video chat. Furthermore if your web site allows for several user levels (like guests, free members & premium members) you can impose restrictions one some user levels in order to incentivise them to purchase a paid plan.

How AVChat loads username/gender/enabled features information

When a user visits your web site and reaches the HMTL page with AVChat embedded in it, the HTML file and the the AVChat Flash .swf file are downloaded to the users computer and displayed in their browser.

Then avc_settings.xxx (PHP or .NET depending on your webserver) is executed on the web server and returns a string containing many variable/value pairs that are used by the .swf file. There’s one variable for the username, one for the background image, etc. .

You can see an example of what is returned by executing our avc_settings.php file (from our online demo) in the browser: http://avchat.net/demos/avchat30/avc_settings.php.

All the variables accepted and used by the .swf file are listed and explained in the avc_settings.xml file.

If we were to talk about it in a timely manner, the integration will take place when the avc_settings.xxx file executes on the web server.

Deep in the problem

Once a person is logged in on your web site, the user management system will remember (using a cookie, or a session variable) the persons id, username, real name, email, gender and other details. Once the user logs out, the user management system “forgets” him (the cookie saved in the users browser is deleted, session variables are also deleted from the web server).

You need to look through the existing code and analize how the existing management system remembers the person logged in. Either COOKIES or SESSIONS are used. If you have never learned about these before, this is a good time to do it! :)

Cookies are little bits of information that are stored by your browser and sent with every call to the web site. Session variables are little bits of information that are stored by the web server individually for each visitor of your website.

Username and gender are automatically recognized

When the avc_settings.xxx file is executed, it should check for existing cookies (sent by the users browser) or session variables (saved on the web server for that specific user), and should populate the username and gender variables with the correct values for that user.

The variable for the username inside the PHP configuration file is $avconfig['username']. The variable for the gender inside the PHP configuration file is $avconfig[gender].

Different settings for different user groups

If your web site allows for different levels of membership you can impose restrictions on some of them.

AVChat obeys to whatever values the avc_settings.xxx file returns so you can configure it to return a special set of variables/values when a guest user is executing it (detection based on COOKIES or SESSIONS) and another set of variables/values when a paying user executes it.

Every variable in the avc_settings.xxx file can be configured according to the level of the user.

Here are a few ideas of what you can do

  • Allow “gold” users to send higher quality video and audio by pointing the value of miccamsettingsurl to a XML file with better quality settings
  • Integrate will all the Pay Per View settings
  • Allow “gold” users to see more web cams at a time by modifying the value of maxcams when the logged in user is detected as “gold”
  • Drop “gold” users in selected rooms, while “free” users gather only in the lobby by modifying the value of dropInRoom according to the level of the user
  • Prevent “free” users from creating rooms or initializing private chat or making their video streams private

Further notes

  • You might want to block the user from changing the username and gender detected by the avc_settings.xxx file in the login screen of the AVChat user interface: to do this set the value of changeuser and changegender to 0.
  • When both changeuser and changegender are set to 0 in the .NET/PHP intergration file, AVChat will skip the login screen of the user/admin interfaces and jump directly to the chat area.
  • You can test the integration by logging in, loading the avc_settings.xxx file directly in the browser, and checking the variable/value pairs it returns. This way you can also check for any syntax errors that might have slipped in while editing the file.
  • We also provide integration services for a certain fee: http://avchat.net/buy-now#services
  • If you are in need of a good text editor we recommend [Atom]https://atom.io/
  • A good introduction on PHP (including Sessions and Cookie variables) can be found here: http://www.w3schools.com/php/default.asp
  • A good introduction on .NET (including Sessions and Cookie variables) can be found here:http://www.w3schools.com/aspnet/aspnet_pages.asp

Placing ads around the video chat

Placing ads around the video chat is simple. The video chat itself is actually a Flash .swf file embedded in a HTML file. In that HTML file you can place anything: links, images, AdWords ads, banners, etc. .

The default HTML file embedding the index.swf file (main video chat file) is: index.html so to add ads around your video chat:

  1. Connect to your web site using FTP
  2. Edit index.html with a text editor
  3. Place your ad code in it
  4. Save and upload back to web server

A little bit of HTML knowledge might be required tough to properly place the ads above, below or to the sides of the video chat.

Troubleshooting

Connection issues

You or your users may experience one of the following connection issues. We will explain what they mean and what can be done to solve them.

Connection failed

If when trying to connect using AVChat 3, you are getting this error message:

Connection failed, media server might be down or firewall might be blocking the connection!

You need to check:

  • Your RTMP connection string and make sure it is correct
  • There is a firewall on the media server blocking TCP traffic over the specific ports: 1935 and 5080 (use this tool to check if the ports are pen on your media server)
  • The media server might not be running (you can check if Red5 is running by going to http://yourred5server.com:5080/ or on Wowza http://yourwowzaserver.com:1935)
  • The media server might have not started properly (thus is not running, you can check the logs for any error messages during startup)
  • The user trying to connect is behind a firewall that blocks the connection (either a personal one installed on his computer or a corporate one installed on his network, to test his connection he should run these connection tests: http://www.flashcomguru.com/apps/port_test/index.cfm )

Connection Rejected:No scope

If when trying to connect using AVChat 3, you are getting this error message:

Connection Rejected:No scope ”avchat30/_definst_” on this server

OR

The connection with the video chat server could not be made

It means you are using Red5 and your Red5 is running but:

  • make sure you installed the AVChat 3 Red5 server files properly at Red5/webapps/avchat30
  • make sure you restart Red5 after you installed the above mentioned avchat30 app

Connection Rejected Application is not defined

If when trying to connect using AVChat 3, you are getting this error message:

Connection Rejected: [Server.Reject]: (_defaultRoot_,_defaultVHost_): Application (avchat30) is not defined

There are 2 causes/solutions for this error:

  • You are using AMS and you have not created the AMS server side avchat30 app AMS/applications/avchat30, follow the installation instructions and try again.
  • If the avchat30 app folder is installed properly restart the AMS server (or just the vHost through the FMS Management Console)

Connection success, waiting for server

If when trying to connect using AVChat 3, you are getting this error message:

Connection success, waiting for server…

There is 1 possible cause/solution for this issue:

The avchat30 application folder was not installed properly on the media server (it does not contain the proper files). Make sure you follow the installation instructions for the avchat30 app folder exactly.

Video quality issues

On the publisher side

Low framerate

Solutions:

  1. Increase the light in the room, natural light works best.
  2. Get a better web cam, good web cams capture a lot of frames with little light in the room.
  3. Lower the picture resolution requested by AVChat 3, some web cams just can’t capture 30fps at higher resolutions.
  4. Increase the movement in the shot, if there’s no movement Flash Player will not capture many frames/second because there’s no movement.

Video stream does not use entire allocated bandwidth

Solutions:

  1. Increase the light in the room, natural light works best. More light helps the web cam capture more details!
  2. Get a better web cam, good web cams capture a lot of detail with little light in the room. DV cams for example capture huge amounts of data compared to normal web cams. Check your connection to the media server. When you’re publishing video you’re uploading data to the media server. Even tough you might have a 20Mbits/s or higher Internet connection, that’s most probably your download rate, your actual upload rate could be much less. If you’ve configured the video chat to use as much as 768kbits/s per stream, this ammount of video data will not fit in real time through your 350kbits/s upload pipe.

Problem: dark image or noisy image

Solutions:

  1. Increase the light in the room, natural light works best.
  2. Get a better webcam.

No image at all or blank image

Solutions:

  1. Make sure your web cam is not already used by another app.
  2. Make sure the proper web cam is used by Flash Player (Right click -> Settings -> Web Cam tab -> Select the web cam you want to use from the drop down list)
  3. Make sure the browser was allowed to have access to your webcam. A pop up dialog shows up on most modern browsers asking you if you wish to allow access to your camera and microphone.

Ensuring high connection success rate

Why a connection attempt to a working media server might fail

Red5, AMS and Wowza by default only accept RTMP connections over port 1935. This will work fine for most home Internet connections however when your user is behind a corporate firewall/network he might hit 2 major restrictions:

  1. NO traffic/connections to non standard ports like 1935 (default port for RTMP). Traffic is only allowed to standard ports like 80 (HTTP) and 443 (HTTPS) . The solution for this is to configure the media server to accept RTMP connections over ports 443 and 80 .
  2. NO non-http traffic allowed (or a proxy server is used). The solution for this is to configure the media server to accept RTMPT connections. RTMPT is RTMP wrapped as HTTP and its slower. It also adds some overhead/consumes more bandwidth because each RTMP packet needs to be wrapped as HTTP. According to a 2004 Adobe article, only 4% of Internet users are behind such a network.

The automatic connection sequence in Flash Player

By default, when a Flash Player app (AVChat 3 for example) tries to connect to a media server (Red5, AMS or Wowza), it automatically tries to establish a connection by using the following sequence of ports and protocols:

  1. rtmp://myserver:1935/avchat30/_definst_
  2. rtmp://myserver:443/avchat30/_definst_
  3. rtmp://myserver:80/avchat30/_definst_
  4. rtmpt://myserver:80/avchat30/_definst_

This connection sequence can enable connections to succeed that otherwise would not. This automatic retry sequence occurs only if the initial connection specifies the RTMP protocol and does not specify a port – for example rtmp://myserver/avchat30/_definst_. During this connection sequence, users may wait several seconds for multiple connection attempts to time out.

Configuring your media server for high connection success rate

If you’re using AMS:

Solution for restriction 1

Configure it to listen for RTMp connections over ports 1935, 443 and 80. You need to edit conf/fms.ini, set ADAPTOR.HOSTPORT = :1935,443,80 and restart AMS. Make sure you don’t have other apps (like the Apache web server) started and listening on 80 or 443.

Solution for restriction 2

Same as above, AMS can listen for both RTMP and RTMPT connections over the same ports at the same time

Most AMS hosting services (like influxis.com) are already configured like this out of the box.

If you’re using Wowza:

Solution for restriction 1

Make it listen for RTMP connections over ports 1935, 443 and 80. You need to edit conf/VHost.xml , set <Port>1935,443,80</Port> and restart Wowza. Make sure you don’t have other apps (like the Apache web server) started and listening on 80 or 443.

Solution for restriction 2

Same as above, Wowza can listen for both RTMP and RTMPT connections over the same ports at the same time

If you’re using Red5:

Solution for restriction 1

Bind RTMP connections to port 443 instead of 1935 (Red5 can listen for RTMP connections over several simultaneous ports like Wowza and AMS can). You need to edit conf/red5.properties, set rtmp.port=443 and restart Red5. Make sure you don’t have other apps (like the Apache web server) started and listening on 443 . You can also use port 80 but we will use that for listening for RTMPT connections as explained below.

Solution for restriction 2

Bind RTMPT connections to port 80. You need to edit conf/red5.properties, set rtmpt.port=80 and restart Red5. Make sure you don’t have other apps (like the Apache web server) started and listening on 80.

How you can check YOUR computer’s connection

This tool will attempt to establish RTMP and RTMPT connections (using all ports) to a properly configured media server.