WebRTC
Аудио, видео и данные между пирами в реальном времени: браузерный API WebRTC — RTCPeerConnection,
MediaStream, MediaStreamTrack, RTCDataChannel, mediaDevices.getUserMedia() — плюс картинка
трека: UIRTCVideoNode, бокс в раскладке экрана (плитки звонка), и RTCVideoView, трек на весь
экран с твоими контролами поверх. Код, написанный под браузер, читается здесь так же. Опционален
по хосту — проверяй RTCPeerConnection.supported / mediaDevices.supported, прежде чем
предлагать звонки, и UIRTCVideoNode.supported, прежде чем рисовать трек на экране (iOS, Android и
Web Lite).
Это плагин приложения: перечисли его в app.json — "plugins": { "webrtc": "*" }. На iOS и
Android он работает поверх libwebrtc (библиотека Google, в оболочке: ~8 МБ), в вебе (Web Lite и
веб-плеер) — поверх собственного стека браузера, в безопасном контексте (https или localhost). Нет
на десктопе и в headless (lecodes render) — там supported равен false.
Сигналинг — забота приложения. Плагин не несёт ни комнаты, ни звонка, ни сервера: приложение
отправляет описания и кандидатов другой стороне по своему каналу (WebSocket к своему бэкенду) и
скармливает соединению то, что приходит в ответ. STUN-сервер проводит большинство пиров; для
остальных нужен TURN-сервер (coturn) — передай оба в iceServers.
Обзор
Звонок 1:1 по браузерному паттерну «perfect negotiation», поверх сигнального канала приложения:
const signal = new WebSocket("wss://signal.example.com/ws")
const send = (msg: object) => signal.send(JSON.stringify(msg))
const pc = new RTCPeerConnection({ iceServers: [{ urls: "stun:stun.l.google.com:19302" }] })
const local = await mediaDevices.getUserMedia({ audio: true, video: { facingMode: "user" } })
for (const track of local.getTracks()) await pc.addTrack(track, local)
const mine = UIRTCVideoNode({ track: local.getVideoTracks()[0], mirror: true }) // твоя камера, плитка
.style({ position: "absolute", right: 16, bottom: 16, width: 120, height: 160, borderRadius: 12 })
const theirs = UIRTCVideoNode().style({ flex: 1 }) // другая сторона, всё остальное
pc.ontrack = (e) => { if (e.track.kind === "video") theirs.track = e.track }
pc.onnegotiationneeded = async () => {
await pc.setLocalDescription() // оффер
send({ type: "description", description: pc.localDescription })
}
pc.onicecandidate = (e) => send({ type: "candidate", candidate: e.candidate })
// сообщения по одному: кандидата нельзя добавлять, пока описание ещё устанавливается
let chain = Promise.resolve()
signal.addEventListener("message", (text) => { chain = chain.then(() => handle(JSON.parse(text))) })
const handle = async (msg) => {
if (msg.type === "description") {
await pc.setRemoteDescription(msg.description)
if (msg.description.type === "offer") {
await pc.setLocalDescription() // ответ
send({ type: "description", description: pc.localDescription })
}
} else if (msg.type === "candidate") {
await pc.addIceCandidate(msg.candidate)
}
}
UIScreen(theirs, mine).open()
// … позже
pc.close()
for (const track of local.getTracks()) track.stop()API
То, что есть в браузере, с отличиями, которые вносит объект на стороне хоста (ниже).
// устройства — navigator.mediaDevices браузера
mediaDevices.supported: boolean
mediaDevices.getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStream>
// { audio?: boolean | AudioConstraints, video?: boolean | VideoConstraints }
// VideoConstraints: { deviceId?, facingMode?: "user" | "environment", width?, height?, frameRate? }
// отклоняется с "denied" / "notFound" / "failed"
mediaDevices.enumerateDevices(): Promise<DeviceInfo[]> // { deviceId, kind, label, facing? }
mediaDevices.setAudioOutput("earpiece" | "speaker"): Promise<void> // маршрут звука телефона; в вебе ничего не делает
mediaDevices.ondevicechange / addEventListener("devicechange", …)
// трек
track.id, track.kind, track.label, track.readyState ("live" | "ended"), track.muted
track.enabled = false // тишина / чёрные кадры; остаётся во всех соединениях
track.stop() // отпускает устройство
track.applyConstraints({ facingMode: "environment" }) // другая камера; трек и его отправители остаются
track.getSettings(): Promise<TrackSettings> // промис: знает хост
track.onended / onmute / onunmute
// поток: группа треков
new MediaStream(tracks?)
stream.id, stream.active, getTracks(), getAudioTracks(), getVideoTracks(), getTrackById(), addTrack(), removeTrack()
// соединение
RTCPeerConnection.supported: boolean
new RTCPeerConnection(configuration?) // { iceServers, iceTransportPolicy, bundlePolicy, iceCandidatePoolSize }
pc.createOffer(options?) / createAnswer(): Promise<RTCSessionDescription>
pc.setLocalDescription(description?) // без аргумента — неявная форма: ответ на ожидающий оффер, иначе оффер
pc.setRemoteDescription(description)
pc.addIceCandidate(candidate | null) // null / пустой = конец удалённых кандидатов
pc.localDescription, remoteDescription, signalingState, iceGatheringState, iceConnectionState, connectionState
pc.restartIce(), getConfiguration(), setConfiguration(c)
pc.addTrack(track, ...streams): Promise<RTCRtpSender> // промис: отправителя создаёт хост
pc.removeTrack(sender): Promise<void>
pc.addTransceiver(trackOrKind, { direction?, streams?, sendEncodings? }): Promise<RTCRtpTransceiver>
pc.getTransceivers() / getSenders() / getReceivers() // копия SDK, синхронизируется после каждого описания и на каждом треке
pc.getStats(track?): Promise<Map<string, any>> // RTCStatsReport: id → { type, timestamp, … }
pc.createDataChannel(label, init?): RTCDataChannel
pc.close()
pc.onnegotiationneeded / onicecandidate / ontrack / ondatachannel / on…statechange
sender.track, sender.replaceTrack(track | null), sender.getParameters() (a promise), sender.setParameters({ encodings })
transceiver.mid, direction (settable), currentDirection, sender, receiver, stop()
// канал данных
channel.label, ordered, protocol, negotiated, id, readyState, binaryType ("arraybuffer")
channel.send(string | ArrayBuffer | ArrayBufferView) // пока хост его не создал — ставится в очередь
channel.getBufferedAmount(): Promise<number> // промис — свойства bufferedAmount нет
channel.bufferedAmountLowThreshold
channel.close()
channel.onopen / onmessage (e.data: string | ArrayBuffer) / onclose / onerror / onbufferedamountlow
// картинка на экране — узел раскладки, размер задают его стили (iOS, Android, Web Lite)
UIRTCVideoNode.supported: boolean
UIRTCVideoNode({ track?, objectFit?: "cover" | "contain", mirror? }): UIRTCVideoNode
node.track = track | null // вживую: переключает картинку; null = чёрный
node.objectFit = "contain"; node.mirror = true // вживую
node.onResize(({ width, height }) => …) // первый кадр и каждое изменение размера картинки
// картинка на весь экран — destination (NativeView): Router.push(view) / view.open(), виджеты поверх
RTCVideoView.supported: boolean
RTCVideoView({ track?, objectFit?: "cover" | "contain", mirror? }): RTCVideoView
view.track = track | null // меняется в любой момент
view.objectFit, view.mirror
view.on("resize", ({ width, height }) => …)Картинка: UIRTCVideoNode, RTCVideoView
Трек, нарисованный как часть экрана, — другая сторона на весь экран, твоя камера в плитке в углу, —
это UIRTCVideoNode: узел раскладки экрана, бокс среди его детей, как UIImage, с картинкой
внутри. Трек, который заполняет экран с контролами поверх, — полноэкранный вид одного участника, —
это RTCVideoView, открытый как destination; у узла нет open, onBack и widgets.
// app.json: "plugins": { "webrtc": "*" }
const local = await mediaDevices.getUserMedia({ video: { facingMode: "user" } })
const size = UIText("")
const me = UIRTCVideoNode({ track: local.getVideoTracks()[0], mirror: true }) // фронтальная камера, зеркально
.style({ width: 200, height: 200, borderRadius: 16 })
.onResize(({ width, height }) => { size.text = `${width} × ${height}` }) // размер картинки, как она показана
UIScreen(UIRTCVideoNode.supported ? me : UIText("No video here"), size)
.style({ pt: "safe-top", p: 16, gap: 12 }).open()- Размещается, как любой элемент: дай ему размер или
flex: 1в колонке; где картинки нет, он чёрный, аborderRadiusего скругляет (узел обрезает содержимое:overflow: "hidden"у него по умолчанию). Сам он ничего не измеряет: для бокса в форме картинки ставьaspectRatioизonResize. track,objectFitиmirrorработают вживую; геттер отвечает то, что записали последним.
в вебе (Web Lite) узел — это <video> трека в своём боксе, та же картинка, что и у
полноэкранного RTCVideoView: objectFit — это CSS object-fit, mirror — CSS-отражение,
onResize — собственные события размера видео. В веб-плеере, на десктопе и в headless-тестах узел —
пустой бокс своего размера, а UIRTCVideoNode.supported равен false (создание узла там один раз
выдаёт предупреждение). RTCVideoView никогда не бывает частью экрана: переданный экрану дочерним
элементом, он попадает в отчёт и пропускается — картинка на экране — это UIRTCVideoNode.
Чем отличается от браузера
Объекты живут в хосте, и вызов уходит к нему, поэтому то, на что браузер отвечает из своей памяти,
здесь — промис, когда надо спросить хост: addTrack, addTransceiver, track.getSettings(),
sender.getParameters(), channel.getBufferedAmount(). getTransceivers() отвечает сразу из
копии SDK, которая обновляется после каждого установленного описания и на каждом событии track —
в те моменты, когда меняются mid и направления. Канал данных возвращается сразу, в состоянии
"connecting"; то, что отправлено до того, как хост его создал, ставится в очередь. События приходят
простыми объектами с type и target — и в обработчики on<type>, и в addEventListener.
MediaStream — это группировка, а его id — метка на проводе: в вебе браузер даёт отправляемому
потоку собственный id, поэтому между пирами сравнивай треки, а не id потоков.
Группы, SFU
Провод — это peer connection, а не звонок: сетка соединений 1:1 обслуживает небольшую группу
(примерно до четырёх); дальше нужен SFU, и его клиент (mediasoup-client, клиент LiveKit) работает в
бандле приложения поверх этих объектов — addTransceiver с sendEncodings — это simulcast,
который просит SFU, а getStats — то, чем он измеряет.
Смотрите также
- Service — сырой канал, на котором стоят типизированные обёртки.
- NativeView — что такое
RTCVideoView: destination.