> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfsky.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Screencast
> Watch a running browser in the built-in viewer or receive image frames over WebSocket.
Screencast streams a page's screen over WebSocket. It is view-only. Use [DevTools](/debugging) when you need to inspect elements or interact with the browser.
## Get the stream URL
Starting a session returns `inspector.screencast` alongside `ws_url` and `internal_uuid`. Use that value directly; it includes the page target selected for the stream.
A stream URL looks like this:
```text theme={null}
wss://YOUR_API_HOST/screencast/INTERNAL_UUID/devtools/page/PAGE_ID
```
The session and target page must remain open. Closing the viewer does not stop the browser, and an open viewer does not keep it running.
After the connection opens, the server sends `{"type": "started"}`, then a `frame` message for each captured frame, and `{"type": "stopped"}` when the browser side ends. The client does not need to send anything.
## Quick view
Open the built-in viewer at your API base URL with the stream URL in its `ws` query parameter. This browser JavaScript constructs the URL from the start response:
```javascript theme={null}
// baseUrl is your API base URL; session is the parsed start response.
const viewer = new URL("/screencast", baseUrl);
viewer.searchParams.set("ws", session.inspector.screencast);
console.log(viewer.href);
```
Copy the resulting URL into your browser. `URLSearchParams` handles encoding the nested WebSocket URL.
Keep the viewer URL private: anyone who can use it can see the live page.
## Embed a stream
This HTML displays frames at their natural dimensions. Replace `SCREENCAST_URL_FROM_START_RESPONSE` with the returned URL before opening the file:
```html theme={null}
Surfsky screencast
Connecting…
```
Each `frame` message contains a Base64 JPEG in `data` and the CDP screencast frame `metadata`, such as the device dimensions and timestamp. Streaming provides live frames; this example does not store a recording.
## If the stream stops
Watching a screencast is not activity. The browser still stops after `browser_settings.inactive_kill_timeout` seconds without CDP, ChromeDriver, or scraping traffic, 30 seconds by default, and the stream ends with a `stopped` message. Check that the session appears in `GET /profiles/active` before reconnecting. See [the browser stopped by itself](/troubleshooting#the-browser-stopped-by-itself).
The stream follows one page. `inspector.screencast` points at the first page open at start; if your automation opened a new tab, the stream keeps showing the original one. Open `inspector.list` to get the current pages with their `page_id`, then build the stream URL for the page you want:
```text theme={null}
wss://YOUR_API_HOST/screencast/INTERNAL_UUID/devtools/page/PAGE_ID
```