Changes between Version 90 and Version 91 of Documentation/VLC


Ignore:
Timestamp:
Dec 10, 2010, 2:42:33 PM (13 years ago)
Author:
Christoph Mayer
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Documentation/VLC

    v90 v91  
    1 = '''aribamc''' Ariba Overlay Multicast VLC Plugin - Overlay-based Videostreaming using Ariba and MCPO Application-Layer Multicast =
     1= Ariba Overlay Multicast VLC Plugin - Overlay-based Videostreaming using Ariba and MCPO Application-Layer Multicast =
    22
    33[[Image(logotest.png)]]
    44
    5 === What is the plugin? ===
    6 
    7 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. With '''vlc-mcpo''' 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, '''vlc-mcpo''' can cope with several protocol issues such as IPv4/IPv6 transitions, Network Address Translation (NAT), and many more networking problems in a self-organized and distributed manner.
     5=== What is the AribaMC plugin? ===
     6
     7The '''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.
    88
    99For more information about Ariba, MCPO, or the SpoVNet project, please refer to: http://www.ariba-underlay.org , http://www.spovnet.de
    1010
    1111=== Setting up / installing ===
     12
     131.0.6 --> Ubuntu 10.04 LTS
     141.1.4 --> Ubuntu 10.10
     151.1.5 --> aktuelle VLC version, aber nicht std. in Ubuntu
     16
     1732 bit
     1864 bit
     19
     20xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     21
    1222The 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.
    1323
    1424A 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 9.10 or 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.
    1525
    16 For running the vlc-mcpo plugin a number of packages are required on the target system:
     26For running the AribaMC plugin a number of packages are required on the target system. Your might need different boost versions, use what's coming with your distribution. Log4cxx is this version or higher required.
    1727
    1828{{{
    … …  
    273732bit linux: [ coming soon ][[BR]]
    283864bit linux: [ coming soon ]
    29 
    30 Unpack the archive to {{{$HOME}}}. (If you choose another location, you have to adjust the path in the running script.)
    31 
    32 Now you can link the running-script to {{{$HOME/bin}}} or {{{/usr/bin}}} via: [[BR]]
    33 {{{
    34 cd $HOME/bin
    35 ln -s $HOME/vlc-mcpo/run.sh vlc-mcpo
    36 }}}
    37 
    38 Or just run from where it is.
    39 
    40 (Note: If you just created the {{{$HOME/bin}}} folder, you have to start a new bash.)
    41 (Note: The following instructions assume you created one of links described above.)
     39xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     40
     41Unpack the archive to e.g. {{{$HOME}}}. You will find two folders {{{aribalibs}}} and {{{vlclibs}}}. Set the {{{LD_LIBRARY_PATH}}} to aribalibs:
     42{{{
     43set LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/aribalibs
     44}}}
     45and run VLC with
     46{{{
     47vlc --plugin-path=/home/user/vlclibs
     48}}}
    4249
    4350=== A first test: ===
    … …  
    4552Now it's time for a first simple test.
    4653
    47 Run two instances of the modified vlc-players:[[BR]]
    48 {{{
    49 LANG=en_US.UTF-8 vlc-mcpo & LANG=en_US.UTF-8 vlc-mcpo &
    50 }}}
    51 (Note: {{{LANG=en_US.UTF-8}}} sets the language of these two vlc-instances to English for easier following of the instructions below.)
    52 
    53 Two vlc-windows should open, let's call them [S] and [R].
     54Run 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]]
     55
     56To follow the instructions here, you can switch the language to English:
     57{{{
     58LANG=en_US.UTF-8 vlc --plugin-path=/home/user/vlclibs
     59}}}
     60
     61When you now have two vlc-windows let's continue, we'll call them [S] and [R].
    5462
    5563[[Image(VLC_media_player.png)]]
    … …  
    5765 * Receiver side [R]
    5866  * On [R] please click: Media > Open Network Stream... [[BR]]
    59   * Then choose: Protocol: »MCPO« (Note: If you can only see protocols like: HTTP, HTTPS, UDP, etc but no MCPO then the plugin wasn't loaded correctly into your vlc. Please refer to the trouble shooting section in this case.) [[BR]]
     67  * 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]]
    6068  * The address field should now look like this: {{{1234:localhost:5000}}} [[BR]]
    6169  * Press »play«.
    … …  
    6573 * Server side [S]
    6674  * On [S], click: Media > Streaming... [[BR]]
    67   * 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]]
     75  * 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 AribaMC plugin.) [[BR]]
    6876  * Press »Stream«. [[BR]]
    6977  * Press »Next«. [[BR]]
    70   * Choose »MCPO« and press »Add«. [[BR]]
     78  * Choose »AribaMC« our of the list and press »Add«. [[BR]]
    7179  * Now you can see: Source: Port: 5000; Destination: Address: localhost, Port: 1234 [[BR]]
    7280  * Disable transcoding and press »Stream«. [[BR]]
    … …  
    7684
    7785=== Usage ===
    78 In this section we describe the parameters of the mcpo-vlc plugin and some usage scenarios which demonstrate the strength of the mcpo approach.
    79 
    80 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.
     86In this section we describe the parameters of the AribaMC plugin and some usage scenarios which demonstrate the strength of the AribaMC plugin approach.
     87
     88AribaMC 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.
    8189
    8290==== Parameters ====
    8391
    84 The mcpo-vlc plugin takes three connection parameters. {{{SourcePort:DestinationAddress:DestinationPort}}} (e.g. {{{1234:localhost:5000}}})
    85 
    86 The {{{SourcePort}}} provides an entry point for other instances to the SpoVNet our instance is in (or will be in).
    87 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.
    88 
    89 An instance which has not connected to such an entry point makes up a SpoVNet with only itself in it.
     92The AribaMC plugin takes three connection parameters in the GUI:
     93{{{SourcePort:DestinationAddress:DestinationPort}}} (e.g. {{{1234:localhost:5000}}})
     94
     95The {{{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.
     96
     97While 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
     98{{{
     99vlc --plugin-path=/home/user/vlclibs --sout-aribamc-config-file ./config.txt
     100}}}
     101and for the receiver side use
     102{{{
     103vlc --plugin-path=/home/user/vlclibs --config-file ./config.txt
     104}}}
     105
     106The configuration file can hold several parameters, the [wiki:Documentation/Configuration main documentation is here].
     107
     108
     109
     110
     111
     112
     113To view further parameters of the AribaMC plugin do:
     114{{{
     115./vlc -p aribamc
     116}}}
     117
     118which outputs
     119
     120{{{
     121VLC media player 1.0.6 Goldeneye
     122
     123 MCPO input (aribamc)
     124      --caching <integer>        Caching value in ms
     125      --config-file <string>     ariba config file
     126
     127 MCPO stream output (aribamc)
     128      --sout-aribamc-caching <integer>
     129                                 Caching value (ms)
     130      --sout-aribamc-config-file <string>
     131                                 ariba config file
     132}}}
    90133
    91134==== Creating a SpoVNet ====
    92135
    93 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.
     136At 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.
    94137
    95138On the second instance, {{{DestinationAddress}}} and {{{-Port}}} must be set adequate. It can also set the {{{SourcePort}}} to act as an entry point later.
    … …  
    209252
    210253== Developer Guide ==
    211 The ''Developer Guide'' describes how to compile VLC and the vlc-mcpo plugin, and how to insert the plugin's code into an existing VLC code.
     254The ''Developer Guide'' describes how to compile VLC and the AribaMC plugin, and how to insert the plugin's code into an existing VLC code.
    212255
    213256=== Compile Ariba & MCPO ===
    214257
    215 In order to compile the vlc-mcpo 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).
     258In 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).
    216259
    217260On ''ubuntu 9.10 / 10.04'' the following packages are necessary:
    … …  
    247290=== Getting the plugin code ===
    248291
    249 The source code package contains a modified vlc-1.0.6 including the vlc-mcpo 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) you can continue reading the ''compile the modified VLC'' section.
     292The source code package contains a modified vlc-1.0.6 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) you can continue reading the ''compile the modified VLC'' section.
    250293
    251294The following instructions help to insert the plugin code into an existing vlc source (e.g. from a different version than 1.0.6):
    … …  
    254297 * Get the vlc source code you intend to modify.
    255298 * Insert the following folders from "our" source code:
    256    * vlc/modules/access/mcpo
    257    * vlc/modules/access_output/mcpo
     299   * vlc/modules/access/aribamc
     300   * vlc/modules/access_output/aribamc
    258301 * Activate the new folders by adjusting the following files. (You can make a {{diff}}} with our version of these files to see the changes.):
    259302   * vlc/configure.ac
    … …  
    261304   * vlc/access_output/Modules.am
    262305
    263 Note: The file {{{vlc/modules/access_output/mcpo/mcpo.c}}} is based on {{{vlc/modules/access_output/udp.c}}}. You might to consider this, if you work on this code.
     306Note: 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.
    264307
    265308==== GUI support ====
    266 For MCPO-Gui support please adjust the following files. You can see the changes by making a {{{diff}}} between your version of these files and the original ones.
     309For AribaMC-Gui support please adjust the following files. You can see the changes by making a {{{diff}}} between your version of these files and the original ones.
    267310 * vlc/modules/gui/qt4/dialogs/sout.cpp
    268311 * vlc/modules/gui/qt4/components/open_panels.cpp
    … …  
    274317Probably you want to set the ariba logging output to "info":
    275318{{{
    276 * on vlc/modules/access/mcpo/McpoModule.cpp edit line 24
     319* on vlc/modules/access/aribamc/McpoModule.cpp edit line 24
    277320    from:
    278321      logger->setLevel(log4cxx::Level::getWarn());
    … …  
    280323      logger->setLevel(log4cxx::Level::getInfo());
    281324
    282 * Equally on vlc/modules/access_output/mcpo/McpoModule.cpp line 30.
     325* Equally on vlc/modules/access_output/aribamc/McpoModule.cpp line 30.
    283326}}}
    284327