P2P LiveFree live streaming · peer-to-peer delivery

Learn

How this system works, and how to set it up — no prior knowledge needed.

How peer-to-peer streaming works

One server, many viewers

Without peer-to-peer, every viewer downloads every second of video from your origin server. Ten viewers means ten times the bandwidth. A thousand viewers means a thousand times.

Video arrives in pieces

An HLS stream is a list of small files, a few seconds each. Because every viewer wants the same files in the same order, a viewer who already has one can give it to a viewer who does not.

Viewers help each other

With peer-to-peer, the first viewer fetches a piece of video from the origin and then passes it to the others directly, browser to browser. The origin sends each piece far fewer times.

One viewer leads

The swarm picks one viewer as leader. The leader stays slightly ahead, fetches from the origin, and feeds the rest. If the leader closes the tab, another takes over in well under a second.

Nothing ever depends on a peer

If a piece does not arrive from another viewer in time, the browser simply fetches it from the origin instead. Peer-to-peer can only make delivery cheaper, never less reliable.

Getting started

You need one thing to begin: the web address of an HLS playlist. It ends in .m3u8 and it must be reachable from the internet. Everything below is about getting such an address, depending on what you have today.

If you already have an HLS address

  1. Log in and open My channel.
  2. Paste the address into HLS stream address (.m3u8). It must begin with http:// or https://.
  3. Give the channel a title, then press Save.
  4. Press Check stream now. Within a few seconds the status becomes ONLINE.
  5. Open your channel page and press play. Then open the same page in a second browser — that is when peer-to-peer starts, because it needs two viewers to have anyone to share with.

If the check says the stream cannot be reached, it is almost always one of two things: the address is not reachable from outside your own network, or the origin does not send the Access-Control-Allow-Origin header. Browsers refuse to play a stream from another server without it.

If your source is RTMP (most encoders, OBS)

Your encoder sends RTMP to a server, and that server writes HLS. Any of nginx-rtmp, MediaMTX, Flussonic or ffmpeg will do it. The minimal ffmpeg version, running on the machine that receives the stream:

ffmpeg -listen 1 -i rtmp://0.0.0.0:1935/live/mystream \
       -c copy -f hls \
       -hls_time 4 -hls_list_size 6 -hls_flags delete_segments+independent_segments \
       /var/www/live/mystream/playlist.m3u8

Serve /var/www/live with any web server, add the CORS header, and use https://yourhost/live/mystream/playlist.m3u8 as the stream address here.

-c copy means the video is not re-encoded, so this costs almost no CPU. Use it whenever your encoder already produces H.264 and AAC, which nearly all of them do.

If your source is SRT

SRT is a contribution transport: it moves a stream between servers reliably, but no browser can play it. Receive it and package it the same way:

ffmpeg -i "srt://0.0.0.0:9000?mode=listener&latency=200" \
       -c copy -f hls \
       -hls_time 4 -hls_list_size 6 -hls_flags delete_segments+independent_segments \
       /var/www/live/mystream/playlist.m3u8

If your source is multicast (UDP or RTP)

This system cannot read a multicast address, and neither can any browser. That is not a missing feature — it is what multicast is. Multicast delivers one copy of a stream to many receivers on a network that is configured to carry it, which is why it works beautifully inside an operator's own network and does not exist on the public internet at all. A browser has no way to join a multicast group.

So multicast is converted once, on a machine inside the network that receives it, and what goes online is the HLS result:

ffmpeg -i "udp://@239.0.0.1:1234?fifo_size=1000000&overrun_nonfatal=1" \
       -c copy -f hls \
       -hls_time 4 -hls_list_size 6 -hls_flags delete_segments+independent_segments \
       /var/www/live/channel1/playlist.m3u8

For RTP, use rtp://@239.0.0.1:1234 instead. If the multicast source is MPEG-2 or another codec browsers cannot play, replace -c copy with real encoding:

-c:v libx264 -preset veryfast -b:v 3000k -g 100 -c:a aac -b:a 128k

One conversion serves any number of viewers, because from that point on the peer-to-peer swarm does the distribution.

If your source is an IP camera (RTSP)

ffmpeg -rtsp_transport tcp -i rtsp://user:password@camera.local/stream1 \
       -c:v libx264 -preset veryfast -g 50 -c:a aac \
       -f hls -hls_time 2 -hls_list_size 5 -hls_flags delete_segments \
       /var/www/live/camera1/playlist.m3u8

The CORS header, once

Whatever produces your HLS, the web server that hands it to viewers must send:

Access-Control-Allow-Origin: *

In nginx:

location /live/ {
    add_header Access-Control-Allow-Origin * always;
    add_header Cache-Control "no-cache" always;
    types { application/vnd.apple.mpegurl m3u8; video/mp2t ts; }
    root /var/www;
}

Without it the stream check reports CORS as missing, and no browser will play the stream — with or without peer-to-peer.

Where your stream comes from

Supported directly

HLS over HTTP or HTTPS

Paste the playlist address into your dashboard. Nothing else is needed.

https://origin.example.com/live/stream/playlist.m3u8

A recorded file

Serve it as HLS over HTTP. Any web server will do.

https://files.example.com/vod/show/playlist.m3u8

Needs converting first

Multicast (UDP or RTP)

Browsers cannot join a multicast group, so this server cannot read one either. Convert it to HLS on your own network first.

udp://@239.0.0.1:1234 → HLS

SRT

A contribution transport. Receive it on a server, package it as HLS, then point this system at that playlist.

srt://host:9000 → HLS

RTMP

Send it to a server that packages HLS, then use that playlist address here.

rtmp://host/app/key → HLS

RTSP (cameras)

Typical of IP cameras. Convert to HLS with ffmpeg or a media server, then use that address.

rtsp://camera/stream → HLS

Why the distinction exists

Everything a viewer plays is fetched by their browser, over HTTP, as a file with a URL. That is the whole basis of the peer-to-peer part: two viewers can only share a piece of video if they can both name it the same way. A URL is that name.

Multicast, SRT, RTMP and RTSP are all transports — they move a stream from one machine to another. None of them produces addressable files, and no browser speaks any of them. That is why they are converted first, and why the conversion happens once rather than per viewer.

Choosing segment length

-hls_time sets how long each piece is. It is the one setting worth thinking about:

  • 2 seconds — lower latency, more requests, less time for a peer to share a piece before it is needed.
  • 4 seconds — a good default, and what the examples above use.
  • 6 seconds or more — highest chance of peer-to-peer working well, at the cost of latency.

Peer-to-peer works better with longer segments, because there is more time for one viewer to pass a piece to another before playback needs it. If you do not have a hard latency requirement, four seconds is a sensible place to start.

Keeping segment URLs stable

Two viewers share a piece of video only when they both request the same URL. If your CDN gives each viewer a different address for the same segment — a per-viewer token, a per-backend hostname — then no two viewers ever recognise a piece as the same piece, and the swarm delivers nothing. The stream check warns about this when it can detect it.

Monitoring your stream

What offload means

Offload is the share of video your viewers delivered to each other. With two or three viewers it is usually small; with dozens it commonly passes half.

On your channel page

The status line under the player tells you what is happening, in plain words: whether peer-to-peer is active, whether you are the only viewer, and whether anything is wrong with playback. If it says the stream cannot be reached, the reason is shown too.

On your dashboard

Check stream now runs the stream check immediately: it fetches your playlist the way a browser would and reports whether it is reachable, whether CORS is set, and what it found inside.

What good looks like

  • Two viewers — peer-to-peer connects, but offload stays low. One viewer has to fetch from the origin for the other to have anything to receive.
  • Ten viewers — offload commonly reaches a third to a half.
  • Dozens of viewers — offload above half is normal, and the origin's traffic stops growing in step with your audience. That is the entire point.

Offload of zero with several viewers watching is worth investigating: it usually means the viewers cannot reach each other, which a TURN relay fixes. Mobile networks are the common case.

If viewers report errors

The administrator's Live analytics page lists errors reported by viewers, per stream, including which HTTP protocol the failing request used. A stream that plays fine from your own machine but fails for viewers elsewhere is usually a CDN or geography problem rather than a fault in the stream, and that column is what tells the two apart.

Glossary

HLS
HTTP Live Streaming. A way of sending video as a playlist of small files that any web browser can fetch over ordinary HTTP.
Playlist (.m3u8)
The text file that lists the pieces of your stream in order. This is the address you paste into your dashboard.
Segment
One small file of video, usually 2 to 6 seconds long. Viewers share these with each other.
Origin
The server your stream really comes from — your encoder, packager or CDN. Peer-to-peer reduces how much it has to send.
Swarm
Everyone watching the same stream at the same time. They exchange segments with each other.
Leader
The viewer the swarm has chosen to fetch from the origin and feed the others.
Peer
Another viewer your browser is connected to directly.
WebRTC
The browser technology that lets two viewers send data to each other without going through a server.
STUN
A small helper service that tells a browser what its own address looks like from the outside, so two viewers can find each other.
TURN
A relay used when two viewers cannot reach each other directly — common on mobile networks. This server can run one itself.
Offload
The share of video delivered by viewers instead of by your origin. Higher is cheaper.
CORS
A rule that lets a web page read files from another server. Your origin must allow it, or browsers will refuse to play the stream.
Multicast
A way of sending one copy of a stream to many receivers on a managed network. Browsers cannot receive it, so it must be converted to HLS first.
SRT
A transport for moving a stream reliably between servers over the public internet. It is a contribution format, not something a browser can play.
RTMP
An older protocol still widely used to send a stream from an encoder to a server. Browsers cannot play it directly.
Transcode
Re-encoding video into another format or quality. Needed when your source is not already something browsers can play.
Package
Cutting an incoming stream into HLS segments and writing the playlist, without necessarily re-encoding the video.