Whisper

This repository contains the required submodules to stream audio from the browser to the server.

###Definition

Streaming media is multimedia that is constantly received by and presented to an end-user while being delivered by a provider.

• http://en.wikipedia.org/wiki/Streaming_media

Note: the end-user in context of streaming audio would be the Server hosting this application, and the provider would be the clients browser.

WebSocket is a protocol providing full-duplex communications channels over a single TCP connection. It is designed to be implemented in web browsers and web servers, but it can be used by any client or server application.

• http://en.wikipedia.org/wiki/WebSocket

###Overview

This project utilizes the WebSocket Protocol. Some configurations need to be made at each end, in order for WebSocket to be able to communicate from the browser to the server (and vice versa):

First, a WebSocket server needs to be defined. Since AutobahnPython is the chosen server-side implementation, the corresponding server.py will need to utilize the respective interfaces.

Once the server has been created, the client-side implementation needs to be defined. This project chooses to use the javascript WebSocket Protocols. However, other client-side schemes are possible, for example, AutobahnJS. Implementing AutobahnJS on the client-side, would require the use of the WAMP Protocol on the server-side (provided in AutobahnPython) as well. The change from WebSockets, to the WAMP Protocol would change server.py, respectively.

Note: The WebSocket protocol is supported by all major browsers, except:

• IE 9-
• Opera Mini 5-7
• Android Browser 4.3-

After the WebSocket protocol has been defined, this application is able to stream to the server using the HTML5 getUserMedia object. This object first prompts permission to access the microphone. Once granted, an audio stream object is created. The stream is sent to the server.py, where it can be accessed, and modified.

Unfortunately, not all browsers (Internet Explorer, Safari, and mobile devices) support the getUserMedia object. In particular, Internet Explorer claims to support this feature in later releases, while Safari supports its own streaming API. Mobile devices will need to incorporate a framework such as Cordova, or Phonegap in order to support audio streaming.

Since getUserMedia has not been adopted by all browser, a fallback is required. In this project, a basic flash fallback has been implemented. This implementation requires users to start, then stop recording an audio, and click upload, before the entire audio recording is saved to the server. Later releases for this project, may incorporate a flash fallback implementation that streams audio from the browser to server, along with a mobile device polyfill.

Note: to see a working example of this project, refer to test.php.

##Installation

###Linux Packages

The following packages need to be installed through terminal in Ubuntu:

# Google Chrome Dependencies:
sudo apt-get install libappindicator1
sudo apt-get install libindicator7

###Google Chrome

This project requires testing the functionality of getUserMedia. The Google Chrome browser, ensures, and provides this functionality.

wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt-get update
sudo apt-get install google-chrome-stable

Note: This project assumes Ubuntu Server 14.04 as the operating system.

##Configuration

###GIT

Fork this project in your GitHub account, then clone your repository:

cd /var/www/html/
sudo git clone https://[YOUR-USERNAME]@github.com/[YOUR-USERNAME]/whisper.git whisper

Then, add the Remote Upstream, this way we can pull any merged pull-requests:

cd /var/www/html/whisper/
git remote add upstream https://github.com/[YOUR-USERNAME]/whisper.git

####GIT Submodule

We need to initialize our git submodules:

sudo git submodule init
sudo git submodule update

Note: We have to use the sudo prefix, since we haven't taken care of file permissions yet.

The above two commands will update submodules. If they are already initialized, then the latter command will suffice. Then, we need to pull the code-base into the initialized submodule directory:

cd /var/www/html/whisper/
git checkout -b NEW_BRANCH master
cd [YOUR_SUBMODULE]/
git checkout master
git pull
cd ../
git status

Now, commit and merge the submodule changes.

###File Permission

Change the file permission for the entire project by issuing the command:

cd /var/www/html/
sudo chown -R jeffrey:sudo whisper

Note: change 'jeffrey' to the user account YOU use.

###AutobahnPython

Provides an open-source, real-time framework implementation for the following protocols:

• WebSocket Protocol
• Web Application Messaging Protocol (WAMP)

Either protocols, excel at pushing data asynchronously between the client, and server in real-time. In order to use the AutobahnPython framework, it must first be installed:

cd /var/www/html/whisper/AutobahnPython/autobahn/
sudo python setup.py install

###Twisted

AutobahnPython requires a networking framework, which must be either Twisted, or asyncio. This project implements the Twisted framework:

cd /var/www/html/whisper/twisted
sudo python setup.py install

Note: Generally, Twisted is the framework of choice if the environment only provides python 2.x (will support python 3.x). Whereas, asyncio is generally preferred if the environment is python 3.x (included in python 3.4+).

##WebSocket Execution

###Start Server

In order for the browser to be able to connect to the AutobahnPython Webserver, server.py needs to be executed:

cd /var/www/html/whisper/websocket/
python server.py

This will dedicate the terminal window tab specifically to the server, and unresponsive to other commands.

###Stop Server

The WebSocket Server can be stopped within the dedicated terminal console by pressing ctrl-c.

###Server Echo

Periodically, print statements within the dedicated terminal will display the status of certain actions. For example, when a WebSocket Server is connected, then started:

sending echo: CONNECTED TO YOU
sending echo: start

Likewise, when the WebSocket Server is stopped:

sending echo: stop

Other print statements may appear in the dedicated terminal console, and will vary accordingly.