Publisher Video Constraints — Web

Once you have initialized a Publisher, you can control the preferred resolution and frame rate of the outgoing video track. This lets you optimize bandwidth and CPU usage for different UI sizes (thumbnails, tiles, full screen) and subscriber devices.

This topic includes the following sections:

Understanding publisher video constraints

The Publisher can advertise a preferred resolution and frame rate for its video track: the SDK applies constraints to the capture device and outbound track. Subscribers benefit from lower bandwidth and CPU when the publisher sets smaller sizes or lower frame rates for small UI targets. Note that delivered quality can be further adjusted by device capabilities and network conditions.

Setting the preferred resolution

Call publisher.setPreferredResolution(preferredResolution) to set the preferred pixel dimensions:

await publisher.setPreferredResolution({ width: 640, height: 360 });
  • preferredResolution is an object: { width: number, height: number }.
  • The preferred resolution must not exceed the initial publishing resolution.
  • Only applies when the Publisher is capturing video (publishVideo: true).

Throws an error if:

  • The Publisher is audio-only.
  • width or height is not a positive integer.
  • The requested resolution exceeds the initial publishing resolution.
try {
  // If the initial publish was 640x480, this will throw:
  await publisher.setPreferredResolution({ width: 1920, height: 1080 });
} catch (error) {
  console.error('Failed to set preferred resolution:', error.message);
}

Setting the preferred frame rate

Call publisher.setPreferredFrameRate(frameRate) to set a preferred frames-per-second value:

await publisher.setPreferredFrameRate(15);
  • frameRate must be a positive integer (≥ 1).
  • Requires an active video track.

Throws an error if:

  • The Publisher is audio-only.
  • frameRate is not a valid integer ≥ 1.

How constraints affect delivery

Preferred constraints influence the outbound video track for all subscribers to the stream. However, the final delivered resolution and frame rate may be lower due to:

  • Capture device limitations
  • Browser or OS limitations
  • Network conditions and adaptive media decisions

Best practices

  • If you know the ideal resolution and frame rate in advance, set them when creating the Publisher using OT.initPublisher() (for example via resolution and frameRate). For subscribers, you can omit these settings or use preferredResolution: 'auto' when calling Session.subscribe().
  • Use the Subscriber APIs (subscriber.setPreferredResolution() / subscriber.setPreferredFrameRate()) to change how a single subscriber receives/decodes/renders a stream. This only affects that subscriber, and does not change what the Publisher sends or what other subscribers receive.
  • Use the Publisher APIs (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) to change what the Publisher sends. This affects all subscribers to that stream, which will automatically receive the updated settings. You may want to reduce the publisher resolution using the preferredResolution method in several cases, such as:
    • When you notice that the publisher device is struggling, whether due to CPU limitations or network issues, and you want to alleviate the strain more quickly than the WebRTC stack typically would.
    • If the device is running low on battery and you want to minimize power consumption to extend the call duration.
    • When you initiate screen sharing or start additional publishers from the same device and need to free up computational resources for those activities.
  • Publisher preferred resolution/frame rate can never exceed the values specified when initializing the Publisher. Initialize the Publisher with the maximum resolution and frame rate you might need, then reduce or increase dynamically within those limits based on your use case.
  • Use appropriate frame rates:
    • 5 fps — static dashboards, slides, bandwidth-sensitive UI
    • 15 fps — low-motion content
    • 30 fps — full-motion/high-quality video
  • Network conditions may prevent the SDK from maintaining your preferred resolution and frame rate. Treat preferred values as targets: if bandwidth or CPU becomes constrained, the SDK may automatically reduce the published/subscribed video quality (for example, a 1080p preference may temporarily drop to a lower resolution during poor network conditions).
  • These APIs are currently supported only in the JavaScript SDK.

Examples

// Lower quality for mobile users
if (isMobileUser) {
  publisher.setPreferredResolution({ width: 320, height: 180 });
  publisher.setPreferredFrameRate(15);
}

// Higher quality for desktop
if (isDesktopUser) {
  publisher.setPreferredResolution({ width: 1280, height: 720 });
  publisher.setPreferredFrameRate(30);
}

// Error when using resolution above initial publish
try {
  await publisher.setPreferredResolution({ width: 1920, height: 1080 }); // If initial was 640x480, throws error
} catch (error) {
  console.error(error.message);
}

// Debugging: Current track settings
const videoTrack = publisher.getVideoSource().track;
const { width, height, frameRate } = videoTrack.getSettings();
console.log('Current resolution:', width, 'x', height);
console.log('Current frame rate:', frameRate);

Troubleshooting

Handling errors

Wrap calls in try/catch and surface user-friendly messages when constraints are invalid or the environment cannot satisfy them.

async function setPublisherQuality(publisher, preferredResolution, preferredFrameRate) {
  try {
    await publisher.setPreferredResolution(preferredResolution);
    await publisher.setPreferredFrameRate(preferredFrameRate);
  } catch (err) {
    showMessage('Unable to apply video constraints. Check your device and network.');
    console.error(err);
  }
}

Network considerations

If the network is constrained, the media pipeline may lower the delivered resolution or frame rate regardless of preferred settings. Consider implementing UI indicators for reduced quality modes.

Additional resources