Introduction

If you stream an AI avatar over WebRTC, the network is part of your product surface. When bandwidth drops, the failure mode is usually ugly: video stutters, audio stays barely alive, lip sync drifts, or the browser keeps a high-quality track alive long after the connection can support it. Bandwidth adaptation is the difference between “works on my Wi‑Fi” and something that stays usable on hotel Wi‑Fi, mobile tethering, or constrained corporate networks.

This post shows how to add bandwidth adaptation to a streaming avatar in React and TypeScript. The goal is not to hand-wave “adaptive bitrate” as a magic checkbox, but to show the practical pieces: monitor the connection, define quality tiers, switch tracks cleanly, and avoid visual pops when the avatar changes resolution or encoding profile. By the end, you should be able to wire up a client-side adaptation loop and decide where the server should cooperate.

Start with the actual failure modes

For a streaming avatar, bandwidth adaptation is usually about three things:

• Video quality selection: lower resolution, lower frame rate, or a cheaper encode when the connection degrades.

• Latency control: keeping motion and lip sync acceptable even if quality drops.

• Graceful fallback: avoiding full teardown unless the connection is genuinely unusable.

The mistake most teams make is treating adaptation as a single threshold, like “if RTT is high, switch to low quality.” In practice, you want a small state machine driven by multiple signals:

• WebRTC stats: packet loss, RTT, available outbound bitrate, jitter, frame drop rate.

• Player behavior: stalled frames, decode time, and whether the remote track is actually rendering.

• User-visible intent: if the avatar is in an active speaking state, preserve audio and lip sync even if video becomes static or lower fidelity.

For avatars, audio continuity is usually more important than video fidelity. If you must trade something away, sacrifice visual detail before you sacrifice speech timing.

Model bandwidth adaptation as a quality ladder

The cleanest implementation is a ladder of quality tiers. Each tier maps to a known streaming configuration: for example, 720p at 30 fps, 480p at 24 fps, 360p at 15 fps, and a low-motion fallback. Your app does not need to “calculate” an infinite set of bitrates; it needs to select from a small set that the server can reliably produce and the browser can reliably decode.

In React, keep the active tier in state, but let the network telemetry drive that state through hysteresis. Hysteresis matters because network stats bounce around. If you switch immediately on every spike, the avatar will thrash between tiers.

A simple rule set looks like this:

1. Sample WebRTC stats every 2–5 seconds.

2. Maintain a rolling average over the last few samples.

3. Downgrade only after sustained poor conditions.

4. Upgrade only after sustained healthy conditions, and use a longer dwell time than you use for downgrades.

That asymmetric behavior prevents oscillation. Users tolerate a temporary downgrade much better than repeated quality flips.

Reading WebRTC health in React and TypeScript

If you are rendering the avatar with a remote media track, the browser already exposes useful telemetry. The exact source depends on your WebRTC stack, but the pattern is the same: obtain sender/receiver stats, extract a few fields, then reduce them into a quality decision.

type QualityTier = "high" | "medium" | "low";

}

type QualityTier = "high" | "medium" | "low";

}

type QualityTier = "high" | "medium" | "low";

}

This is intentionally conservative. In a real app, you would also add dwell timers so a downgrade can happen quickly but an upgrade requires several healthy samples in a row.

For a media element backed by WebRTC, you can poll stats from the active receiver or peer connection. Pseudocode looks like this:

async function sampleStats(pc: RTCPeerConnection): Promise<NetSnapshot | null> {

}

async function sampleStats(pc: RTCPeerConnection): Promise<NetSnapshot | null> {

}

async function sampleStats(pc: RTCPeerConnection): Promise<NetSnapshot | null> {

}

Not every browser exposes every field in every situation, so treat stats as best-effort signals, not hard guarantees. When a field is missing, default conservatively and avoid making large decisions from a single sample.

Apply the tier without tearing down the experience

The key implementation detail is whether a quality change requires a full session restart or just a track renegotiation. A restart is expensive and tends to create visible artifacts. Prefer a design where the avatar stream can switch profiles while the session stays alive.

In React, that usually means separating the avatar session from the player component:

• The session component owns authentication, signaling, and track identity.

• The player component owns rendering and quality selection.

• A controller hook owns telemetry sampling and tier selection.

That separation lets you do one important thing: if the network briefly worsens, downgrade the stream profile but keep the avatar object, voice, and conversation state intact. When conditions improve, upgrade gradually.

One practical trick is to preload the next-lower tier before switching to it. If your implementation can keep more than one profile ready, the user experiences a clean transition instead of a rebuffer event. If you cannot prebuffer, at least align changes with natural conversational pauses.

Keep the React state machine small

Bandwidth adaptation logic gets messy when it leaks into rendering code. Keep it in a dedicated hook. The hook can expose the active tier, the latest network snapshot, and a setter for manual overrides. Manual overrides are useful for debugging and for allowing a support agent to pin a lower quality on purpose.

function useAvatarQuality(pc: RTCPeerConnection | null) {

}

function useAvatarQuality(pc: RTCPeerConnection | null) {

}

function useAvatarQuality(pc: RTCPeerConnection | null) {

}

That code is not production-complete, but it shows the shape. In a real implementation, add:

• Exponential moving averages or rolling windows.

• Cooldowns after tier changes.

• Telemetry logs so you can correlate downgrades with user complaints.

• A safe default when WebRTC stats are unavailable.

If you support multiple browsers, test the adaptation loop on Chrome, Safari, and Firefox separately. The same API shape does not always mean the same field availability or cadence.

Where Protoface fits

This is exactly the kind of problem Protoface is meant to absorb on the avatar side: you keep your application logic in React, while the avatar/session layer gives you a streamed talking face that can be managed through the platform’s developer surfaces. For implementation details, use the public docs and the quickstarts in the repository linked from the docs site.

For example, if you are orchestrating avatar sessions from a backend, you would typically create or manage those sessions through the REST API or the Python SDK, then let the client worry about rendering and adaptation. The exact request and response fields are documented in the docs, but the pattern is straightforward: create the session, attach the avatar, and choose the quality tier that best fits the user’s connection.

import os

print(resp.json())

import os

print(resp.json())

import os

print(resp.json())

If you are using the LiveKit voice-agent path, the livekit-plugins-protoface integration gives you the avatar face inside the agent pipeline, which is useful when your primary problem is “my voice agent needs a synchronized talking head” rather than “I need to hand-roll video signaling.” In that setup, bandwidth adaptation should still happen at the client or session layer, but the plugin keeps the avatar synchronized with the agent’s speech output.

Operational gotchas

A few things are worth calling out because they fail in production more often than in demos:

• Do not key adaptation solely off network type. “Wi‑Fi” can be worse than LTE, and vice versa.

• Do not overreact to a single bad sample. Use windows, not spikes.

• Keep audio and video policies separate. Losing video detail is acceptable; dropping speech frames is not.

• Log the tier transitions. If users complain about “fuzzy avatar” or “laggy face,” you want to know when and why the system changed.

• Make the downgrade visible but not jarring. A simple overlay or subtle placeholder can communicate that quality changed without making the app feel broken.

Also, if your app allows custom instructions or persona changes, make sure quality changes do not reset conversational state. Adaptation should be orthogonal to the content of the interaction.

Conclusion

Bandwidth adaptation for a streaming AI avatar is mostly an engineering discipline, not a media trick. Measure the connection, map it to a small set of known quality tiers, switch conservatively, and keep the session alive while the stream quality changes. If you get those parts right, your avatar remains usable under real network conditions instead of only on a clean lab connection.

For implementation specifics, the docs at docs.protoface.com and the quickstarts in the linked GitHub examples are the right place to fill in the platform details. Start with the smallest loop that can downgrade and recover cleanly, then add observability, manual overrides, and browser-specific testing once the basics are stable.