Live streams in Django
One person presents live to everyone watching: the picture, a chat beside it, reactions, and the count of who watches. The host goes live from the browser, a phone or OBS, and brings viewers on stage beside them. Viewers may be signed in or not.
How a stream starts, runs and ends is in how it works, and live streaming builds one from an empty folder, and gives its rule in Python too.

Who is who
Each stream has a name, as a room has: show:mugs is the show of the mugs, one name for each show of your shop. A page that opens a stream asks your server first, through the calls route of the package, and a rule of yours answers who the user is in it. WordPlus Cloud then holds the page to the answer. The rule goes beside your rooms and calls, in shop/realtime.py, and decides:
- A show of your shop opens: any other name is refused.
- A visitor who is not signed in watches and reads the chat, and signs in to write.
- The presenter of the show hosts: goes live, brings viewers on stage and keeps the chat.
- Your staff keep the chat beside the host.
- Everyone else watches, writes in the chat, and may raise a hand to come on stage.
Its settings take guests on stage and reactions, and links in the chat only from those who keep it.
# shop/realtime.py
from django.contrib.auth import get_user_model
from wordplus_realtime.django import realtime
from .models import Show
def show_role(user, p):
# 1. A show of your shop: any other name is refused.
show = Show.objects.filter(slug=p["slug"]).first()
if show is None:
return False
# 2. A visitor watches and reads the chat, and signs in to write.
if user is None:
return {"role": "viewer", "chat": "read"}
# 3. Its presenter hosts: goes live, brings viewers on stage and keeps the chat.
if user == show.presenter_id:
return "host"
# 4. Your staff keep the chat beside the host.
if get_user_model().objects.filter(pk=user, is_staff=True).exists():
return {"role": "viewer", "mod": True}
# 5. Everyone else watches, writes, and may raise a hand to come on stage.
return "viewer"
# Guests on stage, reactions, and links in the chat only from those who keep it.
realtime.streams("show:{slug}", show_role, stage=True, reactions=True, chat={"links": False})
useris an id, not a model, and None for a visitor. The rule queries your models the usual way.- The answer:
False,"host"or"viewer", or a dict for more:role,info(what others see of them, their name from your user model by default),chat(writeorread),mod(keeps the chat),srcandquality(what the host sends:camera,microphone,screen, and720por1080p). - A visitor who is not signed in may only be a viewer: a rule that gives them more is refused with
no_user. With"chat": "read", the player offers them Log in to chat, to the page itslogin-urlnames. - The settings of the stream, keyword arguments, are each a value or a function of the parts of its name:
stage(guests on stage, on unlessFalse),reactions,people(who sees who is watching:mods, the default, orall) andchat:offline(the chatopenorclosedwhile the stream is not live),links(from everyone, or only from those who keep the chat) andfresh(the chat emptied each time it goes live) (live streams in depth).
The calls route (/api/realtime/calls) is already among the routes of the package, for streams too.
Your server hears each stream go live and end by webhook: stream.live and stream.ended, with its name in stream, and started_at and ended_at in milliseconds.
The page
Optional, as every ready-made part: a screen of your own below draws the stream with no element.
The stream drawn ready: its player with the chat beside it, and the studio where the host goes live.
{# shop/templates/shop/show.html #}
<live-stream name="show:{{ show.slug }}" title="{{ show.title }}" login-url="{% url 'login' %}"></live-stream>
await rt.streamScreen(); // loads its script, realtime-ui-streams.min.js, once
- The host sees the studio in it: the camera and microphone, the picture before going live, a shared screen, OBS, the guests, Go live and End stream. Everyone else sees the player, how many watch, and the chat.
- Guests on stage: while live, a viewer who is signed in raises a hand from the player, and the host invites them from the studio to come on with their camera and microphone (guests on stage).
- Its parts apart, each where the page wants it:
view="player",chat(withheight="480"),detailsorstudio, and<stream-studio name="show:mugs">for the studio alone. The parts of one stream share one join, wherever they are. - A studio page of its own for the host:
view="studio-page"on a page of yours, withurl(where viewers watch) andback-url, andstudio-urlon the page viewers watch, which then shows the host the way there in place of the studio (the studio as a page of its own). - Its attributes:
title,cover,url(the page to share),login-url(where a visitor signs in to chat),studio-url,back-url,chat="off", andsticky(the player kept at the top of a phone while live). - Its words follow the language of the page, its
<html lang>: English, German, Spanish, French, Italian, Dutch, Polish, Croatian and Hebrew. - A refusal shows its words in place of the stream, such as no access (refusals).
- Its script comes from the routes with the others, and loads with the first stream on a page.
The show card of the API demo is this element, in showCard() of its page.
A screen of your own
The same stream on markup of your own, with calls.stream():
const calls = await rt.calls();
const show = await calls.stream( 'show:mugs' );
show.watch( document.querySelector( '#show video' ) ); // the picture and its sound
show.on( 'state', ( state ) => draw( state ) ); // idle, live, ended
show.on( 'viewers', ( n ) => ( count.textContent = `${ n } watching` ) );
show.on( 'message', ( m ) => addLine( m.from.name, m.text ) );
await show.chat.send( 'Hello!' );
show.react( '❤️' ); // any one emoji
The page of the host goes live with the camera and ends it:
if ( show.role === 'host' ) {
await show.preview(); // the camera and microphone, shown in the same video
await show.goLive(); // everyone watching sees it now
// …
await show.end();
}
- The picture follows the stream as it changes: a shared screen, the picture from OBS, else the camera of the host. The
videostaysmuted, and the sound plays from the page. - The host sends what they turn on:
setCamera(),setMicrophone()andsetScreenShare().goLive()with nothing on turns the camera and microphone on first. show.snapshot()is everything the screen draws, andshow.subscribe( fn )hears each change (live streams in depth).
Guests on stage
A viewer raises a hand, the host invites them, and they come on stage beside the host with their camera and microphone, for everyone watching: a question from the audience, an interview, a panel. The host may invite anyone signed in who watches, hand raised or not.
The page of a viewer:
raiseButton.onclick = () => show.hand( true ); // show.hand( false ) takes it down
show.on( 'invited', () => offerToJoin() ); // the host asks them on
joinButton.onclick = () => show.joinStage(); // on stage, their camera and microphone live
leaveButton.onclick = () => show.leaveStage();
show.on( 'stage', ( on ) => showOnStage( on ) ); // whether this page is on stage now
The page of the host:
show.on( 'hands', ( hands ) => drawHands( hands ) ); // [ { user, name, at } ], the oldest first
await show.invite( hands[ 0 ].user ); // or anyone watching, by their user id
await show.unstage( 34 ); // off stage, back to watching
await show.layout( 'speaker' ); // 'grid', 'speaker', or 'spotlight' with a user id
- A guest is a viewer on stage: everyone watching sees them in the picture of the stream, by the layout the host chose, and
show.tileshas each of them withrole: 'guest'. - A guest sends their camera and microphone, the picture up to 720p.
- A visitor who is not signed in watches, and does not come on stage.
- The stage is on unless the settings of the stream say
stage=False, as for a show where nobody but the host appears. - The ready-made player does all of it: Ask to join on stage for a viewer, the hands in the studio with Invite beside each, and the guests with a way to take them off (interviews and questions on stage).
Keeping the chat
The host, and anyone the rule made mod, keep the chat. In the ready-made player, each message has a menu for them: pin it over the chat, delete it, mute its writer for a minute, 10 minutes, an hour or a day, remove them from the stream, or ban them. The chat settings hold slow mode and Clear the chat, and Who is here lists the signed-in people watching, with the same menu, and those banned, with Let back.
On a screen of your own:
await show.chat.delete( id );
await show.chat.pin( id ); // chat.unpin() takes it down
await show.chat.timeout( user, 600 ); // no writing for 10 minutes, a minute to a day: they go on watching
await show.chat.slow( 30 ); // one message per 30 seconds each, 0 turns it off
await show.chat.clear(); // every message, the pinned one too
await show.kick( user ); // out now: they may come back
await show.ban( user ); // out, and kept out
useris the id your rule named them by, andshow.snapshot().you.modsays whether this page keeps the chat.- A host is never put out, banned or timed out.
- Your server keeps the chat too, with no page open (from your server): a ban lifted, a timeout lifted, or the stream ended.
From OBS
A host may stream from OBS, or any encoder that sends over WHIP, in place of the camera: a studio camera, a mixed scene, a game. The studio of the ready-made player has it as Stream from OBS, with the settings that suit a stream, such as a keyframe every second. On a screen of your own:
const { url, key } = await show.ingest(); // ingest( true ) makes a new key and cuts off the old one
- In OBS, Settings, Stream: Service WHIP, Server the
url, and Bearer Token thekey. - Start Streaming in OBS. Its picture shows in the studio, in place of the camera.
- Go live from the studio, or with
show.goLive(). Everyone watching sees the picture from OBS.
Only the host gets the key. Keep it as a password: anyone with it streams to the show.
The sound
A browser plays sound only once the person has clicked or typed on the page, or on the page of your site they came from. A viewer who opens the stream from a link in a new tab sees the picture without its sound, and the ready-made player shows Turn sound on over it: the sound starts at that click.
On a screen of your own, the snapshot says so in audioBlocked, and startAudio() from a click turns it on:
show.on( 'change', ( state ) => ( soundButton.hidden = ! state.audioBlocked ) );
soundButton.onclick = () => show.startAudio();
From your server
Your server reads a stream and keeps its chat as its moderators do, with no page open. Each change reaches everyone watching at once:
realtime.list_streams() # [{"name", "started_at", "viewers"}], those live now
show = realtime.stream("show:mugs")
show.get() # {"state", "viewers", "peak", "slow", "reactions", "pinned"}
show.people() # {"watching", "people": [{"user", "name", "role", "timeout_until"?}]}
show.chat(limit=50) # the last messages, oldest first, up to 200
show.say("Free shipping until midnight", "Mug Shop", "https://shop.example/logo.png")
show.delete_message(message_id) # clear_chat() empties it
show.pin(message_id) # None unpins
show.slow(30) # one message per 30 seconds each, up to 300, 0 turns it off
show.timeout(user, 600) # untimeout(user) lifts it
show.kick(user) # out now, they may come back
show.ban(user) # unban(user) lifts it, bans() lists them
show.reactions(False)
show.end()
A button of your staff page posts to a view of yours, which checks who asks, then speaks in the chat and pins it:
# shop/views.py
from django.contrib.admin.views.decorators import staff_member_required
from django.http import JsonResponse
from django.shortcuts import get_object_or_404
from django.views.decorators.http import require_POST
from wordplus_realtime.django import realtime
from .models import Show
@require_POST
@staff_member_required
def announce(request, slug):
show = get_object_or_404(Show, slug=slug)
stream = realtime.stream(f"show:{show.slug}")
message = stream.say(request.POST["text"], "Mug Shop", "https://shop.example/logo.png")
stream.pin(message["id"])
return JsonResponse({"ok": True})
- A message from your app shows as a host message, with the name and https picture you give it, up to 500 characters, and nobody may ban it.
useris the id your rule named them by. A host is never put out or timed out: that raises aRealtimeErrorwith the codehost.- A timeout lasts from a minute to a day, and they go on watching.
people()lists the signed-in people watching or on stage, andwatchingcounts everyone, visitors included.- In an async view, run them off the event loop:
await sync_to_async(show.get)(), fromasgiref.sync.
Charging for what was watched
An app that charges its users by the minute hears each signed-in person watching or presenting, at its webhook:
stream.joined, as they start watching while the stream is live: they opened it live, or it went live with them on it.stream.left, as that ends, withsecondsof live time: they left, or the stream ended.
# shop/realtime.py
import math
# Each viewer pays for the minutes watched live, the host nothing. charge() is yours, once for each id.
def stream_left(e):
if e["role"] == "viewer" and e["seconds"] > 0:
charge(e["id"], e["user"], math.ceil(e["seconds"] / 60))
realtime.on("stream.left", stream_left)
- Only live time counts. A page open before the stream goes live counts from when it goes live. Going live again starts another pair, with the same
watch. - Visitors are not told: someone who did not sign in has nobody to charge.
- Each event has an
id: an event may come again, so charge once for each. roleis the one your rule gave them, so the host pays nothing here.
Your rule letting a viewer in only with a balance, and your server taking out whoever ran out while watching: charging for calls and streams.
Refusals
calls.stream() and each action on the stream reject with a code, and the ready-made player shows its words in place of the stream:
| Code | |
|---|---|
forbidden | Your rule said no, or no pattern matches the name |
no_user | Your rule gave a visitor who is not signed in more than the place of a viewer |
not_included | The plan of your app does not include live streams |
banned | This user is banned from the stream, until unban() lets them back |
no_hours | A new viewer above what your plan includes, while your account has no credits left (below) |
not_host | An action of the host from someone who is not the host |
anonymous | A hand raised by a visitor who is not signed in |
no_stage | A hand or an invitation in a stream whose settings say stage=False |
not_invited | joinStage() with no invitation |
no_encoder | Going live from OBS before its picture came |
read_only, slow, timeout, too_long, links, not_live | A message refused: the chat is read-only for them, it came sooner than slow mode allows, they are timed out, it is over 500 characters, a link from someone who does not keep the chat, or the chat is closed while the stream is not live |
When the credits run out. Viewers above what your plan includes take credits from your account, a credit a minute each (limits). Once the credits of the month, those you bought and what the account may borrow are used, a new viewer above that number is not let in. Everyone watching goes on, the host and the guests come in, and someone signed in who was watching comes back after a reload. Buy credits in your WordPlus Cloud account, or the next month refills them, and new viewers come in again.
What WordPlus Cloud sees
A stream is for everyone watching it, so its picture and its chat are not encrypted end to end. They are encrypted on the way, and the media servers of WordPlus Cloud see them, as a stream needs.
More
- Every method, the snapshot and the events of a stream: live streams in depth, the Python reference and the browser reference.
- How a stream starts, runs and ends: how it works.
- Use cases: live streaming, interviews and questions on stage, members-only streams and charging for calls and streams.