Skip to main content

How to Share Window Snapshots

An image source adds a still image to a running Eyeson session as its own video spot, next to the participants. If you upload a new snapshot of an application window every few seconds, that spot becomes a low frame rate view of the window. This works for a dashboard, a map or a document, and the participant who shares it never has to switch their camera.

In this tutorial you build a single browser page that captures a window with the Screen Capture API, turns each frame into a JPEG, PNG or WEBP on a canvas, sends it to the image_sources endpoint and removes the spot again when you stop.

info

Send the same image_source_id with every request. Eyeson then replaces the image in the existing spot instead of adding a new spot for every snapshot in the layout.

Step 1. Set up​

The page runs entirely in the browser and talks to the Eyeson REST API directly, so you need no backend and no SDK. The image source endpoints authenticate with a participant's access key in the URL, which means no API key ever reaches the browser. Get the tools and values below ready before you write any capture code, because the browser only grants window capture under specific conditions.

You need the following.

  • A running session and its access_key. You get both when you start a session with POST /rooms. The same response contains links.gui, which you use in Step 3 to watch the result.
  • A desktop browser that supports getDisplayMedia. The Screen Capture API is only available in a secure context, so serve the page over HTTPS or from localhost.
  • A static web server for local testing. Any server that serves the folder on localhost works.

Create index.html with a preview <video>, a hidden canvas and two buttons. The video shows the captured window, and the canvas renders the snapshot you upload.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Window snapshots to Eyeson</title>
</head>
<body>
<button id="startBtn">Pick window and start</button>
<button id="stopBtn" disabled>Stop and remove</button>
<p id="status">Idle</p>
<video id="preview" autoplay muted playsinline style="max-width: 100%"></video>

<canvas id="frame" hidden></canvas>

<script src="app.js"></script>
</body>
</html>

Then start app.js with the configuration. Every snippet in Step 2 and Step 3 goes into this file.

const CONFIG = {
apiBase: 'https://api.eyeson.team',
accessKey: 'YOUR_ACCESS_KEY',
name: 'Shared window',
imageSourceId: `window-${Date.now()}`,
intervalMs: 2000,
format: 'image/jpeg', // JPEG, PNG or WEBP
quality: 0.8, // 0 to 1, used for JPEG and WEBP only
maxWidth: 1280,
objectFit: 'contain', // auto, cover or contain
};

const $ = (id) => document.getElementById(id);
const endpoint = `${CONFIG.apiBase}/rooms/${encodeURIComponent(CONFIG.accessKey)}/image_sources`;

The values work as defaults. intervalMs and maxWidth decide most of the bandwidth. A 1280 pixel JPEG every 2 seconds is a reasonable start for text-heavy windows, and you can raise the interval for content that rarely changes.

Step 2. Capture window​

navigator.mediaDevices.getDisplayMedia() opens the browser's picker and returns a MediaStream of the window the participant chooses. The browser only allows the call from an event handler such as a click, which is why it runs from the start button in Step 3. Nothing is sent to Eyeson in this step. It only produces image blobs that the next step uploads.

Start capture​

Request video only and suggest a window as the surface. Five frames per second is plenty, because you snapshot far less often. When the participant ends sharing through the browser's own controls, the track fires ended, and the handler calls stop() from Step 3 so the spot is removed as well.

let stream = null;

const startCapture = async () => {
stream = await navigator.mediaDevices.getDisplayMedia({
video: { displaySurface: 'window', frameRate: 5 },
audio: false,
});
stream.getVideoTracks()[0].addEventListener('ended', () => stop());

const video = $('preview');
video.srcObject = stream;
await video.play().catch(() => {});
return video;
};

If the participant cancels the picker, the promise rejects with a NotAllowedError. Step 3 catches it and leaves the page idle.

Snapshot to blob​

Draw the current video frame onto the frame canvas, scaled down to maxWidth, and export it with canvas.toBlob(). The toBlob quality argument applies to lossy formats (JPEG and WEBP). PNG ignores it and produces much larger files for screen content with photos or gradients.

const captureBlob = (video) => new Promise((resolve, reject) => {
const canvas = $('frame');
const scale = Math.min(1, CONFIG.maxWidth / video.videoWidth);
canvas.width = Math.round(video.videoWidth * scale);
canvas.height = Math.round(video.videoHeight * scale);
canvas.getContext('2d').drawImage(video, 0, 0, canvas.width, canvas.height);
canvas.toBlob(
(blob) => (blob ? resolve(blob) : reject(new Error('toBlob failed'))),
CONFIG.format,
CONFIG.quality,
);
});

Step 3. Send to Eyeson​

Each snapshot from Step 2 goes to Eyeson as a multipart upload with POST /rooms/{ACCESS_KEY}/image_sources, and stopping sends DELETE /rooms/{ACCESS_KEY}/image_sources/{IMAGE_SOURCE_ID}. Both requests use only the access key from Step 1. The snippets below upload, run the loop, remove the spot and wire up the buttons, and together with the earlier snippets they complete app.js.

Upload snapshot​

Build a FormData with the blob in file and send it. Do not set a Content-Type header yourself, because the browser has to add the multipart boundary to it (MDN on FormData). Because image_source_id stays the same on every call, the first upload creates the spot and every later upload replaces its image.

const upload = async (blob) => {
const ext = { 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/png': 'png' }[blob.type] || 'jpg';
const form = new FormData();
form.append('file', blob, `snapshot.${ext}`);
form.append('image_source_id', CONFIG.imageSourceId);
form.append('name', CONFIG.name);
form.append('object_fit', CONFIG.objectFit);

const res = await fetch(endpoint, { method: 'POST', body: form });
if (!res.ok) {
throw new Error(`HTTP ${res.status}: ${await res.text()}`);
}
};

A successful upload returns 201 Created with no response body.

ParameterTypeRequiredDefaultDescription
filefile (binary)yes, unless url is setnoneThe image. PNG, JPG / JPEG, WEBP or SVG
image_source_idstringno, recommendednoneYour own ID. An existing ID updates that image source instead of creating a new one. It can also be referenced in a layout to pin the image to a spot
object_fitstringnoautoauto, cover (fills the spot, may crop) or contain (fits completely, keeps the aspect ratio). A layout that sets its own fitting for the spot overrides it
namestringnononeReadable name shown in the video spot

The endpoint also accepts a public url with a refresh_interval instead of file. That variant is ignored here, because the snapshots exist only in the browser.

Run the loop​

tick() takes one snapshot and uploads it, and start() runs it on a timer. The busy flag makes sure a slow upload never overlaps the next one. Without it, uploads queue up on a slow connection and can arrive out of order. After an error the loop keeps running, so the next tick simply tries again.

let timer = null;
let busy = false;
let uploads = 0;

const tick = async () => {
const video = $('preview');
if (busy || !video.videoWidth) return;
busy = true;
try {
const blob = await captureBlob(video);
await upload(blob);
uploads++;
$('status').textContent = `Live: ${uploads} uploads, last ${Math.round(blob.size / 1024)} KB`;
} catch (err) {
console.error(err);
$('status').textContent = `Upload error: ${err.message}`;
} finally {
busy = false;
}
};

const start = async () => {
try {
await startCapture();
} catch (err) {
$('status').textContent = `Capture cancelled: ${err.message}`;
return;
}
$('startBtn').disabled = true;
$('stopBtn').disabled = false;
uploads = 0;
await tick();
timer = setInterval(tick, Math.max(500, CONFIG.intervalMs));
};

Remove on stop​

Stopping ends the capture and deletes the image source, so the spot disappears from the session. A successful delete returns 200 OK. The beforeunload handler covers a closed tab. It sends the same delete with keepalive: true, which tells the browser not to abort the request when the page unloads.

const stop = async () => {
clearInterval(timer);
timer = null;
if (stream) {
stream.getTracks().forEach((track) => track.stop());
stream = null;
}
$('preview').srcObject = null;
$('startBtn').disabled = false;
$('stopBtn').disabled = true;

try {
const res = await fetch(`${endpoint}/${encodeURIComponent(CONFIG.imageSourceId)}`, { method: 'DELETE' });
$('status').textContent = `Removed image source: HTTP ${res.status}`;
} catch (err) {
$('status').textContent = `Remove failed: ${err.message}`;
}
};

$('startBtn').addEventListener('click', start);
$('stopBtn').addEventListener('click', stop);

window.addEventListener('beforeunload', () => {
if (timer) {
fetch(`${endpoint}/${encodeURIComponent(CONFIG.imageSourceId)}`, { method: 'DELETE', keepalive: true });
}
});

Verify result​

Run the page and the session side by side to confirm the whole flow. Open links.gui from the start-session response in one tab and your page in another. Then click Pick window and start and choose a window.

  1. A new spot with the name from CONFIG.name appears in the session.
  2. Change something in the shared window. The spot follows within one interval, and the status line counts the uploads.
  3. Click Stop and remove. The status shows HTTP 200 and the spot disappears.
success

You now share a live view of any application window into an Eyeson session from the browser, with one image source that updates in place and cleans up after itself.

Handle errors​

Upload errors appear in the status line and in the browser console as HTTP <status>: <body>. The loop keeps running after an error, so a temporary problem fixes itself on the next tick. A persistent error repeats on every tick. Stop the page and check the cause below.

StatusCauseFix
400 Bad RequestBoth file and url are sent, or neither isSend exactly one of them
404 Not FoundThe access key is wrong, or the DELETE uses an image_source_id that does not existCheck CONFIG.accessKey and CONFIG.imageSourceId
410 GoneThe session has endedStart a new session and use its access key
415 Unsupported Media TypeThe image format is not PNG, JPG / JPEG, WEBP or SVGUse image/jpeg, image/webp or image/png in CONFIG.format

Next Steps​

The page from this tutorial works as a standalone tool, and you can extend it in a few directions. Pinning the image source to a fixed spot keeps it in place while participants join and leave. The reference pages below cover the full parameter set, including URL-based images that Eyeson refreshes on its own.