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», поверх сигнального канала приложения:

TypeScript
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

То, что есть в браузере, с отличиями, которые вносит объект на стороне хоста (ниже).

TypeScript
// устройства — 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.

TypeScript
// 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 работают вживую; геттер отвечает то, что записали последним.
Note

в вебе (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.