@magnaboy/whep

Browser WHEP viewer connections without a React dependency. Module imports also work outside a browser; starting a session reports unsupported WebRTC through its snapshot.

import { createHttpWhepTransport, WhepSession } from '@magnaboy/whep';

const session = new WhepSession({
  transport: createHttpWhepTransport('https://media.example/live/whep'),
  rtcConfiguration: { iceServers: [{ urls: 'stun:stun.example:3478' }] },
  iceTimeoutMs: 2000,
  retryDelayMs: 4000,
});
const unsubscribe = session.subscribe(snapshot => {
  video.srcObject = snapshot.stream;
});
session.start();
// On unmount:
unsubscribe();
session.close();

The transport implements the MediaMTX SDP offer/answer profile: receive-only audio/video, bounded ICE gathering, POST SDP, resolve Location, and DELETE the allocated session. It does not implement trickle ICE, ICE restarts, or the counter-offer extension in the WHEP draft. Reconnection creates a fresh session.

WhepTransport lets applications retain authenticated HTTP routes. offer receives an abort signal. It must return the allocated location with the answer, or release that location itself if reading the answer fails. The session releases late answers after cancellation and ignores stale peer events. DELETE is best effort, with an independent five-second timeout in the HTTP transport. Servers still need expiry for allocations whose response never reaches the client.

Defaults: two-second ICE gathering, 25-second connection timeout, no disconnect grace, and no automatic retry. retryDelayMs enables retries after connection/negotiation failures; unsupported browser/setup failures remain errors. disconnectGraceMs permits temporary outages. hasAudioTrack tracks live, unmuted audio; setAudioEnabled controls ducking independently and persists across retries. Autoplay policy remains with the application.

Sessions pause and release resources on pagehide, and reconnect on pageshow. Pass lifecycleTarget: false to manage page lifecycle yourself. close is permanent; restart replaces the current attempt while keeping subscribers.

WhepSessionPool shares connections by key within one caller-owned authentication/configuration context. Each acquisition returns an idempotent release function. The default two-second release grace supports remounts. Restarting a pooled connection keeps all active viewers subscribed. Scope separate pools to different users or credentials.

CX uses a pool retained across hot reloads, four-second retries, Cloudflare STUN, and a 100 ms jitter target. IronStream injects its authenticated media routes, configured ICE servers, a five-second ICE timeout, and three-second disconnect grace. Its UI retains manual retries and missing-audio fallback.

Build this package before installing the consumers' sibling file: dependencies. Run pnpm build, pnpm test:types, and pnpm test:unit to verify the package.

pnpm test:browser runs real Chromium peers with synthetic audio and video on localhost for both consumer profiles. Install the test browser with pnpm exec playwright install chromium if needed. This verifies SDP negotiation, received media, ducking, and teardown without contacting a deployed media server. Production authentication, TURN, and server reachability need the corresponding deployment environment.