Troubleshooting Guide

Capacity & Performance

API key quotas

A developer API key supports up to 500 Minutes of running time and 25 parallel sessions. The running-time quota limits the total duration of sessions using the API key, while the parallel-session limit controls how many sessions can run simultaneously. To increase these quotas, contact our support team.

Participant scaling guidelines

Eyeson supports large participant counts, while video layout capacity depends on the number of video sources:

• Video sources: For optimal video performance, use fewer than 10 simultaneous video sources. Additional video sources can be displayed in custom layouts, but smaller tiles may reduce video clarity at standard HD resolution.
• Audio-only participants: Participants can join with audio_only, which does not require a video spot and therefore does not affect the video layout.
• Total participants: The number of participants is not limited by the number of available video spots. A large number of participants can join as long as they do not all require simultaneous video.

Video Codecs

Eyeson supports multiple video codecs to accommodate different deployment and compatibility requirements. If you require a specific codec or have additional codec requirements, contact our support team.

• VP9 (primary MCU output)
• VP8 (legacy device fallback)
• AV1 (edge deployments)
• H.264, H.265 (on request)

info

Eyeson preserves the original codec when forwarding playback streams to external systems.

Authorization & Access

Authorization header format

Unlike many APIs, Eyeson does not use the Bearer prefix. Include the API key directly in the Authorization header:

curl -X POST \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"user\": {\"name\": \"John Doe\"}, \"options\": {\"sfu_mode\": \"disabled\", \"widescreen\": true}}" \
  "https://api.eyeson.team/rooms"

Invalid or expired access keys

Get the access_key by creating a room with the API key. Remember:

• Unlike many APIs, some of Eyeson features can be managed without an API key, when an access key exists.
• Access keys are bound to specific user instances
• An access key expires when the session ends

Distinguishing guest users

• Guest tokens are only valid for the meeting they're generated for!
• Guest tokens are exchanged for an access_key upon first use
• Guest users include "guest": true in their user profile. Use this flag to enforce role-based feature restrictions:

{
  "id": "user123",
  "name": "Guest User",
  "guest": true
}

Participant history in user lists

The /users endpoint returns a complete participant history, which includes users who have since disconnected. Query the online parameter to filter for active participants:

curl -X GET "https://api.eyeson.team/rooms/$ACCESS_KEY/users?online=true"

Or, to retrieve only disconnected participants:

curl -X GET "https://api.eyeson.team/rooms/$ACCESS_KEY/users?online=false"

Initial Meeting Configuration

Options configured when a room is created establish the initial behavior and capabilities of the session. They define the baseline configuration for participants, media handling, and other room-level features, some of which can be updated later during the session.

Recommended configuration options

The default parameters are optimised for the prebuild-UI. For development environments, the following configuration is recommended:

Option	Default	Recommended	Purpose
sfu_mode	auto	disabled	Enable MCU+ features such as layout and layers
widescreen	false	true	Use a 16:9 aspect ratio
exit_url	null	string	Redirect to the specified page when the session ends
voice_activation	false	true	Auto-adjust the layout based on speaker activity
recording_available	true	false	Enable recording feature
broadcast_available	true	false	Enable streaming feature
reaction_available	true	false	Enable GIF reaction ingestion feature
suggest_guest_names	true	false	Suggest random names when guests join

Enabling MCU+ features

To leverage advanced features like dynamic layouts and visual layers, explicitly disable SFU mode when creating the room:

-d "options[sfu_mode]=disabled"

info

By default, Eyeson only activates MCU mode when a second participant joins. For development and testing with single-user scenarios, you must explicitly set sfu_mode=disabled to enable layout and layer functionality.

Resolution configuration

Eyeson delivers the video stream in two resolutions:

Format	Aspect Ratio	Dimensions	Best For
standard	4:3	1280 × 960 px	Document-heavy sessions, portrait layouts
widescreen	16:9	1280 × 720 px	General use, streaming platforms (Recommended)

caution

Most Eyeson tools and demos are designed for widescreen video. Using the standard format may therefore require additional layout adjustments.

Dynamic Layouts & Visual Composition

Layout updates not taking effect

Layout changes require three preconditions:

1. Correct access credential: Use access_key, not the API Key or Room ID
2. User positioning data: Include at least one users[]= and map= parameter to register the update
3. MCU mode enabled: SFU mode must be disabled at room creation (options[sfu_mode]=disabled)

Layout request formating

As mentioned above, Eyeson delivers optimal performance with fewer than 10 simultaneous video sources, so layouts are typically designed for a limited number of video spots.

When using a custom layout, the number of entries in users[] must match the number of positions defined in map. Each user is assigned to the corresponding position in the map by index. For example, the following layout defines three users and three video positions:

curl -X POST \
  -d "layout=custom" \
  -d "name=custom-map" \
  -d "users[]=$USER_ID1" \
  -d "users[]=$USER_ID2" \
  -d "users[]=$USER_ID3" \
  -d "map=[
    [20, 80, 400, 400, \"auto\"],
    [440, 160, 400, 400, \"contain\"],
    [860, 240, 400, 400, \"cover\"]
  ]" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layout"

Slot filling behavior

Mode	Empty Positions	Outcome
auto	Dynamic	Automatically populated by active participants
custom	Static	Remains empty, when the assigned user_id is not connected

Display name truncation

Names are automatically reduced to initials when the containing position has a width less than 250 pixels.

Visual layers fail to render

Verify all of the following conditions are met:

1. Image URL is publicly accessible or use local files
2. MCU mode is active: layers require MCU+, so verify sfu_mode=disabled at room creation
3. Overlay image dimensions must not exceed the stream resolution (oversized images return 400 BAD REQUEST)
4. Layer positioning: use z-index=-1 for backgrounds, z-index=1 for overlays

Example public URL request:

curl -X POST \
  -d "url=https://example.com/overlay.png" \
  -d "z-index=1" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layers"

caution

The overlay image format should support transparency.

Example local file request:

curl -X POST \
  -F "file=@path/to/local/background.jpg" \
  -F "z-index=-1" \
  "https://api.eyeson.team/rooms/$ACCESS_KEY/layers"

Speaker-activated layout adjustment

When voice_activation=true, participants outside the current layout automatically reposition when they vocalize. If all slots are filled, the least recently active participant is replaced by the new speaker.

For this feature to work:

1. Layout has to be layout=auto
2. The number of users should be higher than the number of video spots
3. The user has to have an active camera0

Recording Lifecycle

Recording progresses through three states:

Stage	Duration Field	Download Link	Description
start	null	null	Recording session initiated
stop	populated	null	Recording paused (intermediate state)
finish	populated	available	Processing complete, ready for retrieval

tip

Large recordings require additional processing time. Monitor state transitions via the Meeting Observer webhook for recording_update events.

Architecture: Eyeson vs. Others

Feature comparison matrix

Capability	Eyeson	SFU-based platforms
Core architecture	MCU+ (server-side composition)	Selective Forwarding Unit
Layout management	Managed and synchronized server-side	Typically managed independently by each client
Visual composition	Native server-side layer support	Client-side or through additional integrations
Per-user bandwidth	~1.5 Mbps (constant)	1–8+ Mbps (variable)
Recording codec	WebM with VP8, VP9, or AV1	Commonly MP4, depending on the platform
Broadcast endpoints	RTMP, RTSP and WHIP	Commonly RTMP and HLS, depending on the platform

Architectural implications

Eyeson's MCU+ architecture composes media server-side before distribution:

• Single stream: Clients receive one composed stream, reducing bandwidth and processing requirements.
• Synchronized layouts: Layout changes are applied server-side and synchronized across clients.
• Native composition: Overlays, logos, and backgrounds are composed directly into the output.
• Simpler clients: Applications primarily display the composed stream.

SFU-based architecture forwards individual media streams to clients:

• Multiple streams: Clients receive and process multiple streams as required.
• Client-side layouts: Applications control stream arrangement and presentation.
• Custom composition: Overlays and visual elements typically require client-side implementation.
• Distributed logic: Consistent presentation must be implemented across client applications.