= Ariba VLC Plugin - Overlay-based Videostreaming using Ariba and MCPO Application Layer Multicast = NOTE! This text is currently under development. Please do not rely on completeness or even correctness of the following content. == User Guide == === What is the VLC-MCPO plugin? === The vlc-mcpo 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. Through vlc-mcpo you can deliver video streams to groups of users, similar to IP Multicast, but without the need of in-network support. Through the use of Ariba, vlc-mcpo can handle protocol issues such as IPv4/IPv6 transitions, Network Address Translation (NAT), and many more network issues through a self-organizing overlay. For more information about Ariba, MCPO, or the SpoVNet project, please refer to: http://www.ariba-underlay.org , http://www.spovnet.de === Setting up / installing === The ariba framework is currently only available for Linux and therefor the plugin is linux-only at the moment. A quick and simple way for testing but also using the plugin are the precompiled libraries. 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 will be provided in the Developers Guide below. For running the vlc-mcpo plugin a number of packages have to be installed: {{{ 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 sudo apt-get install libdb4.7 }}} Please download the tar-ball containing the required libraries: 32bit linux: [ coming soon ] 64bit linux: [ coming soon ] Unpack the archive to {{{$HOME}}}. (If you choose another location, you have to adjust the path in the running script.) Now you can link the running-script to {{{$HOME/bin}}} or {{{/usr/bin}}} via: [[BR]] {{{ cd $HOME/bin ln -s $HOME/vlc-mcpo/run.sh vlc-mcpo }}} Or just run from where it is. (Note: If you just created the {{{$HOME/bin}}} folder, you have to start a new bash.) (Note: The following instructions assume you created one of links described above.) === A first test: === Now it's time for a first simple test. Run two instances of the modified vlc-players:[[BR]] {{{ LANG=en_US.UTF-8 vlc-mcpo & LANG=en_US.UTF-8 vlc-mcpo & }}} (Note: {{{LANG=en_US.UTF-8}}} sets the language of these two vlc-instances on English for easier following the instructions below.) Two vlc-windows should open, let's 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: »MCPO« (Note: If you can only see protocols like: HTTP, HTTPS, UDP, etc but no MCPO then the plugin wasn't load 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] * Continuing on [S], click: Media > Streaming... [[BR]] * Add a video file. (For a first test we recommend the test-video [coming soon], or at least a video you're successfully able to stream via UDP. Just eliminate sources of error not connected to the vlc-mcpo plugin.) [[BR]] * Press »Stream«. [[BR]] * Press »Next«. [[BR]] * Choose »MCPO« 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 mcpo-vlc plugin and some usage scenarios which demonstrate the strength of the mcpo approach. Mcpo-vlc 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 mcpo-vlc plugin takes three connection parameters. {{{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. ==== Creating a SpoVNet ==== At first we need an initial SpoVNet, consisting of a single mcpo-vlc 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 === == Developer Guide == NOTE! This guide consits only of keywords at the moment. It will be elaborated in future. === compile ariba & mcpo === (see http://ariba-underlay.org/wiki/BaseInstall) === adjusting vlc source code === - get the vlc source code - insert the following folders (download from here): -- vlc/modules/access/mcpo -- vlc/modules/access_output/mcpo - adjust the following files (refer to the diffs): -- vlc/configure.ac -- vlc/access/Modules.am -- vlc/access_output/Modules.am === compile the modified VLC === At first you need the build dependencies. On Ubuntu you can get all the dependencies via: sudo apt-get build-dep vlc After that run {{{./bootstrap}}} and {{{./configure}}} with suitable parameters.[[BR]] On an Ubuntu system with VLC already installed, you can get it's configure parameters via: {{{vlc --version --verbose=2}}} We recommend the following configure line:[[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-dv' '--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" }}} After you configured successfully, 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