UNVedu Files

UNVedu_v2

Abstract

Several popular IP-based services today involve entertainment media streaming. We propose (and make available online) Java-based media streaming over IP utilizing the Matroska (MKV) container, which is rapidly gaining popularity within online user communities. Fast and accurate access to individual MKV elements is ensured by a hinting mechanism tailored to the container. The achieved throughput and continuous playback capability has been examined under RTSP/TCP with UDP or TCP transmission over Wi-Fi, which is setup via a single port or via multiple ports. New avenues for media traffic differentiation with the proposed framework are highlighted. 
The project is suitable for research and advanced graduate courses on video streaming systems over the Internet Protocol.

For a 4-page technical overview of the basic features, please see:
I. Tsakos and Y. Andreopoulos, "Multiport streaming Of matroska (MKV) video over IP," Proc. London Communications Symposium (LCS), 2010. http://www.ee.ucl.ac.uk/lcs/   
http://www.ee.ucl.ac.uk/~iandreop/TSAKOS_LCS_2010_MultiportVideoStreaming.pdf 

For a summary of the graphical user interface and encryption features, please see file 
Jeuk_IMS_Assignment.pdf within the main folder.

If you are interested on a video streaming project with real-time video capture and sub-500ms end-to-end delay please see the UNV project at: http://sourceforge.net/projects/unv/ instead. UNV is streaming video only with very low delay and without MKV support based on a C/C++ implementation using the FFmpeg and the v4l2 libraries (Linux only). This project aims for higher-delay rich media streaming and can be used on any platform with Java, VLC and mkvtoolnix (more on these later).

Changes since UNVedu_v1
•	Support for TCP is now available
•	Support for advanced hinting, indicating stream elements, such as I/P/B frames is now available

Contributors (alphabetically)
Yiannis Andreopoulos, iandreop@ee.ucl.ac.uk (supervisor, project coordinator)
Frankie Cojocaru, frankie.1993@hotmail.co.uk (advanced hinting via mkvinfo, bug fixes, testing)
Husam Fahmi, zceef13@ee.ucl.ac.uk (hinting improvements and TCP support) 
Prashant Jain, prashant.jain.10@ucl.ac.uk, im_prashant@yahoo.com (hinting via mkvinfo)
Sebastian Jeuk, sebastian.jeuk.10@ucl.ac.uk, sjeuk001@gmail.com  (encryption, GUI features)
Nicholas Mastronarde, nmastron@buffalo.edu (concept & initial MATLAB design of advanced hinting)
Asset Nurbakimov, asset.nurbakimov.09@ucl.ac.uk (advanced hinting via mkvinfo)
Obada Sawalha, ssobada@gmail.com (initial project design)
Ioannis Tsakos, giannistsakos@hotmail.com (general project design and multiport architecture)

Important 
This README.pdf file, the LCS paper and file Jeuk_IMS_Assignment.pdf must remain intact in all derivative works produced by this work. 

Licence 
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 
MKVToolnix, VLCJ, JCA, and VLC are all distributed under their original licences, please see:
http://www.bunkus.org/videotools/mkvtoolnix/
http://code.google.com/p/vlcj/ 
http://download.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html 
http://www.videolan.org/vlc/ 

Compiling 
The project can be compiled with any IDE, such as Netbeans or Eclipse. Project files are provided for Netbeans (you can download Netbeans at www.netbeans.org/). Naturally, you must have the Java Development Kit installed on your computer (aka “Java compiler”) to compile and develop Java code via Netbeans or any other Java IDE. You can download and instal Java JDK from:
http://www.oracle.com/technetwork/java/javase/downloads/index.html. 

After installing and launching Netbeans, select:
File --> Open Project --> (Navigate and open “UNV_Server” project)
File --> Open Project --> (Navigate and open “UNV_Client” project)

To compile, right-click each project file (on the “Projects” window of Netbeans) and select “Clean and Build”. At the Client project, remember to add the VLC Java libraries by right-clicking the Libraries folder on the “Projects” window and selecting “Create Library” --> (use name VLJ1.2.0 or similar) and then select Add JAR files and navigate to the folder containing files jna-1.jar, platform-1.jar and vlcj-1.2.0.jar and add these JAR files. 
If you get any errors during compilation that seem like IDE (Netbeans errors), right-click the project file, select “Properties” and change options in the Build --> Compile option to NOT include Debug information. If this does not fix the problem, try to search on the internet for the specific compilation error you are getting, it is likely your IDE version may not be compatible with a particular build or compile option preset in the project file, in which case you can disable it. 

Finally, if you get messages warning about Library Reference Problems at the Client project: These are related to the VLCJava libraries. Please go to: Client-->Properties-->Libraries and add all the Jar files in the Client folder before recompiling. VLCJ may not work properly in MacOS or Linux, in which case simply use the “external VLC” option at the Client. If you keep getting errors at the Server or Client, try launching both projects via the Netbeans IDE. 

Important: 
In order to be able to hint new videos (which is an essential part of this project), you MUST download and install MKVToolnix from here: www.bunkus.org/videotools/mkvtoolnix/
Most Linux distributions will support these tools in their Package (or repository) Manager, search for “mkv” to find MKVToolnix and install it (root privileges are required). 
If you are using Microsoft Windows, after the download and installation from the above website, you MUST add the install folder in your PATH variable, please search “Environment Variables” in Microsoft Windows and edit the PATH variable to append it with the install directory of the MKV tools. Most likely you will need to have administrator rights to do this. 
If you do not have administrator rights on your machine, you can still compile the tools manually but you will need to change the code of the Server project (file Server_fnc.java – search for mkvinfo to find the system call) to point to the location that the mkvinfo is placed in your system and recompile the Server project. 
Also, you MUST download and install VLC in the default directory in your system (Windows, Mac, or Linux – via your package manager) if you would like to use VLC as the external player. 

Usage
The compiled Server and Client JAR files will be placed on the /dist folder of each project. In the Server project, we include one video that can be used for testing purposes (“mixtape.mkv” from http://vodo.net/). If you are launching the project by clicking the JAR file in the /dist folder, please remember to place the videos in the /dist folder (i.e. same folder as the UNV_SERVER.jar) or (preferably) copy the JAR files and the video files in the folder /test to run your experiments.

Launching the Server (UNV_SERVER.jar), you can setup the following:
•	Number of ports to be used (1~6)
•	RTSP port to be used (all ports are opened serially from this number)
•	Frame Period, i.e. the number of milliseconds in-between two packet transmissions. 
•	Fixed Packets, at the moment keep this to the default “No”
•	Encryption (Yes/No) and Type (if “Yes”), if you would like to use encryption and which type. More information on Encryption is included in the report: 
S. Jeuk, “Security in the video streaming environment UNV,” Assignment for the MSc course Internet Multimedia Systems, Dept. of Electronic and Electrical Engineering, University College London, 2011. 
•	Distance, set the distance in number of packets between the Server and the Client so that the Server adaptively backs off from sending when the reports received via RTSP; this feature can be used for buffer and traffic management in the streaming session
•	TCP/UDP selection, with TCP being the default

When the Server is ready, press “Run Server” to launch the Server. If you would like to reset the server, press the “Reset” button. Currently the Server has no graceful termination feature and it can simply be closed when the streaming session ends.

Launching the Client (UNV_CLIENT.jar), you can setup the following:
•	Number of ports to be used (1~6), must match the server setting!
•	Server IP-Address and Server Port to be used, must correspond to the Server settings! Use the default address if you would like to test on the same machine with localhost (packets going up and down the stack)
•	Video File Name, must be an MKV file present in the same directory as the UNV_SERVER.jar 
•	Start VLC at, number of packets after which VLC is launched; setting this too low you risk underruning the client, setting it too high means you wait longer for the video to start once you press “play”
•	OS (Windows/MAC/Linux), used soley to change the way the external VLC is called
•	Buffer-size, change to increase or decrease the overall buffer size; this has little impact unless you are targeting very low delay streaming
•	Encryption (Yes/No) and Encryption-Type, must match the server settings.
•	Start external VLC, Start Java VLC (Yes/No), select which one you would like to use. 
•	TCP or UDP selection, with TCP being the default

When the Client is ready, press “Create Client & Connect to Server” to launch the Client. You should see an additional control panel pop up with self-explanatory buttons. First press Setup, then Play to stream. Eventually, you can press Stop and Teardown to close everything. Currently, Server and Client teardown is not done in a graceful manner and can even throw some exceptions in the IDE environment during their termination. 
Both Client and Server can of course also be launched via the Netbeans (or Eclipse, or other) IDE for debug or development purposes but please remember to place the videos in the main Server directory in this case (not in the /dist folder) as this is the execution folder that the IDE will assume by default (and thus will be looking for the videos in that folder). 
The first time a video is streamed, it will be hinted, this may take a few seconds. This is only done the very first time the video is streamed and the hint file will remain in the folder along with the video (with the extension .udp_hint). Hinting is done via the mkvinfo file of MKVToolnix. 

For Comments, Errors, etc.
Please report any comments or bugs to one or all of the contributors. No support is warranted for them but we shall make reasonable efforts to respond to reasonable queries. We are also very interested to hear about usages of this project. 
This is an on-going effort with contributions designed annually via the MSc module “Internet Multimedia Systems” (formerly known as “Interactive Multimedia Systems)
http://www.ee.ucl.ac.uk/syllabus/syllabusIMS.pdf
and via MSc projects at the Dept. of Electronic and Electrical Engineering of UCL. 

“To Do” List
Here is a list of features or fixes that we would love to see developed in the UNV testbed (and more contributors/contributions are welcome!):
Features:
•	RTSP based Pause/Restart/Random-access features
•	Support for multiple Clients concurrently connected to the Server
•	Graceful termination of the streaming session and restarting without re-launching the Client and Server
•	GUI support for file-management at the Client side, e.g. the Client requesting the list of available video files from the Server and then the user being able to click the video file they want to receive via the streaming session
•	Detailed GUI support for encryption, e.g. key generation by password insertion 
•	TCP-friendly streaming and smart buffer management via RTSP live reports for content-driven or traffic driven prioritization
•	Mixture of multi-port TCP-based and UDP-based streaming with appropriate buffer control to balance the delay difference between TCP and UDP-based delivery
 
Bug Fixes
•	Encryption with AES seems to be crashing the Server in Windows, most likely this is a problem of the encryption library
•	There are internal Java GUI null-pointer exceptions popping up in Linux and/or MS Windows even though the code works; most likely these are internal IDE or Java runtime errors but they could be caused by the GUI design
•	The Server seems unable to find the video files when running as standalone JAR file in Linux. This problem does not occur in MS Windows and it also does not occur in Linux when running via the Netbeans IDE. 
•	VLCJ is not functional in Linux, it seems the libvlc library cannot be imported in the code, despite pointing to the right location /usr/lib. This could be a problem because the code is not run with root privileges. Hence, only the external VLC option is available in Linux at the moment.
•	Multiport buffering currently flushes the buffer before all packets are received from all ports, which creates occasional artifacts even under TCP. 
The basic mechanisms most of these features and bug fixes already exist in the test-bed but they are not formally supported/fixed at this stage.