API reference

Inside a bundle, your code talks to the app through window.DesktopOverlaysAPI. The API is split into namespaces. Each namespace is only present if you request its permission in the manifest. If you do not request a scope, the namespace is undefined, so guard for it or rely on your declared permissions.

const api = window.DesktopOverlaysAPI
if (api.audio) api.audio.onUpdate(frame => { /* ... */ })

Methods that return data return a Promise. Methods named onUpdate (and similar) take a callback and keep calling it as the data changes.

Namespaces at a glance

Namespace	Permission	Purpose
audio	sdk.audio	System audio FFT frames.
media	sdk.media	The now-playing track.
windows	sdk.windows	Open windows and desktop state.
app	sdk.app	Foreground app, fullscreen, display, desktop.
notifications	sdk.notifications	Windows notifications.
resources	sdk.resources	CPU, GPU, memory, disk, and network metrics.
options	sdk.options	The user's settings for this overlay.
content	sdk.content	Messages between the bundle's surfaces.
size	sdk.size	Read, set, and watch the overlay size.
position	sdk.position	Read, set, and watch the overlay position.
mouse	sdk.mouse	Cursor position relative to the display and the overlay.
storage	sdk.storage	Persistent key/value storage shared by the bundle.
user	sdk.user	The signed-in Steam user's id.

Coordinates

position and mouse use the same coordinate space as the overlay itself: pixels relative to the top-left of the display the overlay sits on, with displayId telling you which monitor. mouse also gives overlayX/overlayY, which are relative to the overlay box's top-left, so 0, 0 is the overlay's own corner.

audio

Requires sdk.audio. Provides frequency data captured from system audio output, suitable for visualizers.

audio.onUpdate(callback)

Calls callback(frame) for each new frame. frame is a Uint8Array of 256 values from low to high frequency, each 0-255 (like getByteFrequencyData). The bars snap up to beats and fall back gently. Frames arrive about every 16ms (~60fps).

const bars = document.querySelectorAll('.bar')
api.audio.onUpdate((frame) => {
  bars.forEach((bar, i) => {
    bar.style.height = (frame[i] / 255 * 100) + '%'
  })
})

media

Requires sdk.media. Reports the Windows now-playing session.

media.get()

Returns a Promise of the current snapshot, or a snapshot with hasSession: false when nothing is playing.

media.onUpdate(callback)

Calls callback(info) whenever the now-playing session changes.

The snapshot shape:

Field	Type	Notes
hasSession	boolean	False when there is no media session.
title	string
artist	string
albumTitle	string
albumArtist	string
trackNumber	number
albumTrackCount	number
genres	string[]
playbackStatus	string
isPlaying	boolean
appId	string	The source app.
position	number	Playback position.
duration	number	Track length.
lastUpdatedMs	number	When position was last refreshed.
thumbnail	string or null	A data:image/...;base64,... URI of the album art, or null.

Position and timeline only refresh on a seek or a track change. For a live position, interpolate from lastUpdatedMs while isPlaying is true.

const snap = await api.media.get()
if (snap.hasSession) title.textContent = snap.title + ' - ' + snap.artist

windows

Requires sdk.windows. Reports open top-level windows and whether the desktop is showing. The app's own overlay windows are excluded from the list.

windows.get()

Returns a Promise of the currently visible top-level windows as WindowInfo[]. Visible means not minimized, not cloaked, and having a title.

windows.getForeground()

Returns a Promise of the current foreground window as WindowInfo, or null on the desktop.

windows.onUpdate(callback)

Calls callback({ windows, foreground, desktop }) whenever the set of windows or the foreground changes. desktop is the same boolean as $.app.desktop in conditions: true when no application window is visible.

WindowInfo shape:

Field	Type
title	string
exe	string
x	number
y	number
width	number
height	number
foreground	boolean

app

Requires sdk.app. Gives you the same $.app state that conditions use, readable at runtime.

app.get()

Returns a Promise of { activeProcess, fullscreen, displayId, desktop }. activeProcess is the lowercase foreground executable name, or null on the desktop. displayId is the display this overlay sits on.

app.onUpdate(callback)

Calls callback(state) with the same shape whenever the foreground or desktop state changes, so the bundle can react to the same conditions it declares.

notifications

Requires sdk.notifications. Reports Windows notifications from the Action Center. On first use, Windows asks the user to allow reading notifications. If the user declines, the list comes back empty.

notifications.get()

Returns a Promise of the current notifications as NotificationInfo[], oldest first.

notifications.getLast()

Returns a Promise of the newest notification as NotificationInfo, or null.

notifications.onUpdate(callback)

Calls callback(list) with the full current list whenever a notification is added, updated, or removed.

NotificationInfo shape:

Field	Type
id	string
appId	string
appName	string
title	string
body	string
timestamp	number

resources

Requires sdk.resources. Live system metrics: CPU, GPU, memory, disks, and network adapters. Read from Windows performance counters, enriched with NVML for NVIDIA GPUs. Capacities are bytes, throughput is bytes per second, temperatures are Celsius, usage is a percent (0-100), and memory speed is MHz. Anything Windows will not reveal comes back null or 0 (for example per-core temperatures, and the temperature and usage of non-NVIDIA GPUs).

resources.get()

Returns a Promise of the current snapshot.

resources.onUpdate(callback)

Calls callback(update) with the same snapshot about once a second while subscribed. The reader runs only while a bundle is listening, so there is no cost when nobody subscribes.

The snapshot shape is { cpu, gpu, memory, disk, ethernet }:

cpu is an array (one entry per processor package):

Field	Type	Notes
name	string	e.g. "AMD Ryzen 7 5800X 8-Core Processor".
temperature	number or null	Package/thermal-zone reading, or null when unavailable.
usage	number	Overall busy percent, 0-100.
cores	array	Per logical core (see below). cores.length is the core count.
threads	number	Logical processor count.

Each cores[] entry:

Field	Type	Notes
index	number	Logical processor index.
usage	number	Busy percent for that core, 0-100.
temperature	number or null	Per-core temperature, usually null on Windows.

gpu is an array (one entry per adapter):

Field	Type	Notes
name	string
temperature	number or null	Celsius on NVIDIA, null otherwise.
usage	number or null	0-100 on NVIDIA, null otherwise.
memory	object	{ total, used, free } in bytes. used/free are 0 on the non-NVIDIA fallback.

memory is an array, one entry per physical RAM module. total and speed are that module's own; RAM usage is not measurable per stick, so the system-wide used/free are echoed onto every entry:

Field	Type	Notes
name	string	Module make/part and slot, or "System Memory".
total	number	This module's capacity, in bytes.
used	number	System-wide bytes in use (same on every entry).
free	number	System-wide bytes free (same on every entry).
speed	number	This module's speed in MHz, or 0 when unknown.

disk is an array (one entry per drive):

Field	Type	Notes
name	string	The drive, e.g. "C:".
type	string	"fixed", "removable", etc.
total	number	Capacity in bytes.
used	number	Used space in bytes.
speeds	object	{ read, write } in bytes per second.

ethernet is an array (one entry per network adapter):

Field	Type	Notes
name	string	Adapter name.
speeds	object	{ upload, download } in bytes per second.

api.resources.onUpdate((u) => {
  cpuBar.style.width = u.cpu[0].usage + '%'
  const gpu = u.gpu[0]
  if (gpu) gpuLabel.textContent = `${gpu.name} ${gpu.usage ?? '?'}%`
  const installed = u.memory.reduce((sum, m) => sum + m.total, 0)
  if (installed) ramLabel.textContent = Math.round(u.memory[0].used / installed * 100) + '%'
})

options

Requires sdk.options. Reads the user's settings for this overlay instance and reacts to changes. See Options for how to define them.

options.get()

Returns a Promise of the current values, keyed by option key.

options.set(key, value)

Sets one option value.

options.update(values)

Sets several option values at once, given an object of key to value.

set and update cannot change shortcut or file options. Those are user-driven only, and writes to them are ignored.

options.onUpdate(callback)

Calls callback(event) when something changes. The event.action field tells you what happened:

action	Extra fields	Meaning
value-change	values	One or more option values changed. values holds the changed keys.
button-click	key	A button option was clicked.
shortcut	key	A shortcut option's global key was pressed.
editor-state	visible, editMode	The overlay's editor state changed. visible is whether the overlay is shown; editMode is whether the editor panel is open.

The initial state is also sent once when the surface loads.

api.options.get().then(apply)
api.options.onUpdate((e) => {
  if (e.action === 'value-change') apply(e.values)
  else if (e.action === 'button-click') doAction(e.key)
})

content

Requires sdk.content. Lets the bundle's own surfaces talk to each other. A message is delivered to every other open surface of the same bundle, but not back to the sender.

content.sendMessage(message)

Sends a message object to the bundle's other open surfaces.

content.onMessage(callback)

Calls callback(message) for messages from the bundle's other surfaces.

size

Requires sdk.size. Reads and changes the overlay's box size.

size.get()

Returns a Promise of { width, height } in pixels.

size.set(width, height)

Resizes the overlay. Expects positive integers. The change is saved and reflected everywhere. If the content declares size bounds (minWidth/maxWidth/minHeight/ maxHeight in the manifest), the value is clamped to them. For fullscreen surfaces the effect is limited, since they cover the display.

const s = await api.size.get()
api.size.set(s.width, s.height + 40)

size.onUpdate(callback)

Calls callback({ width, height }) whenever the overlay box is resized, whether by the user dragging a handle, by size.set, or by a content swap. Useful for re-laying-out a canvas.

api.size.onUpdate(({ width, height }) => {
  canvas.width = width
  canvas.height = height
})

position

Requires sdk.position. Reads, sets, and watches where the overlay sits. See Coordinates for the coordinate space.

position.get()

Returns a Promise of { x, y, displayId }.

position.set(x, y, displayId?)

Moves the overlay to display-local x, y. The move is smart about monitors: if the point spills past the display's edge, the overlay slides onto the adjacent monitor and displayId updates to match. Pass an optional displayId to make x, y relative to that monitor instead of the overlay's current one (handy for jumping to a specific screen). The change is saved.

const p = await api.position.get()
api.position.set(p.x + 100, p.y) // nudge right, crossing to the next monitor if needed
api.position.set(0, 0, 2)        // top-left of display 2

position.onUpdate(callback)

Calls callback({ x, y, displayId }) whenever the overlay is moved or lands on another display.

mouse

Requires sdk.mouse. Reports the cursor position relative to the display and to the overlay. This works on the live desktop even though the overlay is click-through.

mouse.onUpdate(callback)

Calls callback({ x, y, overlayX, overlayY, hovering, displayId }) as the cursor moves over the overlay's display.

Field	Type	Notes
x	number	Cursor x, display-local.
y	number	Cursor y, display-local.
overlayX	number	Cursor x relative to the overlay box's top-left.
overlayY	number	Cursor y relative to the overlay box's top-left.
hovering	boolean	Whether the cursor is over the overlay box.
displayId	number	The monitor the cursor is on.

api.mouse.onUpdate(({ overlayX, overlayY, hovering }) => {
  eye.style.transform = hovering ? `translate(${overlayX}px, ${overlayY}px)` : ''
})

storage

Requires sdk.storage. A small key/value store that persists across restarts and is shared by every instance of your bundle (keyed by the bundle's name and author), so two copies of the same overlay see the same data and it survives reinstalling or updating the bundle. Values must be JSON-serializable.

storage.get(key?)

With a key, returns a Promise of that value (or undefined). With no argument, returns the whole store as an object.

storage.set(key, value)

Stores one value and persists it.

storage.update(values)

Merges several values at once, given an object of key to value.

storage.onUpdate(callback)

Calls callback({ values }) whenever any instance of the bundle writes, including this one. values holds the keys that changed, so instances stay in sync.

const saved = await api.storage.get('highScore')
api.storage.set('highScore', Math.max(saved ?? 0, score))
api.storage.onUpdate(({ values }) => {
  if ('highScore' in values) render(values.highScore)
})

user

Requires sdk.user. Exposes the identity of the signed-in Steam user.

user.get()

Returns a Promise of the user's Steam id as a string, or null when Steam isn't available. The id is stable per account, so a bundle can use it to scope per-user state, leaderboards, or saves.

const steamId = await api.user.get()
if (steamId) console.log('signed in as', steamId)