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.
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 withPOST /rooms. The same response containslinks.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 fromlocalhost. - A static web server for local testing. Any server that serves the folder on
localhostworks.
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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file | file (binary) | yes, unless url is set | none | The image. PNG, JPG / JPEG, WEBP or SVG |
image_source_id | string | no, recommended | none | Your 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_fit | string | no | auto | auto, 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 |
name | string | no | none | Readable 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.
- A new spot with the name from
CONFIG.nameappears in the session. - Change something in the shared window. The spot follows within one interval, and the status line counts the uploads.
- Click Stop and remove. The status shows
HTTP 200and the spot disappears.
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.
| Status | Cause | Fix |
|---|---|---|
400 Bad Request | Both file and url are sent, or neither is | Send exactly one of them |
404 Not Found | The access key is wrong, or the DELETE uses an image_source_id that does not exist | Check CONFIG.accessKey and CONFIG.imageSourceId |
410 Gone | The session has ended | Start a new session and use its access key |
415 Unsupported Media Type | The image format is not PNG, JPG / JPEG, WEBP or SVG | Use 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.
- Image Sources API reference for every parameter, including
urlandrefresh_interval - Layout API reference to place the
image_source_idin a fixed position - Update Image Layers for backgrounds and overlays instead of a image source inside the video layout
- Video Sources for sharing video files