Blog

WebRTC in Python: cosa fa Python in una videochiamata

· Andrij Tkachenko · 8 min di lettura

Un server segnato dal logo di Python tra due finestre del browser, ognuna con una persona in video, unite da linee tratteggiate, con un fotogramma di pellicola che passa lungo una di esse

Python partecipa a una chiamata WebRTC in uno di due modi. Il più delle volte è il server dietro la chiamata: passa le offerte e gli indirizzi di rete tra due browser e decide chi può chiamare chi, mentre i browser portano l’immagine e il suono. Meno spesso è un peer a sé, con la libreria aiortc, e invia e riceve video e audio da un processo Python, per registrare una chiamata, farci entrare un bot o lavorare su ogni immagine.

Questo articolo mostra entrambi i casi, ognuno come un breve programma provato con Chromium, spiega dove serve l’uno e dove l’altro, e poi mostra come un’app Django, FastAPI o Flask aggiunge chiamate tra i suoi utenti senza nessuno dei due.

I due ruoli di Python in una chiamata

Ruolo Chi porta i media Cosa serve
Server di signaling I due browser Una libreria websocket
Peer nella chiamata Python stesso aiortc

Nel primo caso Python non vede mai nemmeno un’immagine. La chiamata va da browser a browser, e Python li aiuta solo a trovarsi. È ciò che serve a una videochat tra gli utenti di un’app web, ed è lo stesso in qualunque linguaggio sia scritto il server (come WebRTC collega due browser mostra per intero il lato del browser).

Nel secondo caso Python è un capo della chiamata. Risponde all’offerta di un browser, decodifica ciò che arriva e codifica ciò che invia. Serve ai programmi che hanno bisogno dei media stessi.

Python come server di signaling

Prima che passi qualsiasi immagine, due browser devono scambiarsi un’offerta, una risposta e un elenco di indirizzi a cui ognuno potrebbe essere raggiunto, chiamati candidati. WebRTC lascia all’app il modo in cui si raggiungono (lo dice RFC 9429, che descrive l’API del browser). Il server di signaling più piccolo passa ogni messaggio da un browser all’altro. Con il pacchetto websockets (pip install websockets):

signaling.py
import asyncio
from websockets.asyncio.server import serve

clients = set()

async def relay(websocket):
    clients.add(websocket)
    try:
        async for message in websocket:
            # Lo passa a tutti gli altri connessi: qui, all’altra persona.
            for other in clients - {websocket}:
                await other.send(message)
    finally:
        clients.discard(websocket)

async def main():
    async with serve(relay, "localhost", 8080) as server:
        await server.serve_forever()

asyncio.run(main())

Non sa nulla di chiamate e si limita a inoltrare testo. L’abbiamo provato con la pagina del nostro articolo sulle videochiamate in JavaScript, senza cambiarla, in due schede di Chromium con fotocamere finte, in entrambi gli ordini, e ogni scheda mostrava l’altra. Al resto pensa la pagina: apre la fotocamera, fa l’offerta e risponde, e stabilisce quale lato cede quando entrambi fanno un’offerta insieme.

Ciò che aggiunge un’app vera è lo stesso su qualsiasi stack. Il relay qui sopra passa qualsiasi messaggio a chiunque, quindi uno vero controlla chi ha effettuato l’accesso e se può chiamare quella persona. La persona chiamata deve sentire lo squillo in ogni scheda che ha aperto, e per questo serve una connessione tenuta aperta per ogni utente (i websocket in Python spiega perché Django e Flask su WSGI non possono tenerne una). E le chiamate dietro firewall rigidi hanno bisogno di un relay TURN (i server STUN e TURN, spiegati).

Python come peer, con aiortc

aiortc implementa WebRTC in Python su asyncio, con un’API che segue quella del browser, con le coroutine al posto delle promise. Il suo README elenca l’audio in Opus, PCMU e PCMA, il video in VP8 e H.264, e i data channel, provati con Chrome e Firefox. La versione 1.16 richiede Python 3.11 o successivo.

Il programma qui sotto risponde a un browser e gli rimanda subito il suo video, dopo che Python ha ricevuto ogni immagine. Usa aiohttp per l’unica richiesta di cui lo scambio ha bisogno (pip install aiortc aiohttp):

peer.py
import asyncio
from aiohttp import web
from aiortc import RTCPeerConnection, RTCSessionDescription, MediaStreamTrack

peers = set()

class Mirror(MediaStreamTrack):
    """Rimanda indietro ogni immagine che riceve, dopo che Python l’ha vista."""
    kind = "video"

    def __init__(self, source):
        super().__init__()
        self.source = source

    async def recv(self):
        frame = await self.source.recv()   # un av.VideoFrame, decodificato
        # frame.to_ndarray(format="bgr24") dà i pixel, per NumPy o OpenCV.
        return frame

async def offer(request):
    params = await request.json()
    pc = RTCPeerConnection()
    peers.add(pc)

    @pc.on("track")
    def on_track(track):
        if track.kind == "video":
            pc.addTrack(Mirror(track))

    @pc.on("connectionstatechange")
    async def on_state():
        if pc.connectionState in ("failed", "closed"):
            await pc.close()
            peers.discard(pc)

    await pc.setRemoteDescription(RTCSessionDescription(sdp=params["sdp"], type=params["type"]))
    await pc.setLocalDescription(await pc.createAnswer())   # prima raccoglie tutti i candidati
    return web.json_response({"sdp": pc.localDescription.sdp, "type": pc.localDescription.type})

async def close_all(app):
    await asyncio.gather(*(pc.close() for pc in peers))

app = web.Application()
app.router.add_post("/offer", offer)
app.router.add_static("/", "static")
app.on_shutdown.append(close_all)
web.run_app(app, host="localhost", port=8081)

La pagina va in static/index.html, con due elementi video e lo script:

HTML
<video id="me" autoplay playsinline muted></video>
<video id="back" autoplay playsinline></video>
<script type="module" src="/mirror.js"></script>
static/mirror.js
const local = await navigator.mediaDevices.getUserMedia({ video: true });
document.getElementById('me').srcObject = local;

const pc = new RTCPeerConnection();
pc.addTrack(local.getVideoTracks()[0], local);
pc.ontrack = ({ track }) => {
  document.getElementById('back').srcObject = new MediaStream([track]);
};

// Il lato Python accetta un’offerta sola con tutti i candidati dentro, quindi aspettali tutti.
await pc.setLocalDescription(await pc.createOffer());
await new Promise((resolve) => {
  if (pc.iceGatheringState === 'complete') return resolve();
  pc.addEventListener('icegatheringstatechange', () => {
    if (pc.iceGatheringState === 'complete') resolve();
  });
});

const response = await fetch('/offer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(pc.localDescription),
});
await pc.setRemoteDescription(await response.json());

Esegui python peer.py e apri http://localhost:8081/index.html. Il browser chiede la fotocamera, e pochi secondi dopo il secondo video mostra il primo, di ritorno da Python. L’abbiamo provato in Chromium con una fotocamera finta: l’immagine tornava larga 640 pixel e continuava ad arrivare.

Tre cose lo distinguono da una chiamata tra due browser:

  1. Una sola richiesta è tutto lo scambio. Il browser aspetta di avere tutti i candidati e li invia nella sua offerta. aiortc raccoglie i propri candidati in setLocalDescription() e li mette nella sua risposta, quindi non serve nessun websocket e basta una semplice POST.
  2. La traccia è una classe. Ogni immagine passa per recv(), che ne attende una dal browser e ne restituisce una da inviare. In mezzo va il tuo codice: leggere i pixel, disegnarci sopra, conservarli o inviare qualcos’altro.
  3. Python decodifica e codifica. Ogni immagine che passa viene decodificata e codificata di nuovo sulla CPU. Va bene per poche chiamate alla volta, ed è il motivo per cui un media server che inoltra il video a molte persone non lo decodifica affatto (come funzionano le videochiamate di gruppo).

Perché la fotocamera si apra, la pagina deve essere su localhost o in HTTPS. Su un tuo server, al lato Python serve anche un server STUN, e un server TURN per chi sta dietro reti rigide, indicati in RTCConfiguration(iceServers=[...]). Se una chiamata non si collega, perché una connessione WebRTC non riesce passa in rassegna cosa controllare.

Quale dei due ti serve

  • I tuoi utenti si chiamano tra loro. Python è il server di signaling, oppure lo lascia a un servizio. I browser portano la chiamata, e Python decide chi può chiamare chi.
  • Un programma entra nella chiamata. Un registratore, un bot che ascolta e risponde, una fotocamera su un piccolo dispositivo, un test che avvia una chiamata da uno script. Qui aiortc fa di Python un peer, e lo fai girare su server tuoi.

La maggior parte delle app web ha bisogno del primo, e il lavoro sta meno nel relay che in ciò che gli sta intorno: lo squillo in ogni scheda, i relay, la riconnessione quando un telefono cambia rete, e le chiamate di gruppo oltre le quattro persone. È la parte che può portare un servizio, lasciando alla tua app l’unica decisione che la riguarda davvero.

Chiamate in Django, FastAPI e Flask con WordPlus Cloud

Con il pacchetto wordplus-realtime, un’app Python avvia chiamate tra i suoi utenti senza un server di signaling, un relay o una schermata di chiamata da scrivere, e senza nulla che Python debba decodificare. La tua app decide chi può chiamare in una sua view, che risponde con un token per la chiamata. In Django:

Python
# shop/views.py, su path("call-token", views.call_token): GET /call-token?to=34&type=video
from django.http import HttpResponse, JsonResponse
from wordplus_realtime.django import realtime

def call_token(request):
    # Qui va il tuo controllo: chi può chiamare chi.
    if not request.user.is_authenticated:
        return HttpResponse(status=401)
    return JsonResponse({
        "token": realtime.call_token(request.user.pk, request.GET["to"], type=request.GET.get("type")),
    })

La pagina avvia la schermata di chiamata e mette un pulsante dove le persone chiamano, che chiede il token alla tua view:

JavaScript
await rt.callScreen(); // lo squillo e la finestra di chiamata, su ogni pagina dove una chiamata può squillare
HTML
<call-button to="34" token-url="/call-token" type="video" name="Ann">Call Ann</call-button>

La chiamata squilla in ogni scheda e su ogni dispositivo che Ann ha aperto. Va direttamente tra i due browser quando le loro reti lo consentono, attraverso i nostri relay sulle porte 443 e 80 quando non lo consentono, e attraverso i nostri media server quando nemmeno i relay arrivano, passando dall’uno all’altro senza riagganciare. Le chiamate tra due persone sono cifrate end-to-end su ogni percorso, e le chiamate di gruppo girano sugli stessi server. Senza un token dalla tua view non parte nulla, quindi nessuno può aggirarla.

Le pagine sulle chiamate della nostra documentazione mostrano il resto per Django, FastAPI e Flask: chi può chiamare, le chiamate di gruppo e un’interfaccia di chiamata tutta tua.

Videochiamate per la tua app Python

WordPlus Cloud for Apps ha un prezzo in base alle connessioni simultanee, a partire da 1.000, con fatturazione mensile o annuale, e le chiamate tra due persone non consumano crediti su nessun percorso. Scopri videochiamate e chiamate di gruppo per le app, oppure i prezzi per le app. Domande sulla tua integrazione? Scrivici.