= Ariba Overlay Multicast VLC Plugin - Overlay-based Videostreaming using Ariba and MCPO Application-Layer Multicast = [[Image(logotest.png,right)]] === What is the AribaMC plugin? === The '''AribaMC''' plugin is an Open Source streaming module for the [http://www.videolan.org VLC media player]. It enables video streaming through the overlay-based virtual network substrate Ariba in combination with the MCPO application-layer multicast protocol. With '''AribaMC''' you can deliver video streams to groups of users, similar to IP Multicast, but without any need of in-network multicast support. Also, through the use of Ariba, '''AribaMC''' can cope with several protocol issues such as IPv4/IPv6 transitions, Network Address Translation (NAT), mobility, and many more networking problems in a self-organized and distributed manner. For more information about Ariba, MCPO, or the SpoVNet project, please refer to: http://www.ariba-underlay.org , http://www.spovnet.de, mayer[at]kit[dot]edu, mario.hock[at]student[dot]kit[dot]edu === Get it! === Anonymous SVN source code with newest versions: * [https://i72projekte.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk Ariba] * [https://i72projekte.tm.kit.edu/SpoVNet-KA/entwicklung/mcpo/trunk MCPO] * [https://i72projekte.tm.uka.de/SpoVNet-KA/entwicklung/tools/vlc/vlc-1.0.6 VLC 1.0.6 with AribaMC] * [https://i72projekte.tm.uka.de/SpoVNet-KA/entwicklung/tools/vlc/vlc-1.1.5 VLC 1.1.5 with AribaMC] Ariba and MCPO source official releases (use Ariba >= 0.6.0 and MCPO >= 0.5.0): * [https://projekte.tm.uka.de/trac/spovnet-base/downloads Ariba] * [https://projekte.tm.uka.de/trac/spovnet-base/downloads MCPO] Precompiled packages of Ariba, MCPO, and AribaMC plugins for VLC 1.0.6 that comes with Ubuntu 10.04 LTS * [attachment:AribaMCv0.1_VLCv1.0.6_32.tar.gz AribaMC precompiled package for 32 bit ] * [attachment:AribaMCv0.1_VLCv1.0.6_64.tar.gz AribaMC precompiled package for 36 bit ] === Setting up / installing === The ariba framework is currently available for Linux, therefor, the plugin is also Linux-based. As soon as further platforms are available it will be announced here. A quick and simple way for testing and using the plugin (besides compilation) is the use of precompiled libraries, which we provide. In this section we describe how to set up an ''Ubuntu 10.04'' for this purpose. This should be adoptable to other Linux distributions easily. Instructions how to compile the plugin are provided in the Developers Guide below. For running the AribaMC plugin a number of packages are required on the target system. For the precompiled binaries of Ariba and MCPO you need the exact versions of the libraries, if you compile by yourself use the newest available. {{{ sudo apt-get install vlc sudo apt-get install libboost-system1.40.0 sudo apt-get install libboost-thread1.40.0 sudo apt-get install libboost-regex1.40.0 sudo apt-get install liblog4cxx10 }}} Please download the tar-ball containing the Ariba and the plugin libraries from the links provided in the intro of this documentation above. Unpack the archive to e.g. {{{$HOME}}}. You will find two folders for 32 or 64 bit {{{AribaMC_VLC_32}}} or {{{ArbaMC_VLC_64}}}, then {{{aribalibs}}} and {{{vlclibs}}}. Set the {{{LD_LIBRARY_PATH}}} to aribalibs: {{{ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/AribaMC_VLC_32/aribalibs }}} and run VLC with {{{ vlc --plugin-path=$HOME/AribaMC_VLC_32/vlclibs }}} === A first test: === Now it's time for a first simple test. Run two instances of the modified vlc-players. At best, use two different machines as there are some connection problems with Ariba when running two instances on the same machine[[BR]] To follow the instructions here, you can switch the language to English: {{{ LANG=en_US.UTF-8 vlc --plugin-path={{{$HOME}}}/AribaMC_VLC_32/vlclibs }}} When you now have two vlc-windows let's continue, we'll call them [S] and [R]. [[Image(VLC_media_player.png)]] * Receiver side [R] * On [R] please click: Media > Open Network Stream... [[BR]] * Then choose: Protocol: »AribaMC« (Note: If you can only see protocols like: HTTP, HTTPS, UDP, etc but no »AribaMC« then the plugin wasn't loaded correctly into your vlc. Please refer to the trouble shooting section in this case.) [[BR]] * The address field should now look like this: {{{1234:localhost:5000}}} [[BR]] * Press »play«. [[Image(Open_Media.png)]] * Server side [S] * On [S], click: Media > Streaming... [[BR]] * Add a video file. [[BR]] * Press »Stream«. [[BR]] * Press »Next«. [[BR]] * Choose »AribaMC« our of the list and press »Add«. [[BR]] * Now you can see: Source: Port: 5000; Destination: Address: localhost, Port: 1234 [[BR]] * Disable transcoding and press »Stream«. [[BR]] * After a few seconds you should see the video in [R]. [[Image(Stream_Output.png)]] === Usage === In this section we describe the parameters of the AribaMC plugin and some usage scenarios which demonstrate the strength of the AribaMC plugin approach. AribaMC uses a Spontaneous Virtual Network (SpoVNet) for distributing the video content. Each SpoVNet have to consist of 0-1 senders and 0-N receivers. The connection procedure does not depend on the role (sender/receiver) one instance has. This can confuse a little in the beginning, as on most streaming protocols the role defines whether one instance is client or server. ==== Parameters ==== The AribaMC plugin takes three connection parameters in the GUI: {{{SourcePort:DestinationAddress:DestinationPort}}} (e.g. {{{1234:localhost:5000}}}) The {{{SourcePort}}} provides an entry point for other instances to the SpoVNet our instance is in (or will be in). To access this entry point {{{DestinationAddress}}} and {{{DestinationPort}}} must be set on the IP address (or domain name) and {{{SourcePort}}} of an instance in the targeted SpoVNet. An instance which has not connected to such an entry point makes up a SpoVNet with only itself in it. While the GUI only provides limited configuration capabilities, you can use a configuration file that allows for more fine-grained configuration. The configuration file can only be loaded when using VLC with the command line. Setting the configuration file is currently different on sender and receiver side. For setting the config file of the sender use {{{ vlc --plugin-path=$HOME/AribaMC_VLC_32/vlclibs --sout-aribamc-config-file ./config.txt }}} and for the receiver side use {{{ vlc --plugin-path=$HOME/AribaMC_VLC_32/vlclibs --config-file ./config.txt }}} The configuration file can hold several parameters, the [wiki:Documentation/Configuration main documentation is here]. To achieve the same effect as in the GUI use: {{{ ariba.endpoints = tcp{1234} ariba.bootstrap.hints=mcpovlc{ip{127.0.0.1};tcp{5000}} }}} The first is the local server socket port, the second is the bootstrap information for the remote IP and port. Note, that you can only use hostnames in the GUI, the settings file requires IP addresses. In the settings you can use furthermore IPv6 addresses, RFCOMM, and automatic bootstrap modules. See the [wiki:Documentation/Configuration documentation] for the format. We currently have three automatic bootstrap modules that help to join the network without giving any IP/port information: * broadcast - A periodic broadcasting protocol using IPv4 and IPv6 * mdns - Multicast DNS using the Avahi library * sdp - Bluetooth service discovery protocol If you are running on a LAN, you can e.g. use the following in the settings {{{ ariba.bootstrap.hints=mcpovlc{bootstrap} }}} for running the automatic broadcast based bootstrapping module. Note, that a client does only broadcast its bootstrap information if the module is enabled, and can only receive the information if the module is enabled. Just using it on one machine does not make sense, you have to use it on multiple machines. The mdns plugin is normally the method of choice, broadcast generates quite a lot of broadcast packets (every some second) in the network but reacts much faster than mdns. The sdp plugin is used if you are using Bluetooth RFCOMM connections. To view further parameters of the AribaMC plugin do: {{{ ./vlc -p aribamc }}} which outputs {{{ VLC media player 1.0.6 Goldeneye MCPO input (aribamc) --caching Caching value in ms --config-file ariba config file MCPO stream output (aribamc) --sout-aribamc-caching Caching value (ms) --sout-aribamc-config-file ariba config file }}} ==== Creating a SpoVNet ==== At first we need an initial SpoVNet, consisting of a single AribaMC instance. This instance can either be server or client but must be accessible from (at least) the second instance. (Means, it mustn't be blocked by a firewall or NAT.) On the first instance we have to set the {{{SourcePort}}}. {{{DestinationAddress}}} and {{{-Port}}} can be set but as long as there is no other instance listening there, setting this parameters has no effect. On the second instance, {{{DestinationAddress}}} and {{{-Port}}} must be set adequate. It can also set the {{{SourcePort}}} to act as an entry point later. A third instance can either use the first instance or the second one as an entry point. (Given that both are accessible and have their {{{SourcePort}}} set.) Et cetera. Note: In the current implementation the sender begins the transmission immediately when it's ready. Using the sender as initial node may result in missing the beginning of the transmission. ==== Examples / Scenarios ==== {{{ 192.168.1.1 192.168.1.2 _____ _____ | 1. | | 2. | |_____| ------>------ |_____| \______\ \______\ 5000: 1234:192.168.1.1:5000 }}} {{{ 192.168.1.1 192.168.1.2 _____ _____ | 2. | | 1. | |_____| ------>------ |_____| \______\ \______\ 5000:192.168.1.1:1234 1234: }}} {{{ 192.168.1.1 192.168.1.2 _____ _____ | 1. | | 2. | |_____| -->--+--->--- |_____| \______\ \ \______\ \ 5000: V 1234:192.168.1.1:5000 \ \ 192.168.1.3 _____ | 3. | |_____| \______\ 1234:192.168.1.2:1234 }}} {{{ 192.168.1.100 192.168.178.100 _____ » « _____ | 3. | » « | 2. | |_____| -»->--+--->--«-- |_____| \______\ » \ « \______\ » \ « 5000:141.3.70.130:1234 V 1234:141.3.70.130:1234 \ \ 141.3.70.130 _____ | 1. | |_____| \______\ 1234: }}} {{{ Legend: IP-Address _____ | Nr. | (These Numbers describe |_____| the start-up order of the instances.) \______\ Parameter string Video stream direction: --------- > --------- Firewall: » » » » » }}} === Trouble Shooting === Currently there are some limitations that are work in progress: * connection problems, especially when running multiple instances on the same machine (sometimes it can help just to try it again) * mobility does not always work if you change networks * currently only TCP support, we will provide UDP streaming soon * if the modules are not loaded in VLC, make sure you have set the {{{LD_LIBRARY_PATH}}} correctly to the ariba libraries * sometimes sockets are kept open, try to use a different local port == Developer Guide == The ''Developer Guide'' describes how to compile VLC and the AribaMC plugin, and how to insert the plugin's code into an existing VLC code. === Compile Ariba & MCPO === In order to compile the AribaMC plugin, you have to install ''Ariba'' and ''MCPO'' first. By following the instructions below, you compile and install them to {{{$HOME/local}}} in your home-directory. Further information are provided on the official Ariba-Installation page (http://ariba-underlay.org/wiki/BaseInstall). On ''ubuntu 10.04 / 10.10'' the following packages are necessary: * build-essential * libtool * autoconf * automake * libgmp3-dev * liblog4cxx10-dev * libboost-thread-dev * libboost-system-dev * libboost-regex-dev {{{ sudo apt-get install build-essential libtool autoconf automake libgmp3-dev liblog4cxx10-dev libboost-thread-dev libboost-system-dev libboost-regex-dev }}} Get the Ariba and MCPO sourcecode from the [https://projekte.tm.uka.de/trac/spovnet-base/downloads download section] or anonymous SVN [https://i72projekte.tm.kit.edu/SpoVNet-KA/entwicklung/ariba/trunk here for Ariba] and [https://i72projekte.tm.kit.edu/SpoVNet-KA/entwicklung/mcpo/trunk here for MCPO]. {{{ * in the "ariba"-directory do: ./bootstrap ./configure --prefix=$HOME/local make install * get the MCPO sourcecode * in the "mcpo"-directory do: ./bootstrap ./configure --prefix=$HOME/local LDFLAGS=-L$HOME/local/lib CPPFLAGS=-I$HOME/local/include make install }}} === Getting the plugin code === We provide two source code packages, containing either a modified vlc-1.0.6 or vlc-1.1.5 including the AribaMC sender code, the receive code and the gui modifications. If you want to compile a vlc-1.0.6 (same version as in the ubuntu 10.04 repository) or a vlc-1.1.5 (suitable for ubuntu 10.10, and at the time we wrote this, the newest version available) you can continue reading the ''compile the modified VLC'' section. The following instructions help to insert the plugin code into an existing vlc source (e.g. from a different version than 1.0.6 / 1.1.5): ==== Input and Output Modules ==== * Get the vlc source code you intend to modify. * Insert the following folders from "our" source code: * vlc/modules/access/aribamc * vlc/modules/access_output/aribamc * Activate the new folders by adjusting the following files. (You can make a {{{diff}}} with our version of these files to see the changes.): * vlc/configure.ac * vlc/access/Modules.am * vlc/access_output/Modules.am Note: The file {{{vlc/modules/access_output/aribamc/mcpo.c}}} is based on {{{vlc/modules/access_output/udp.c}}}. You might to consider this, if you work on this code. ==== GUI support ==== For AribaMC-Gui support please adjust the following files. You can see the changes by making a {{{diff}}} between our version of these files and the original ones. * vlc/modules/gui/qt4/dialogs/sout.cpp * vlc/modules/gui/qt4/components/open_panels.cpp * vlc/modules/gui/qt4/components/open_panels.hpp * vlc/modules/gui/qt4/components/sout/sout_widgets.cpp * vlc/modules/gui/qt4/components/sout/sout_widgets.hpp ==== Logging Level ==== The logging level within the ariba module is adjustable. e.g.: {{{ * on vlc/modules/access/aribamc/McpoModule.cpp edit line 24 from: logger->setLevel(log4cxx::Level::getInfo()); to: logger->setLevel(log4cxx::Level::getWarn()); * Equally on vlc/modules/access_output/aribamc/McpoModule.cpp line 30. }}} === Compile the modified VLC === Before you start, please install the vlc build-dependencies. On Ubuntu you can get all the dependencies via: {{{ sudo apt-get build-dep vlc }}} Then prepare the code by running {{{ ./bootstrap }}} and {{{ ./configure }}} with suitable parameters. If you have a version of VLC already installed, you can get it's configure parameters via: {{{ vlc --version --verbose=2 }}} We recommend the following configure line (for ubuntu and vlc-1.0.6):[[BR]] ''export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/local''[[BR]] ''./configure --prefix="$HOME/local" '--build=i486-linux-gnu' '--disable-update-check' '--enable-fast-install' '--enable-release' '--with-binary-version=1ubuntu1.1' '--disable-atmo' '--disable-fluidsynth' '--disable-gnomevfs' '--disable-kate' '--disable-mtp' '--enable-x264' '--disable-zvbi' '--enable-a52' '--enable-aa' '--enable-bonjour' '--enable-caca' '--enable-dca' '--enable-dvb' '--enable-dvbpsi' '--enable-dvdnav' '--enable-faad' '--enable-flac' '--enable-freetype' '--enable-fribidi' '--enable-ggi' '--enable-gnutls' '--enable-jack' '--enable-libass' '--enable-libmpeg2' '--enable-lirc' '--enable-live555' '--enable-mad' '--enable-mkv' '--enable-mod' '--disable-mozilla' '--enable-mpc' '--enable-ncurses' '--enable-notify' '--enable-ogg' '--enable-pulse' '--enable-qt4' '--enable-realrtsp' '--enable-sdl' '--enable-shout' '--enable-skins2' '--enable-smb' '--enable-speex' '--enable-svg' '--enable-taglib' '--enable-telx' '--enable-theora' '--enable-twolame' '--enable-vcd' '--enable-vcdx' '--enable-vorbis' '--enable-alsa' '--enable-pvr' '--enable-v4l' '--enable-v4l2' '--enable-svgalib' 'build_alias=i486-linux-gnu' 'CFLAGS=-I${HOME}/local/include -g -O2' 'LDFLAGS=-L${HOME}/local/lib -Wl,--as-needed' 'CPPFLAGS=-I${HOME}/local/include' 'CXXFLAGS=-g -O2' LIBS="-L${HOME}/local/lib -lariba -lmcpo"'' Having the code successfully configured, compile VLC via: {{{ make }}} and install it via: {{{ make install }}} For further instructions about compiling VLC please have at look at: http://wiki.videolan.org/UnixCompile '''Note! ''' Compiling on Ubuntu requires the specification of the "--prefix" option. For a system wide installation use "--prefix=/usr"