Skip navigation.
Home

Usage

Once PeerStreamer is installed in the system it can be immediately used to broadcast and receive media contents.

There are two main binaries in each distribution:

  • the chunker_streamer;
  • the streamer;

along with some utility scripts and text files, which coordinate the use of the binaries and configure their options.

Basic Usage

The most common scenario involves the scripts player.sh (or peerstreamer.bat for the Windows platforms), for the playout, and source.sh to set-up a streaming source.
All the required binaries and libraries are included in the PeerStreamer installation folder.

The Source

To stream file video contents, a bash-like capable interpreter is required, i.e., for the time being we do not have developed a fully working stream source for windows or MAC. In general users wants to watch an event, so go the the section describing the player unless your goal is setting up a working source. In this case be prepared to have to study a bit video encoding, transcoding and synchronization to understand all parameters involved in the configuration of the system.
Just copy the following files in a folder with write permission granted:

    chunker_streamer
    streamer-ml-monl-chunkstream-static
    source.sh

Running:

 ./source.sh -h 

gives the available streaming options.

A typical launch string is:

 ./source.sh -f ~/video/big_buck_bunny_480p_1Mbps_mpeg4_mp2.ts -V libx264 -A mp2 

(you can find the test video file here)
Obviously the -f option specify the video file path; the -V and -A options indicates the desired encoding for the streamed media.

As default behaviour the streamer takes the IP address of the first available interface (excluding the loopback one).
If you want to specify a different network interface, use the -s to instruct directly the streamer:

 ./source.sh -f ~/video/big_buck_bunny_480p_1Mbps_mpeg4_mp2.ts -V libx264 -A mp2 -s "-I eth2"

Other available streamer options are displayable through:

 ./streamer-ml-monl-chunkstream-static -h 

In order to make the just created channel accessible by other users, the distribution of a configuration file is required.
An example of such a file is given below:

Channel TEST-CHANNEL-01
{
	LaunchString = "-i x.x.x.x -p 6666"
	AudioCodec = mp2
	AudioChannels = 2
	SampleRate = 48000
	VideoCodec = h264
	Width = 854
	Height = 480
	Ratio = 1.7777
	Bitrate = 1000000
}

Here TEST-CHANNEL-01 specify the channel name will be displayed on the PeerStreamer players.
The LaunchString field specify the arguments for the streamer, so x.x.x.x must be replaced with the IP address used by the source.
The flag -p specify the source streamer port (default: 6666). The other parameters have to be set according to the source transcoding settings.

The Player

To run the player just run

 ./player.sh 

on *nix systems or

 ./peerstreamer.bat 

on Windows platforms.

This command will download the default PeerStreamer channel list from the web and will start the player accordingly.

To use a different channel list and being allowed to playout some custom stream, like the one set-up in the previous section,
execute the same script passing as argument the -C flag and the name of the channel list file.

 ./player -C channel.conf 

On some Windows systems the executables must all be run in Windows XP compabitility mode in order to make them work properly.

Advanced Usage

PeerStreamer is a very flexible tool and it's possible to use it many different ways.
Some interensting usage scenarios involves the combination with third-party popular media applications like VLC or MPlayer.

Live Capture Streaming

It's possible to use PeerStreamer for broadcasting live sessions and conferences.
However, since PeerStreamer cannot directly read from video devices, it necessary to combine some tools in order to flawlessy setup the live streaming pipeline.
For our tests we used two USB cameras:
* Logitech QuickCam IM/Connect
* Logitech Webcam C270

The Source

For the source we now make the assumption of working on a *nix system.
The scheme below sketches the streaming pipeline:
/dev/video0 ---> |
                          |---> ffmpeg ---> ./fifo ---> fifo0 ---> source.sh
/dev/hw:0,0 ---> |

The FIFO is needed in order to manage the incoming video stream.
We used version 2.1.1 of ffmpeg with alsa support enabled.
You can obtain it by simply install the development files of libasound2 and execute:

wget http://ffmpeg.org/releases/ffmpeg-2.1.1.tar.bz2
tar xvjf ffmpeg-2.1.1.tar.bz2; cd ffmpeg-2.1.1
./configure --extra-libs=-lasound
make

Since the fifo program is needed, download it from github and compile it:

git clone https://github.com/cskiraly/fifo.git
cd fifo && make

Now it's possible to start streaming!
Following is reported one possible streaming configuration. Obviously, since the large number of transcoding parameters available, a little environment specific tuning might be needed in order to obtain the minimum latency possible at the receiving side and the best performances at the source computation side.

Supposing to have placed all the executables in one folder:

mkfifo fifo0
./ffmpeg -f alsa -i default -f video4linux2  -i /dev/video0 -f nut - | ./fifo > fifo0

And in another shell:

./source.sh -f fifo0 -V libx264 -A mp2

Where /dev/video0 is the choosen video capture device.

The Player

On the player side, all needed is just the channel configuration, like for example:

Channel TEST-CHANNEL-01
{
	LaunchString = "-i source_ip_address -p 6666"
	AudioCodec = mp3
	AudioChannels = 2
	SampleRate = 48000
	VideoCodec = h264
	Width = 854
	Height = 480
	Ratio = 1.7777
	Bitrate = 1000000
}

and then it's possible to execute:

./player.sh -C channel.conf

RTP Bridge

PeerStreamer offers the possibility to inject media contents through udp ports.
That means that it's possible to distribute an RTP stream using the advanced peer-to-peer live technology brought by PeerStreamer.
Moreover, since almost all popular media applications are capable of stream and play-out RTP data,
it's possible to use PeerStreamer as an underlying effiecient transport service and rely on the more familiar desktop programs for the end-user frontends.

In order to use this feature a specific PeerStreamer incarnation is required, so the code must be compiled with:

 make ml

It's worth noting that this kind of usage is still under testing and that is sub-optimal as the RTP-based distribution has not been optimized yet.
Moreover the distribution of the channel information has not been defined.

The Source

On the source side we combine the streaming function of a media application (VLC for the rest of this section)
with PeerStreamer using RTP as communication protocol between them.
The first step is hence the launch of the vlc RTP streamer.
It is possible to use the VLC GUI but the command line is more flexible and gives a greater degree of customization.

For the sake of simplicity it is shown an example with a video file in input,
but feel free to exploit all the input support features of VLC (as the live capture input for example).
In this example the RTP stream is directed to the local instance of PeerStreamer,
so the dst parameter is set to the local address 127.0.0.1.

cvlc ~/video/big_buck_bunny_240p_300Kbps_mpeg2_mp2_cam.ts --sout 
"#transcode{vcodec=h264,venc=x264{keyint=1,intra-refresh,slice=4},
vb=300,fps=25,acodec=mp2,width=240,heigth=320 
}:rtp{dst=127.0.0.1,port=5004,sdp=file://channel.sdp}"

(you can find the test video file here)

For a complete description of the involved parameters please refer to the VLC manual.
It's wort noting that the x264 options intra-refresh and slice=4 (which imply keyint=1) are crucial for the robustness of the PeerStreamer distribution in a lossy network.
The other parameters are mainly referred to the transcoding, so depends on the specific requirements of the desired media.

At this point PeerStreamer can be launched and instructed to conveys all the VLC RTP traffic in a peer-to-peer overlay.

 ./streamer-ml-monl-grapes-static -f null,chunkiser=udp,port0=5004,port1=5005,port2=5006,port3=5007 -P 6000

In the above example PeerStreamer has been instructed to inject in the peers overlay the UDP traffic of the ports 5004, 5005, 5006, and 5007
(as 5004 was the RTP base port of the VLC streaming) and to conveys all the data through the port 6000.

The Player

From the playout point of view, a similar architecture is required.
First a streamer instance must be launched:

 ./streamer-ml-monl-grapes-static -i x.x.x.x -p 6000 -F null,dechunkiser=udp,port0=7004,port1=7005,port2=7006,port3=7007

Obviously, x.x.x.x has to substitued with the real PeerStreamer source IP address.
The ports 7004, 7005, 7006, and 7007 has been choosed for the demultiplexing of the RTP stream.

At this point the stream can be played with every RTP compatible media application:

 vlc rtp://@127.0.0.1:7004

The local address 127.0.0.1 indicates that VLC has to access the PeerStreamer tunneled RTP stream, not the original one.

To avoid autodetection problems it also possible to distribute the sdp file created with the VLC command in the previous section,
modifying the IP address with the local address and the base port with the destination base port (127.0.0.1 and 7004 in the example above).
Then vlc can be launched:

 vlc channel.sdp --sout '#display'