Service reference

Every service that the logic of a PlayerVox OverCrow widget can call, with what it requires, when it can be called, its parameters and its result. Services and permissions explains how calls, subscriptions, errors and user actions work; this page is the list.

TSwidgets/stopwatch/logic.ts

      if (canRead) {
        state.stopwatch = next;
      }
    },
    () => {},
  );
}

In the SDK, a service stopwatch.subscribe is the function stopwatch.subscribe of the stopwatch namespace. A call returns a promise of its result; a subscription takes a listener that receives each update.

How to read a service

Kind: a call is answered once; a subscription delivers a value at once, then each new value.
Requires: the permission or the capability to declare in the manifest, which the user must grant.
When it can be called: at any time, or only during a user action.
Parameters: the members of the object to pass; a ? marks an optional one. A type such as "text ≤ 128 bytes" gives a limit.
Result, or Each update for a subscription: what the service answers, and the error codes that are specific to it. Every service can also fail with the general error codes.
Shape: the type of the result, described in result shapes.

Services

`storage.get`

Kind: call, answered once
Requires: permission storage
When it can be called: At any time
Parameters: key: text ≤ 128 bytes
Result: stored JSON value or null
Shape: JSON

`storage.set`

Kind: call, answered once
Requires: permission storage
When it can be called: At any time
Parameters: key: text ≤ 128 bytes; value: JSON
Result: null; quota_exceeded beyond 256 KiB
Shape: null

`storage.remove`

Kind: call, answered once
Requires: permission storage
When it can be called: At any time
Parameters: key: text ≤ 128 bytes
Result: null

`storage.keys`

Kind: call, answered once
Requires: permission storage
When it can be called: At any time
Parameters: none
Result: list of keys
Shape: list of text

`http.fetch`

Kind: call, answered once
Requires: permission network
When it can be called: At any time
Parameters: url: text ≤ 2 KiB; method: GET | POST | PUT | PATCH | DELETE; contentType?: application/json | text/plain; as: json | text | bytes | image
Result: { status, contentType } with the body, ≤ the rule's maxResponseBytes (1 MiB when absent), or { status, asset } from a body ≤ 1 MiB
Shape: HttpResponse

`clipboard.writeText`

Kind: call, answered once
Requires: permission clipboardWrite
When it can be called: Only during a user action
Parameters: text: text ≤ 16 KiB
Result: null

`gameEvents.subscribe`

Kind: subscription
Requires: permission gameEvents
When it can be called: At any time
Parameters: none
Each update: { event, at } for each declared event
Shape: GameEvent

`session.subscribe`

Kind: subscription
Requires: capability session.read
When it can be called: At any time
Parameters: none
Each update: { elapsedMs, at } counted from the start of the game process, or null without an active game
Shape: Session or null

`telemetry.subscribe`

Kind: subscription
Requires: capability telemetry.read
When it can be called: At any time
Parameters: none
Each update: { cpu, ram, cpuTemperature, gpuTemperature, sources }, or null without an active game: cpu is the game's share of the whole machine in % (0–100), ram its resident bytes, temperatures are °C or null, sources { cpuTemperature, gpuTemperature } says whether the host has each sensor
Shape: Telemetry or null

`fps.subscribe`

Kind: subscription
Requires: capability fps.read
When it can be called: At any time
Parameters: none
Each update: { fps, stale, status }: fps a number or null; the host sets stale 3 s after the last sample; status is ready, waiting, unsupported, permission_denied, ambiguous, events_lost or unavailable
Shape: Fps

`media.subscribe`

Kind: subscription
Requires: capability media.read
When it can be called: At any time
Parameters: cover?: boolean
Each update: null without a player, or { player, title, artists, playing, canPrevious, canPlayPause, canNext, cover }: player an opaque ID, artists a list, cover an asset: handle of at most 512 px or null
Shape: Media or null

`media.previous`

Kind: call, answered once
Requires: capability media.control
When it can be called: Only during a user action
Parameters: player?: text ≤ 128 bytes
Result: null; stale_context when player is no longer current
Shape: null

`media.playPause`

Kind: call, answered once
Requires: capability media.control
When it can be called: Only during a user action
Parameters: player?: text ≤ 128 bytes
Result: null; stale_context when player is no longer current
Shape: null

`media.next`

Kind: call, answered once
Requires: capability media.control
When it can be called: Only during a user action
Parameters: player?: text ≤ 128 bytes
Result: null; stale_context when player is no longer current
Shape: null

`stopwatch.subscribe`

Kind: subscription
Requires: capability stopwatch.read
When it can be called: At any time
Parameters: none
Each update: { running, elapsedMs, at, shortcuts }, or null without an active game; shortcuts { toggle, reset, bound } holds host-formatted key chords
Shape: Stopwatch or null

`stopwatch.toggle`

Kind: call, answered once
Requires: capability stopwatch.control
When it can be called: Only during a user action
Parameters: none
Result: the new state, as in stopwatch.subscribe; unavailable when the host cannot act
Shape: Stopwatch or null

`stopwatch.reset`

Kind: call, answered once
Requires: capability stopwatch.control
When it can be called: Only during a user action
Parameters: none
Result: the new state, as in stopwatch.subscribe; unavailable when the host cannot act
Shape: Stopwatch or null

`notes.subscribe`

Kind: subscription
Requires: capability notes.read
When it can be called: At any time
Parameters: none
Each update: { active, notes } of the user's single notes document; each note { id, title, body, items }, each item { id, text, checked }
Shape: Notes

`notes.create`

Kind: call, answered once
Requires: capability notes.write
When it can be called: Only during a user action
Parameters: none
Result: { note }, a new empty active note titled Note {n} in the user's language; quota_exceeded beyond 8
Shape: CreatedNote

`notes.select`

Kind: call, answered once
Requires: capability notes.write
When it can be called: Only during a user action
Parameters: note: text ≤ 128 bytes
Result: null; the host stores the active note
Shape: null

`notes.setItem`

Kind: call, answered once
Requires: capability notes.write
When it can be called: Only during a user action
Parameters: note: text ≤ 128 bytes; item: text ≤ 128 bytes; checked: boolean
Result: null

`notes.delete`

Kind: call, answered once; the user confirms it first, in a dialog drawn by PlayerVox OverCrow
Requires: capability notes.write
When it can be called: Only during a user action
Parameters: note: text ≤ 128 bytes
Result: null, or cancelled when the user declines
Shape: null

`playervox.score.subscribe`

Kind: subscription
Requires: capability playervox.score.read
When it can be called: At any time
Parameters: none
Each update: { state, name, score, grade, ratingsCount, criteria }: state is idle, unsupported, loading, ready, no_ratings, not_found or unavailable; criteria { gameplay, art, tech }, each from 0 to 100 or null
Shape: Score

`playervox.rating.subscribe`

Kind: subscription
Requires: capability playervox.rating.read
When it can be called: At any time
Parameters: none
Each update: { state, name, offline, rating }: state is idle, unsupported, loading, ready or unavailable; rating is null before the user's first rating, or { gameplay, art, tech, review, publishedAt, offsetMinutes }. Nothing is sent while the PlayerVox account is signed out, pending or expired. A published rating is sent again by the subscription. The host fills the playervox.rating.publish controls from it
Shape: RatingState

`playervox.reviews.subscribe`

Kind: subscription
Requires: capability playervox.reviews.read
When it can be called: At any time
Parameters: none
Each update: { state, revision, offline }: state is idle, unsupported or ready; revision changes whenever the reviews to read change (another game, another PlayerVox account, reviews changed on PlayerVox), so the widget reads its page again; offline while PlayerVox is unreachable. Nothing is sent while the PlayerVox account is signed out, pending or expired. Holding this subscription is what keeps the host's reviews source running
Shape: ReviewsState

`playervox.reviews.page`

Kind: call, answered once
Requires: capability playervox.reviews.read
When it can be called: At any time
Parameters: page?: integer 1 to 100000; followedOnly?: boolean
Result: { gameName, items, page, totalPages, count }: three reviews of the active game per page, in the language of the host's interface; a page past the end answers the last page; each item { id, author, grade, score, text, original, hidden, publishedAt, offsetMinutes }, text translated when a translation exists, original the untranslated text of a translated review or null, both cut by the host to 16 KiB. Each call reads its own page: the host keeps no page position or filter shared between widgets
Shape: ReviewsPage

`journal.subscribe`

Kind: subscription
Requires: capability journal.read
When it can be called: At any time
Parameters: none
Each update: null without an active game, or { revision, notice }: revision changes whenever the merged journal of the active game changes (a session recorded or deleted, cloud sessions merged, the PlayerVox account or sync changed), so the widget reads its page again; notice is null, offline, storage_unavailable, full, expired, busy or unavailable. Holding this subscription is what keeps the host's journal source running
Shape: JournalState or null

`journal.page`

Kind: call, answered once
Requires: capability journal.read
When it can be called: At any time
Parameters: cursor?: text ≤ 128 bytes
Result: { gameName, items, page, next, previous }: five local and cloud sessions of the active game, merged and deduplicated, newest first; without cursor, the first page; each item { id, startedAt, offsetMinutes, durationMs, source }; cursors are host handles that stay valid for the widget whatever other widgets read, and a cursor past the end answers the last page
Shape: JournalPage

`journal.delete`

Kind: call, answered once; the user confirms it first, in a dialog drawn by PlayerVox OverCrow
Requires: capability journal.delete
When it can be called: Only during a user action
Parameters: session: text ≤ 128 bytes
Result: null, or cancelled when the user declines; not_connected for a cloud session while PlayerVox is disconnected
Shape: null

`twitch.chat.subscribe`

Kind: subscription
Requires: capability twitch.chat.read
When it can be called: At any time
Parameters: none
Each update: { account, channel, joinState, failure, favorites, canSend, generation, reset, messages, removed, skipped }: account is signed_out, pending, connected or expired (sign-in is drawn by the host); failure is the fixed category of a failed join; messages arrive as deltas, at most one update per 100 ms, with reset after subscribing, a generation change or a show, and nothing while the widget is hidden; a faster chat is sampled, skipped counting the new messages left out; each message { id, author, color, badges, fragments, reply, deleted, receivedAt } with at most 16 fragments, emotes and badges as asset: handles for the current theme and scale
Shape: TwitchChat

`twitch.chat.join`

Kind: call, answered once
Requires: capability twitch.chat.read
When it can be called: Only during a user action
Parameters: channel: text ≤ 25 bytes
Result: null; the host remembers the channel and rejoins it when the widget starts
Shape: null

`twitch.chat.leave`

Kind: call, answered once
Requires: capability twitch.chat.read
When it can be called: Only during a user action
Parameters: none
Result: null; the host forgets the channel
Shape: null

`twitch.chat.favorite`

Kind: call, answered once
Requires: capability twitch.chat.read
When it can be called: Only during a user action
Parameters: channel: text ≤ 25 bytes; favorite: boolean
Result: null; quota_exceeded beyond 20
Shape: null

Writes that go through a form

Saving a note, publishing a rating and sending a chat message are not in this list: they are write intents, sent by a form from the values that the user typed. See forms that write user data.