From OpenCloudGaming/OpenNOW a49b124c (2026-10-18): native/opennow-core and the native/opennow-streamer crates DroidDeck's GeForce NOW store builds on, unmodified, with OpenNOW's MIT license and a NOTICE crediting Zortos and the OpenNOW contributors.
120 KiB
OpenNOW shell/core protocol
The Qt shell and Rust application core communicate over newline-delimited UTF-8 JSON on inherited standard input/output. Standard error is reserved for redacted diagnostics. A line is limited to 1 MiB. Unknown, malformed or oversized protocol messages terminate the core connection instead of leaving the shell in an ambiguous state.
Handshake
The first shell request is always:
{"type":"request","id":"1","method":"core.hello","params":{"protocolVersion":5,"shell":"qt","shellVersion":"0.5.4"}}
Protocol 5 requires an exact selected catalog variant and account scope for fresh
session allocation. It retains the bounded library-page contract introduced in
protocol 4. Older shells are rejected with incompatible_protocol during
core.hello, and protocol-5 shells reject older cores. The native streamer
protocol remains 7.
The core must return the same protocol version and its capabilities. The shell
does not send product requests before this succeeds. Version mismatches, a
five-second handshake deadline, process exit and invalid data all transition the
transport to failed with a credential-free diagnostic.
The desktop queue selector requires the queue.servers.v1 capability in this
handshake. The Qt client and relocated package probes reject cores that omit it,
including older protocol-5 binaries, before sending any product requests. This
additive capability leaves the JSON envelope and native streaming ABI unchanged.
Saved accounts (auth.accountPicker.v1)
The "Who's playing?" picker requires the auth.accountPicker.v1 capability. The
Qt client rejects cores that omit it during core.hello, before any product
request. The capability is additive: the protocol version, the envelope and the
native streaming ABI are unchanged.
auth.accounts.list returns {accounts, activeUserId, generation}. Each account
contains only public identity fields; tokens never cross the boundary:
| Field | Type | Meaning |
|---|---|---|
userId, displayName |
string | Saved identity. |
email, avatarUrl |
string or null | From the last sign-in or token refresh. |
membershipTier |
string | FREE, PERFORMANCE or ULTIMATE today. Shells must render other values without failing. |
providerCode |
string | Login provider code. NVIDIA is NVIDIA; any other code is an alliance partner. |
providerName |
string | Display name for the provider. The core owns the code-to-name mapping (gfn::provider_display_name): the name saved at sign-in, then the discovered provider name for that code, then the code itself. BPC is always bro.game. |
providerIdpId |
string, optional | Provider IdP for "Sign in again". Absent for accounts saved before this field existed until their next sign-in or refresh. |
alliance |
bool | providerCode != "NVIDIA". |
hasPin |
bool | A local profile PIN guards auth.accounts.switch. |
needsSignIn |
bool | The last restore or switch for this account ended with refresh outcome expired after the provider answered (not after a network failure). Cleared when the account signs in or refreshes again. |
auth.accounts.switch never ends a running cloud session; the seat keeps its
original owner. The Qt shell ends the session through its end-session
confirmation and waits for session.stop before it sends the switch.
The startAsLastUsedAccount setting (bool, default false) skips the launch
picker when two or more accounts are saved. Loading settings migrates the
retired consoleProfilePickerOnLaunch: false to startAsLastUsedAccount: true.
Cloud library actions and launch decisions
catalog.launch.inspect({appId, variantId}) always resolves the exact parent and
store variant. Its response contains appId, variantId, game, scope,
catalogRevision, fetchedAt, freshness, and decision: {status, message}.
Statuses are ready, ownership_required, selection_required, link_required,
subscription_required, patching, maintenance, unavailable, and
metadata_unconfirmed. Only the selected variant's MANUAL or PLATFORM_SYNC
library status records ownership. App-wide library flags, Home pins, favorites,
free-game labels, store subscriptions, and ownership of another variant do not.
Store-link requirements use the store definitions and fresh account state.
Recorded store-subscription IDs must match the account's active subscriptions.
App playability, variant readiness, patch metadata, and membership restrictions
remain independent checks. Unknown metadata is not a positive authorization.
catalog.launch.store.inspect({store?}) resolves the platform-client apps for the
current streaming region with a PLATFORM_CLIENT type filter and returns
{store, appId, variantId, game, scope, decision, catalogRevision, fetchedAt, freshness}. The resolved appId, variantId, and game are the values the
platform-client query returned for this account. store defaults to STEAM,
the only supported store-client launch, and any other value is invalid_params.
The eligible target is the first game exposing a variant whose exact appStore
value matches the store and whose id is a bounded identifier; extra variants and
extra platform-client apps are searched, not rejected.
The store-launch decision reuses the shared decision vocabulary. It requires the
exact parent identity and variant identity, the exact store on the resolved
variant, a present gfn.status of AVAILABLE, and any patching or maintenance
metadata the server returns. It then requires the persistent-storage entitlement:
the subscription addons entry whose type is STORAGE and whose subType is
PERMANENT_STORAGE and whose status is OK, which the core publishes as
subscription.storageAddon. An ephemeral storage add-on, including
EPHEMERAL_STORAGE, does not authorize a store launch. Store-account linking
requirements, recorded store subscriptions, membership tier, and
isGamePlayAllowed apply from the same account metadata the ordinary launch path
uses.
Cloud DLSS overrides follow the official client. The dlssOverrides setting stores
the exact requestedStreamingFeatures.dlssOverrides wire object (srMode, srModel,
srScale, rrModel, fgMode, fgModel, fgMultiplier), where 0 leaves a feature
to the game. The core clamps unknown enum values to 0, leaves a mode to the game
when its model is, fixes srScale for every SR mode except Custom (33–100), and sends
fgMultiplier only for Dynamic frame generation. Every create request carries the
object. subscription.dlssOverrides reports entitled and upsell for
superResolution, frameGeneration, and rayReconstruction from the MES
SUPPORTED_DLSS_OVERRIDE_* features and SUPPORT_DLSS_OVERRIDE_* upsells, plus the
entitled frameGenerationMultipliers from SUPPORTED_DLSS_FG_MULTIPLIERS.
A platform client that the ordinary catalog resolution also returns is judged by
that resolution's metadata, so catalog playabilityState and patch state are
enforced there. When the ordinary resolution does not return the app, the store
query's own gfn.status is the readiness field, because that query selects no
catalog playability. When the ordinary resolution returns the app but not the
discovered variant, the two sources disagree and the decision is
metadata_unconfirmed rather than a guess.
catalog.launch.inspect and session.create accept storeLaunch: true, a
boolean that selects the platform-client resolution source and the
persistent-storage requirement. The flag grants nothing: the same mutation
admission, scope, catalog revision, active-seat, and exact-variant checks run, and
a store intent that names a target the platform-client resolution does not return
is not ready. Missing, non-boolean, or mismatched values do not fall back to
another target.
All five mutation RPCs require a bounded nonempty parent appId and the current
scope: {generation, userId, providerIdpId}. Ownership mutations also require the
exact variantId. catalog.ownership.add requires
confirmedExistingLicense: true, the user's assertion that they already own the
selected store license. This operation neither buys nor grants a license.
catalog.ownership.select accepts only an owned variant and does not add ownership.
Favorites map to the GraphQL AddFavoriteApp and RemoveFavoriteApp operations
with appId and locale variables. Ownership maps to AddOwnedVariant,
RemoveOwnedVariant, and SelectOwnedVariant, with cmsId and locale
variables. cmsId supplies the variantId argument. Every mutation selects
app { id } and checks the returned parent identity. Mutations share catalog
scheduling and serialize conflicting actions for the same account and parent
app. Fresh allocation holds that same app admission while checking and creating.
Mutation results distinguish outcome: acknowledged|unconfirmed from
reconciliation: confirmed|unconfirmed. A fresh exact read confirms the desired
current state; acknowledgement alone does not. Results include captured target
IDs, operation, scope, catalogRevision, nullable refreshed game, a visible
message, and sanitized error.code, error.httpStatus, and error.graphql
code/path details. reconciliationCode and invalidationCode distinguish read
or cache-invalidation failures from the mutation outcome.
Neither ambiguous failures nor HTTP 401 cause mutation replay. Catalog pages are
invalidated before sending and again after the attempt. Cancellation may prevent
delivery of the outcome without preventing an already-sent upstream mutation.
The shell marks that outcome unconfirmed and refreshes metadata without resending.
catalog.favorites.list reads the FAVORITES panel using GetGameSection with
panelNames, vpcId, and locale; it has no cursor. It preserves all parsed game
items up to the 1,000-game and 768-KiB response bounds, rather than the Store
panel's 24-item display limit. The response contains games, section identity
and seeMoreInfo, scope, catalogRevision, and fetchedAt. coverage is
unknown and complete is false because the panel does not establish global
completeness. No pagination or see-more request is invented. A failed read keeps
the shell's last usable list, and a specific favorite is reconciled through the
exact app's library.favorited value. Existing favoriteGameIds remain local
Home pins; pinning, collections, hiding, and reordering do not upload favorites.
Messages
Authentication boundary
Protocol 5 auth responses and auth.session.changed events use the same envelope.
session is either null or an allowlisted object containing user and provider.
Credentials and issuing-client details remain private to the core. The envelope
includes the core-process account generation, persistence, refresh, warnings,
and deviceIdentity. Consumers reject older generations and reset their generation
when a new core process completes its handshake. A token refresh does not change
account generation.
auth.device.start returns attemptId, userCode, verification URLs, qrRows,
expiresAt, and intervalSeconds. Poll, complete, and cancel use attemptId only.
The core retains the device grant and enforces the deadline, one in-flight poll,
and cumulative five-second slow_down increments. Pending poll replies include
retryAfterMs; the shell schedules one subsequent poll from that reply.
Cancellation before the completion commit fence prevents persistence and publication.
Once the fence is entered, completion is committed under auth ownership; cancelling
its response does not undo that login. The shell reconciles such cancellation with
auth.session.get. Logout or account replacement invalidates pending login/link work.
Persistence intent is independent of outcome. Persistent sessions prefer the OS
credential store on every desktop platform, including Windows. secure-store means
the session was written to and verified in that store and its nonsecret index committed.
local-file means session tokens are saved in unencrypted JSON because the OS store
is unavailable. The per-account file is under
data_dir/fallback-sessions/<sha256 user>.json, with private file access permissions.
Those permissions do not encrypt the tokens. The shell warns that anyone who can read
the file can access the account. Fallback reads take priority over stale OS-store entries.
The next successful secure save verifies the OS-store entry before removing the JSON
fallback.
If the account-index commit fails after JSON is written, persistence remains
local-file and warnings report that account restoration may fail. Interrupted
JSON temporary files are removed on startup and during account cleanup.
memory-only never writes a plaintext credential fallback. migration-pending means
a recoverable legacy source remains because migration could not finish. unavailable
means restoration failed. Warnings identify deferred cleanup without containing
credentials, and the auth envelope never includes tokens. An explicitly temporary
login suppresses automatic restoration of older saved grants for that identity.
Legacy sources are removed only after verified persistence and metadata commit, or
explicit account removal. This is file cleanup, not guaranteed secure erasure of
backups or snapshots.
Logout always ends local auth ownership and reports remoteRevoke separately from
localCleanup. Revocation is best-effort DELETE of the selected client grant with an
access bearer; all-account revocation has a five-second total network budget. Failed
local deletion remains suppressed in the nonsecret account index and is retried on
startup. Logout removes the JSON fallback even if the OS store remains inaccessible;
deferred OS-store cleanup keeps the existing suppression semantics. A metadata write
failure reports pending cleanup and cannot guarantee that suppression survives restart.
Logout selects the next saved account only when it does not require a profile PIN.
Automatic restoration, including a new core process, never activates a PIN-protected
profile. Its credentials remain saved for an explicit PIN-verified switch. An already
unlocked session remains active within the current core process.
Qt loads saved profiles independently of signed-in account services. After a signed-out startup completes, saved profiles open in the existing account picker. An active stream does not trigger automatic navigation. Its user can open saved accounts explicitly from sign-in and unlock a profile without replacing the native video item.
Logout-all also scans local fallback files independently of the account index. Missing
or corrupt metadata cannot prevent best-effort plaintext cleanup. Recoverable identities
are suppressed and removed from the OS store too. Unreadable identities or failed cleanup
remain pending; corrupt metadata is not silently overwritten.
The core persists one versioned 64-hex device identity. Upgrades freeze the previously derived identity using the current environment; if that environment changed before the first upgraded launch, the former hash cannot be recovered. Corrupt or unwritable identity storage is not replaced, new login is blocked, and restoration reports unavailable device identity rather than claiming durable compatibility.
{"type":"request","id":"42","method":"settings.get","params":{}}
{"type":"response","id":"42","ok":true,"result":{"settings":{}}}
{"type":"response","id":"42","ok":false,"error":{"code":"invalid_setting","message":"…"}}
{"type":"event","name":"settings.changed","payload":{"key":"fps","value":120}}
{"type":"cancel","id":"42"}
Request IDs are unique within a core process. Every request has a bounded deadline (100 ms to five minutes). The shell sends cancellation after a timeout or explicit cancellation. Events are delivered in batches through a queue of at most 512 items; overflow drops the oldest event and emits a diagnostic counter.
The core admits at most eight RPC workers, with at most four background workers
(catalog.*, artwork.*, and network.regions.ping). The remaining capacity
is reserved for other methods, including session/control operations. Excess
requests receive busy; duplicate active IDs are also rejected. Cancellation
only tracks active IDs and never frees a worker slot before that worker exits.
The Qt client keeps requests rejected with busy pending and retries the same
ID and payload after 100 ms, doubling the delay up to one second. Retries do not
extend the original deadline. Cancellation, shutdown, and process failure discard
pending retries. Other errors are delivered to the caller without retrying.
Cancelled requests suppress their response. Store page retries/cache traversal
and region measurement loops stop at cooperative checkpoints. An already-running
blocking HTTP, DNS, or TCP operation is not forcibly interrupted; its existing
timeout still applies. Other mutating operations already dispatched are not rolled back.
Protocol 5 retains the requirement for the Qt client to acknowledge an accepted successful session.create
response with {"type":"ack","id":"42"} before delivering that response to QML.
Cancelled or timed-out requests do not acknowledge late responses. The create worker
retains its admission slot for at most ten seconds awaiting acceptance, then the
CloudMatch owner deletes an unaccepted fresh allocation with an eight-second HTTP
deadline. Fresh creation sends a CloudMatch POST without a follow-up PUT;
cancellation after POST uses the same cleanup. PUT RESUME applies only to claims
of existing sessions.
The receipt does not apply to claims of existing sessions. A create response is not
also broadcast as session.changed, preventing a late event from reviving a cancelled
launch. Cleanup failure retains the seat and its scoped discovery route for explicit
retry, blocks another fresh allocation, and reports session_cleanup_pending.
The failed-cleanup record persists only the seat identity, app/status, trusted control
route, original provider/account identity, and error code in pending-session-cleanup.json;
it contains no tokens or signaling secrets. Discovery surfaces it only to that account.
Explicit successful DELETE or not-found clears that exact record, never a different seat.
HTTP-success DELETE responses containing an explicit vendor rejection retain ownership.
The CloudMatch owner reserves fresh-create admission before endpoint resolution or POST.
Concurrent creation, pending handoff, and in-progress cleanup lock contention fail promptly with
session_update_busy, not the automatically retried busy response. Admission is
released on every pre-ID error; after allocation the exact seat remains reserved until
handoff or compensation completes. Cleanup records are read through a 16-KiB limit plus
one overflow-detection byte before parsing, including for corrupt or oversized files.
The session.terminalCleanup.v1 capability adds session.ended. The Qt client
requires this capability during the handshake so an older packaged core cannot
silently retain an ended seat. The JSON protocol version remains 5.
After an authoritative, non-resumable nvst-server termination, the shell sends
session.ended with {sessionId, ownerScope: {userId, providerIdpId}}
from the ended session. This local acknowledgement makes no network request and
requires no valid authentication token. It releases only the exact accepted seat
whose account and provider match. An extra ownerScope.generation is ignored:
control reconciliation can change the core generation before the shell consumes
its response, but it does not change the remote seat's identity.
Pending allocation handoffs and cleanup records are not released.
A matching pending handoff returns
session_update_busy so the shell retries after handoff. The response is
{sessionId, cleared}; duplicate or stale notifications return cleared: false
without changing another seat.
No session.changed event is emitted, so a late acknowledgement cannot clear a
replacement session in the shell. The shell blocks another launch until the
acknowledgement arrives and retries after transient RPC failure or core restart.
Late session snapshots cannot revive the natively terminated seat.
Transport EOF and other failures with unknown resumability do not send this request.
Raw CloudMatch status 7 is phase: "finished", with a termination object containing
source: "cloudmatch-session-status", status: 7, and resumable: false. This proves
the seat is terminal, not whether the game exited successfully; no vendor reason is
invented. A targeted GET returning HTTP 404 yields session: null and a top-level
termination with source: "cloudmatch-http", httpStatus: 404, sessionId, and
resumable: false. Authentication, invalid payloads, other HTTP failures, empty lists,
and native transport closure are not terminal evidence. Recovery first polls the exact
seat before claiming it. session.poll with recoveryMode: true does not broadcast a
session change while the recovery owner is deciding whether to claim.
Negotiated profiles retain normalized bitDepth (8 or 10), CloudMatch chromaFormat
(0 or 1), and per-component *Source fields. request, finalized, server, and
unreported distinguish present values from omissions. Same-seat partial updates retain
previously known components; explicit finalized invalid values are not replaced with
saved preferences. Incomplete or unsupported accepted color is rejected before native
attachment. Transport terminal
events add termination: {source: "nvst-transport", code, resumable: null}, preserving
unknown cloud-session disposition rather than assigning a normal-exit reason to EOF.
Native ABI 13 adds session-timer events through the existing JSON event callback,
with startId, timerType, secondsLeft and active. Idle-warning type 4 shows
stream chrome without stopping media; type 5 or successfully delivered gameplay
input clears it. Server termination events preserve wireCode separately from
optional application reason and extendedCode in termination, use source
nvst-server, and carry a boolean resumable only for verified classifications.
Nonresumable server termination prevents automatic restart and resume. Unknown
classification remains null and is reconciled against CloudMatch. The JSON protocol
version is unchanged; the native library and Qt shell must be rebuilt together.
Expected, authoritative server endings do not create stream-error incidents or
session-error telemetry. Resumable, unknown, and local transport/decode failures
retain their existing reporting.
Deferred input also preserves the ordering of one bounded, cancellation-aware paste
batch. Accepted prefixes are not replayed, later discrete input waits behind text,
and cancellation removes only unsent text. Rejected paste admission emits
text-input-error with startId and a fixed reason, through the existing ABI 13
JSON callback. It is a nonterminal retry notice, not a stream failure; Qt discards
stale generations and shows feedback over the current video item.
After a decoder-stall recovery attempt, the native engine allows one further video-timeout
interval for decoded output to resume. Output progress or a decoder-epoch change clears
that deadline. Otherwise the engine emits nvst-recovery-exhausted and a stopped status
once, allowing Qt to recover the session instead of leaving silent media connected forever.
This does not classify the remote cloud session as ended.
Implemented core methods
Game artwork
GraphQL-backed game objects expose nullable artwork URL strings: imageUrl prefers
GAME_BOX_ART, heroImageUrl prefers hero/banner imagery, and keyArtUrl prefers
NVIDIA KEY_ART with KEY_IMAGE as a fallback. Console Home uses keyArtUrl for
square tiles while retaining hero imagery for wide tiles. If key art is absent,
the shell falls back to imageUrl, then heroImageUrl. Older cached objects and
public-catalog games may omit keyArtUrl; it is an optional, additive field in
protocol 1 and does not change the handshake or existing artwork fields.
Store pagination (catalog.storePages.v1)
The protocol-1 envelope and 1 MiB limit are unchanged. This additive capability
advertises cursor pagination and separate storefront presentation. The existing
catalog.store.list method now caps limit at 100 (default 100), returning one
complete upstream page instead of aggregating thousands of games.
Fresh upstream pages request up to 100 games. Existing cached pages may contain fewer games; always follow the returned cursor rather than assuming a full page has the requested count.
Request: { "limit":100, "cursor":"", "searchQuery":"" }. Cursor is an opaque
string (at most 4096 UTF-8 bytes); search is at most 512 UTF-8 bytes. Response:
{ "games":[], "count":0, "totalCount":0, "hasNextPage":false, "nextCursor":"", "source":"store-browse", "fetchedAt":0 }.
Pass nextCursor unchanged to the next call with the same search. A final page
has hasNextPage:false; empty non-final pages may advance only when the upstream supplies an advancing cursor. Invalid mapped identities are errors.
Missing, repeated or oversized continuation cursors are errors, not completion.
Each result is limited to 768 KiB after JSON encoding, leaving room for the
envelope. Oversized pages are refetched with a smaller count at the same cursor;
they are never truncated while advancing the cursor. A single oversized game
returns catalog_response_too_large without disrupting the core connection.
catalog.store.presentation accepts { "section":"marquee" } (also panels
or filters) and returns { "section":"marquee", "items":[] }, independently
bounded to 768 KiB. Failed/oversized optional sections do not fail game pages.
Store pages and presentation results include cacheHit (boolean). Successful
responses are persisted under the core data directory in store-cache-v1, with
hashed account/provider/membership/proxy/locale and request keys. Credentials
are not stored. Reads remain bounded to 768 KiB; the cache is limited to 64 MiB
and 512 entries. Missing or corrupt entries refetch normally. There is no timed
catalog invalidation: an optional refresh:true on a first-page request clears
that account/context's pages and presentation before fetching. Continuations
must omit it or send false. Other accounts' entries are unaffected.
Concurrent misses for the same cache key and refresh epoch share one successful
fetch. Store network requests (including server metadata, presentation fallbacks,
and oversized-page retries) are serialized with at least 50 ms between them.
HTTP 429 starts a core-wide Store cooldown using Retry-After (seconds or HTTP
date), or 60 seconds when it is absent or invalid. Uncached requests during the
cooldown return rate_limited without network traffic; cached responses remain
available. The core does not automatically retry a rate-limited request.
Server metadata lookups share one bounded, in-memory cache across Store, library,
and subscription requests. A successful lookup is reused for five minutes, scoped
by provider endpoint, account, and token fingerprint; concurrent callers share
the lookup. Ordinary failures use the same context's last known value (or
GFN-PC when none exists) for 30 seconds before retrying. Rate-limit and
cancellation errors propagate instead of becoming cached fallback values.
The shell serializes game requests, merges by stable game identity, and retains loaded games and the failed cursor on error. Retries resume that page. Search/account changes cancel requests before clearing state; late responses are ignored.
Local Store browsing (catalog.storeLocal.v1)
catalog.store.local pages and searches the saved catalog, without replaying
every cached page into Qt. It accepts limit (capped at 60), cursor,
searchQuery, and optional genre, store, and categoryId strings (at most
256 UTF-8 bytes each). A cursor belongs to its search/filter context and must
be returned unchanged. The existing 768 KiB result budget still applies.
The result includes games, count, totalCount (matching games),
catalogTotalCount, hasNextPage, nextCursor, source:"store-local",
cacheHit:true, and cacheComplete. First pages also include facets with
all indexed genres, stores, and official categories (id, label, count),
not just those present on the visible page. Subsequent pages omit facet data
by returning facets:null. categoryId:"all" selects the entire catalog.
The core builds one bounded, account-scoped metadata index from saved pages; full records remain on disk and only selected results are materialized. Search ranks exact titles, acronyms, prefixes, reordered words and single typing errors, with owned games preferred on close matches. Store requests 40 results per page; Ctrl+K uses the same algorithm with a six-result limit and debounced, cancellable requests.
There is no automatic catalog crawl. Scroll/navigation demand or Load more
requests the next page. A missing/partial cache fetches bounded upstream pages
on demand; cacheComplete:false distinguishes this from a complete index.
On this method, refresh:true rebuilds the local index without deleting saved
pages. The upstream catalog.store.list refresh behavior remains unchanged.
catalog.store.presentation also accepts metadataOnly:true. For panels,
each section returns its title and totalCount with an empty games array;
the complete panel remains cached in the core. Qt materializes shelf games
and artwork only near the viewport, using the section's local category ID
(shelf:<panel index>:<section index>). See all opens that category in Store.
Method list
-
core.hello -
app.status -
settings.get -
settings.choices.get -
settings.set -
settings.shortcuts.update -
settings.reset -
auth.providers.list -
auth.session.get -
auth.device.start -
auth.device.poll -
auth.device.complete -
auth.device.cancel -
auth.logout -
auth.accounts.logoutAll -
auth.accounts.list -
auth.accounts.switch -
auth.accounts.remove -
auth.pin.status,auth.pin.set,auth.pin.clear,auth.pin.verify -
catalog.public.list -
catalog.library.listreturns one bounded upstream page, not an aggregate library. -
catalog.game.get,catalog.definitions.get,catalog.languages.get -
catalog.launch.inspect,catalog.favorites.list -
catalog.launch.store.inspectresolves the eligible Steam store-client launch target. -
catalog.favorites.add,catalog.favorites.remove -
catalog.ownership.add,catalog.ownership.remove,catalog.ownership.select -
catalog.store.list,catalog.store.local,catalog.store.presentation -
network.regions.list -
network.regions.ping -
queue.servers.list -
account.subscription.get -
account.connections.list,account.connections.sync,account.connections.unlink -
account.connections.sync.status,account.connections.sync.cancel -
account.connections.link.start,account.connections.link.poll -
account.storage.locations,account.storage.reset -
session.create -
session.poll -
session.stop -
session.ended -
session.active.get -
session.remote.list,session.claim,session.ad.report -
streamer.detect -
streamer.prepare -
streamer.start -
streamer.status.get -
streamer.stop -
streamer.input.pause,streamer.control,streamer.surface.update -
streamer.recording.start,streamer.recording.stop -
diagnostics.snapshot,diagnostics.export,acceptance.export -
media.root.get,media.recording.target,media.list,media.delete -
cache.delete -
queue.status.get,queue.serverMapping.get -
thanks.data.get,communityProxy.provision -
updater.state.get,updater.check,updater.download,updater.install,updater.startup.ack -
updater.highlights.get,updater.highlights.ack -
social.capabilities.get -
discord.activity.sync,discord.activity.clear -
feedback.submit,bug_report.submit,bug_report.incident,analytics.track
Usage & bug reports (automaticBugReports.v2)
automaticBugReports.v2 replaces automaticBugReports.v1 and removes
telemetry.sync and the optInTelemetry capability. The core owns every
network call: reports go to POST {base}/v1/reports and usage events to
POST {base}/v1/events, where base is https://opennow-reports-production.up.railway.app unless the
OPENNOW_REPORTS_API environment variable names another http(s) origin when
the core starts.
One setting, automaticBugReports (unset, enabled, disabled), labelled
"Usage & bug reports", gates automatic reports and usage events. unset means
the notice has not been answered and is treated as enabled while OpenNOW is
experimental. Loading settings migrates the legacy errorReportingConsent:
denied together with unset becomes disabled; the legacy key is otherwise
inert. settings.set for automaticBugReports accepts an optional source
(signin_notice, first_run_sheet, or settings, default settings). Every
enabled or disabled write queues one anonymous consent_changed event
(account is null) even when the new value is disabled. A disabled write
first deletes the queued events, the event spool, and pending reports; the core
does the same at startup when the setting is already disabled.
Reports
Every report is multipart form data with a report part (JSON, at most 64 KB)
and an optional log file part (application/gzip, at most 5 MB compressed)
holding the redacted diagnostics export:
{"schemaVersion":1, "automatic":true, "installId":"32 hex",
"account":{"userId":"…", "providerIdpId":"…", "providerCode":"NVIDIA",
"providerName":"NVIDIA", "alliancePartner":false, "reporter":"Zortos",
"reporterBasis":"username", "membershipTier":"ULTIMATE"},
"trigger":{"kind":"frame_drops", "code":"sustained_frame_drops", "message":"…",
"metrics":{"droppedFrames":412, "windowSeconds":60}},
"activity":{"currentGame":{"title":"Cyberpunk 2077", "appId":"100"},
"recentGames":[{"title":"…", "appId":"…"}]},
"app":{"version":"1.0.3", "os":"windows", "arch":"x86_64", "gpu":"NVIDIA RTX 4070",
"decoderBackend":"d3d11", "channel":"stable"}}
Automatic reports carry trigger; manual reports set automatic:false and carry
manual:{title, description} instead. account is null when no account is
signed in. reporterBasis is username, email, or none. gpu and
decoderBackend come from the latest runtime capabilities the shell sent and may
be null.
The core triggers an automatic report when session.create, session.poll,
session.claim, streamer.prepare, streamer.start, or catalog.library.list
fails with a code that is not a user action or account state (for example
cancelled, stale_account, or session_conflict are ignored).
session.create also records the launched title in the diagnostics log and the
recent-games list attached to every report.
The Qt shell reports in-process media problems with bug_report.incident:
kind is stream_error or frame_drops, code is a lowercase identifier,
message is redacted and bounded, and metrics copies only the numeric fields
droppedFrames, windowSeconds, framesPerSecond, packetLossPercent,
pingMs, and decodeTimeMs. The result is {accepted:true} or
{accepted:false, reason} (disabled, signed_out, already_reported).
Each kind and code pair is reported once per core run, at most five reports per
run, at least 30 seconds apart. Only a signed-in account triggers automatic
reports.
Accepted automatic reports upload in the background and publish
bug_report.changed events with state sending, then sent (with
reportId and issueStatus, for example investigating) or failed (with
message and queued), plus kind, code, and the current game title.
bug_report.submit takes {title (8–120 characters), description (40–12,000), includeDiagnostics} and returns {submitted:true, reportId, issueStatus}.
feedback.submit takes {category: bug|idea|other, message (8–4,000), includeSystemInfo} and sends a manual report titled Feedback: <category>
without an account; without includeSystemInfo it omits the game activity, GPU,
and decoder backend. Both return {submitted:false, queued:true} when the upload
was queued for retry.
A network failure, or an error response whose error.retryable is true (or a
408, 429, or 5xx without that field), writes the report and its compressed log
to <data_dir>/reports/pending/. The core keeps at most five pending reports, no
older than seven days, and retries them oldest first after the first sign-in of
the next run, stopping at the first retryable failure. A non-retryable error
drops the report.
Usage events
analytics.track takes {event, props, uiSurface?}. uiSurface is desktop
or console; the core remembers it for events it emits itself. The shell may
send these events, and the core keeps only the listed properties that pass
validation (unknown events are invalid_params; invalid properties are dropped):
| Event | Properties |
|---|---|
session_started |
game_id, game_title, codec (h264/h265/av1), resolution (<w>x<h>), fps_target, hdr, decoder_backend, first_frame_ms, queue_wait_s |
session_ended |
game_id, game_title, duration_s, outcome, error_code, recoveries, video_drop_count, avg_fps, avg_ping_ms, avg_packet_loss_pct, decoder_errors |
session_error |
stage (create, poll, claim, prepare, start, stream, presentation), code, game_id |
frame_drops_detected |
dropped, window_s, game_id, decoder_backend |
outcome is clean when the user ends a session that presented video, user_stopped
when the user ends it before the first frame, remote_ended when the cloud
session ends, and error when the stream had failed. Codes are
[a-z0-9_]{1,64}; identifiers are [A-Za-z0-9_.:-]{1,64}; numbers are finite
and non-negative.
{event:"app_opened", runtimeCapabilities} is the one exception: the shell sends
it once the native runtime handshake finishes, and the core sends app_opened
once per run with gpu_vendor and package_kind derived from those
capabilities and the installation. The core also emits signed_in
(auth.device.complete with restored:false; a restored or switched account
with restored:true), game_launch_requested (session.create, from its
appId, title, store, and zone), session_error and library_load_failed
for the failures that trigger automatic reports, bug_report_sent after a
report is accepted, and consent_changed. Each event gets app_version, os,
arch, ui_surface, and channel.
The result is {accepted:true} or {accepted:false, reason}. Events are
queued in memory (at most 1,000; overflow drops the oldest and is logged in
diagnostics) and sent as {installId, account:{userId, providerIdpId}|null, events:[{event, ts, props}]} batches of at most 100 events every 30 seconds,
at 50 queued events, and at shutdown within one second. Failed batches are
appended to <data_dir>/analytics/spool.jsonl (at most 1 MB, oldest batches
dropped first) and resent after the next successful send or at the next start.
diagnostics.export optionally accepts embeddedStream.drops and
lastSessionReport.drops from the Qt session owner. Each contains the cumulative
videoDropCount (frames), audioDiscardedMs (decoded audio duration),
audioPacketDropCount (audio packets/PCM blocks with unknown duration),
callbackDropCount (Qt callbacks), and otherQueueDropCount (unclassified items).
The core copies only bounded, non-negative numeric counters into the export's
shell section; it does not export arbitrary caller-provided fields. These
counters survive embedded-runtime stop and remain separate from the core's
process-streamer snapshot and its legacy mixed-unit queueDropCount.
diagnostics.export also optionally accepts runtimeCapabilities from the
in-process Qt streamer. The export's separate nativeRuntime section preserves
allowlisted backend and codec availability, HDR support, and bounded, redacted
failure reasons, even before a stream starts. It does not copy arbitrary runtime
fields or treat an empty process-streamer snapshot as the embedded capabilities.
Session resume and reconnect
session.active.get without hints remains a local-only lookup. After a core
restart, Qt can reconcile an existing native stream by supplying
{sessionId, ownerScope: {userId, providerIdpId}} after authentication is restored.
Both hints are required together. The session ID must contain 1–256 ASCII letters,
digits, hyphens, or underscores; each owner identity must contain 1–1024 bytes and
match the authenticated selected account. An optional old ownerScope.generation
is ignored because generations are process-local. Caller-supplied endpoints are
ignored.
Hinted reconciliation discovers the exact seat through authenticated, core-owned
provider routes and reads its current state with GET. It restores local control
context and ownership without RESUME/PUT, allocation, or native transport changes.
An already-owned matching seat returns its current local state. Another seat or
owner fails with session_owner_mismatch. Successful results use the existing
{session, scope} shape and publish the current generation in scope and
session.ownerScope, preserving the remote phase without adding resumePending.
A missing discovery match fails with session_discovery_failed; authentication,
network, cancellation, and stale-account failures remain errors. Local absence is
not termination. Only an exact-seat GET reporting status 7 or HTTP 404 confirms
termination. Status 7 includes session.termination; HTTP 404 returns
{session: null, termination: {source: "cloudmatch-http", httpStatus: 404, sessionId, resumable: false}, scope}. Qt keeps the native stream alive while
retrying reconciliation errors and resumes ordinary session polling after local
ownership is restored.
Scope-checked discovery also authorizes exact-seat cleanup if reconciliation is
cancelled before active ownership is adopted. A later account generation cannot
reuse that discovery to stop a seat.
session.remote.list checks the selected endpoint and the regions advertised by
CloudMatch instead of treating the first empty regional response as authoritative.
Discovery deduplicates session IDs and uses at most four concurrent requests, a
three-second per-request timeout, a 12-second total budget (including region
discovery), and at most 32 regional endpoints. If no sessions were found but a
region failed, returned invalid data, or could not be checked within these bounds,
the request fails with session_discovery_failed rather than returning an empty
list. HTTP 401 remains http_unauthorized after at most one safe-read renewal;
HTTP 403 remains authentication_required. A found session
can be returned even when another region fails; an empty successful list means
all discovered regions were checked successfully. Callers must not create a new
session after a discovery failure.
Provider routing and account scope
auth.providers.list returns providers, defaultProviderIdpId, generation, and
discovery: {state, message, retryAfterMs}. Successful discovery is fresh for
15 minutes. A failed refresh retains the last known providers and reports
state: "degraded". Without a discovered list, the response includes the restored
provider, when present, and an explicit NVIDIA fallback. This fallback is not
authoritative discovery. Retries wait at least 30 seconds; HTTP 429 Retry-After
can extend the wait up to one hour. Qt performs at most three automatic retries.
An explicit unknown providerIdpId fails with provider_unavailable rather than
selecting another provider. Endpoint updates reconcile by exact IDP identity.
Authenticated catalog and account reads include
scope: {generation, providerIdpId, userId}. Core reads capture private ServiceId
credentials and reject obsolete account/provider generations before publishing.
HTTP 401 permits one renewal and one replay of a safe read for the same owner.
HTTP 403 does not trigger renewal. Create, claim, account sync/unlink, and storage
reset do not replay mutations after an ambiguous response.
Authenticated VPC lookup requires a successful server-info response with a
nonempty requestStatus.serverId. Missing or rejected metadata is an error,
not a successful GFN-PC library. VPC cache entries are scoped by provider route,
account, credential, generation, and proxy, with coalescing within each scope.
Library and VPC requests use the same selected proxy. The core does not silently
retry a selected proxy directly. Authenticated HTTP clients do not follow redirects.
LCARS retains its configured shared endpoint; an Alliance provider ID does not
select GFNPartnerJWT or invent a GraphQL hostname.
GFN service transport failures, including server-info lookup, keep the
network_error code. When the HTTP client identifies the failed stage, the
message ends with (dns), (connect), (tls), or (timeout); the message
never includes the request URL or host. When an Alliance (non-NVIDIA) provider's
server-info lookup for VPC or region discovery fails at the dns stage, the
network_error message instead says that the provider display name can only be
reached from inside its home country and network, asks the user to turn off any
VPN, proxy or custom DNS, and keeps the original failure after Details:. Library,
favorites, store, launch inspection, subscription and region reads share this
message; the shell displays it as received.
settings.set for region also requires the current providerIdpId. The core
atomically updates region, regionProviderIdpId, and the providerRegions map.
The metadata fields cannot be written separately. Existing unscoped preferences
remain eligible only for NVIDIA. Region overrides must occur in the current
provider's server-info list. An unavailable or incompatible override falls back
once to that provider's base without deleting the saved preference. Provider and
region bases must be HTTPS NVIDIA-grid names without userinfo or nonstandard ports.
Arbitrary partner domains require a separate evidenced trust policy.
Free-tier queue locations
queue.servers.list({}) returns {locations, recommendedZoneId}. Each location
contains zoneId, title, region, queuePosition (nonnegative integer),
etaMs (milliseconds or null), lastUpdated (Unix seconds), pingMs
(milliseconds or null), streamingBaseUrl, and alternateCount (the number of
other fresh zones folded into this location). Missing mapping entries retain
their raw zone ID as the title and a friendly continent name as the region.
Mapping failure does not prevent use of valid queue data. Mapping entries marked
nuked: true, malformed rows, non-NVIDIA zones, timestamps over 15 minutes old,
and timestamps more than 60 seconds in the future are excluded. No usable fresh
rows, invalid queue payloads, and HTTP failures return queue_servers_failed;
cancellation returns cancelled.
The core requests PrintedWaste's public queue and mapping endpoints without
credentials, account identifiers, cookies, proxies, or redirects. Each fetch has
a five-second deadline and a 256 KiB streamed body limit, with at most 256 input
entries and 128 usable zones. Only strict NP-<3–8 uppercase alphanumeric location beginning with a letter>-<2 digits> identifiers generate a probe or
launch URL: https://<lowercase-zone>.cloudmatchbeta.nvidiagrid.net/. Neither
provider payload can supply an arbitrary host. Latency uses a TCP warm-up and two
TCP connection samples, each bounded to 750 ms across all resolved addresses,
with 50 ms between samples. Probes run in batches of at most 32 and check
cancellation between samples and batches. DNS resolution has a 750 ms caller
deadline, uses at most 32 resolver workers and 32 queued jobs, and returns at most
eight addresses per host. Stalled system DNS calls cannot block the caller or
spawn additional workers; expired/cancelled jobs are skipped before resolution.
pingMs is the rounded-up mean of successful TCP samples, excluding DNS, TLS,
and server processing. All-failed probes produce null latency, not fabricated
ping values.
Zones sharing a title and region are grouped. Each primary and the final
recommendation prefer measured zones when available, then minimize a normalized
75% latency / 25% queue score. A score winner above 100 ms is replaced by the
lowest-latency candidate. Without measurements the shortest queue wins. Ties
are deterministic. recommendedZoneId always names a returned location primary;
that row sorts first, with remaining rows ordered by region and title.
The desktop shell presents this selector only for an explicitly known FREE
NVIDIA membership, not for unknown membership or alliance accounts.
hideQueueSelector is a persisted boolean preference, default false, exposed
through the standard settings API and boolean normalization. It does not change
the separate region-selector preference. The public queue RPC is unauthenticated
and does not itself authorize gameplay or infer membership.
For a fresh NVIDIA launch, the shell may pass a selected location's exact zone
and streamingBaseUrl to session.create. The core accepts a strict zone and
its exact derived URL for the NVIDIA IDP and NVIDIA provider code even when that
zone is absent from server-info discovery. This exception does not apply to
alliance providers, does not alter persisted region preferences, and does not
bypass account scope, catalog eligibility, or subscription checks. All other
region overrides retain the provider-discovery rules above.
session.create requires catalogAppId as the parent LCARS identifier,
variantId as the selected positive GraphQL Int identifier encoded as a string,
and appId equal to that exact variant ID. scope must contain the current
generation, userId, and providerIdpId. The core resolves fresh catalog and
account metadata and applies the same decision as catalog.launch.inspect
immediately before allocation. Only ready admits a fresh allocation. A decision
from an earlier inspection is not a transferable permission. Missing, foreign,
or mismatched identifiers do not fall back to another variant or a title.
Existing validated seat claims remain separate and never write ownership.
session.create acquires a single typed CloudMatch admission guard before provider
discovery, authentication, or route locks. A concurrent create returns
session_update_busy immediately instead of waiting to allocate after the first
request fails or is cancelled. Pre-allocation failure releases the guard; after
an allocation exists, the existing receipt and exact-seat cleanup state continue
to prevent another allocation.
CloudMatch requests serialize with account changes. An active seat belongs to
its exact session ID, user ID, and provider IDP, independently of the account
generation. Returning from account A to B to A, clearing caches, or signing in
again as A does not revoke A's ownership. New owned-seat operations publish the
current generation and retain the core-captured control and media endpoints.
An active seat retains its original account for polling and exact-seat cleanup
after a switch or logout.
If that retained credential expires, session_owner_authentication_required
asks the user to return to the original account without restarting media.
New-account credentials never authorize requests to the retained seat. When the
selected account matches that owner, explicit cleanup renews expired ServiceId
credentials before issuing DELETE. A rejected DELETE is not automatically replayed.
Session results include ownerScope inside session; Qt distinguishes updates
for its existing native session from unrelated old-account responses. Ordinary
asynchronous results, discovered seats, and catalog results remain generation
fenced. A new allocation's receipt retains its original generation even when
the active seat is republished under a newer generation; an obsolete receipt
still triggers exact-seat compensation.
Qt accepts authoritative terminal status 7 or HTTP 404 for the exact displayed
session and its user/provider identity even when the result's generation is old.
This exception applies before ordinary response and session.changed scope
filters. It does not admit stale nonterminal updates, another account/provider,
another session ID, or a resumable or non-authoritative termination. Duplicate
terminal delivery cannot end a replacement seat.
streamer.prepare uses the caller's session ID to resolve the current core-owned
active seat. Caller-supplied connection endpoints are ignored. The response also
returns the owned session with its current ownerScope, which Qt retains for
later session events. Foreign ownership or an unknown seat fails with
session_owner_mismatch, a non-ready seat with
session_not_ready, and missing RTSPS endpoints with session_endpoint_missing.
The existing negotiated profile checks still run. Preparation does not expose
OAuth tokens to Qt or alter the native /rtsp websocket session-ID authentication.
These fields are additive to protocol 5; allocation receipts and exact-seat
compensation remain unchanged.
session.create reports an existing-session limit as session_conflict, including
CloudMatch status 11, SESSION_LIMIT descriptions, and unified error
4AF1201E, including structured session-limit responses with HTTP 403. An
unrecognized HTTP 403 remains authentication_required; HTTP 401 is
http_unauthorized. Session creation is never automatically replayed. The
rejected request never becomes an active local session. The shell
should call session.remote.list once and offer to resume or end the existing
session instead of displaying the raw vendor error or retrying creation. When the
create response supplies usable otherUserSessions or session details, the core
normalizes them to the ordinary discovery descriptors and hands them to the next
list request without another network lookup. This handoff is account-scoped,
consumed once, and expires after 30 seconds; it is not a persistent discovery
fallback. The code/message error envelope and protocol version are unchanged.
session.claim first queries the trusted seat host returned by discovery, including
conflict-response handoffs whose create region may not own the existing session.
If that host fails for a reason other than authentication, it falls back to the regional
endpoint. The shell refreshes the chosen session's descriptor before retrying a failed
claim, without substituting another game or silently creating a new session.
session.claim discovers the session's actual control server, sends the minimal
action: 2, data: "RESUME" request for a ready, streaming, or paused seat, and returns a session
with resumePending: true and phase: "resuming". It preserves the stable device
identity and existing launch mode; it does not renegotiate codec, resolution, FPS,
or bitrate. An initializing (1) or resuming (6) seat is polled without repeating
the mutation. Discovery includes paused (4/5) and resuming seats so they remain
available to resume and reconnect. Finished or unknown states reject the claim.
The PUT acknowledgement is not stream readiness. Call session.poll until a fresh
GET has a successful CloudMatch request status (statusCode: 1), session status
2 or 3, and nonempty native RTSPS endpoints. Only then does the core clear
resumePending and expose the ready/streaming phase. Transient status 6 continues
to report resuming; finished or unknown poll states clear resumePending and
report failed. A RESUME response of SESSION_NOT_PAUSED (statusCode: 34)
also proceeds to polling, including on an HTTP error response. Authentication
failures and other transport/API failures remain typed RPC errors.
Qt polls every 1.5 seconds with only one request outstanding, bounded by 60 polls
and a 90-second deadline checked between requests. Native connection recovery first
stops the old media transport, discovers the same session ID through
session.remote.list, then claims/polls it and calls streamer.prepare for fresh
connection context. It never creates a replacement cloud game or claims a different
session. During recovery, session.remote.list accepts the active sessionId so the
core can use its remembered regional service rather than the native server IP.
Failed recovery attempts back off up to eight seconds and stop after eight
attempts; only a presented first frame resets this budget. Ending the session cancels
recovery. A native stop stalled for 30 seconds reports an error without launching
another transport over the still-owned resources.
An exhausted video SETUP negotiation (missing-video-peer) or an explicitly
unsupported legacy transport (nvst-legacy-transport-unsupported) stops automatic
recovery and preserves the original error and owned seat for an explicit retry or
stop. These compatibility failures do not trigger another claim of the same seat.
For the embedded Qt client, session.create also accepts an optional numeric maxEntitledFps:
the highest frame rate the signed-in membership entitles at the requested resolution, or 0
or absent when that is not confirmed. Qt derives it from the normalized entitledResolutions
entries it already displays; the core never invents it. The requested frame rate is bounded by
the documented resolution ceiling (1920x1080 and 1920x1200 top out at 360 FPS, every other
resolution at 240 FPS) and, above 240 FPS, by both a hardware decoder for the selected codec
confirmed in runtimeCapabilities and an entitlement limit that covers the requested rate.
An absent or software-only capability probe and an absent or lower entitlement limit both bound
the request to the unconditional 240 FPS ceiling, so the saved preference cannot request the
conditional tier without affirmative evidence. This is a necessary condition, not a throughput
qualification: the client does not measure decoder throughput, and CloudMatch remains the
authority on the finalized profile.
Rates snap to 30, 60, 90, 120, 144, 165, 240, or 360 FPS before allocation.
Embedded codec limits below can reduce the request further.
For the embedded Qt client, session.create and streamer.prepare accept an optional
runtimeCapabilities object copied from the in-process streamer's protocol-7 hello response.
The core filters its available videoBackends by the persisted nativeVideoBackend preference
and resolves codec auto to AV1, HEVC, then H.264 for both SDR and HDR (subject to requested color mode) before
CloudMatch allocation. This resolution is session-local: the saved preference stays auto.
Each codec entry may include colorQualities, an authoritative array of supported settings
values such as 8bit_420 and 10bit_420. An empty array means no supported color modes.
The embedded Linux runtime publishes this field for every codec: Vulkan values come from the
attached device's actual decode profiles, while non-Vulkan Linux paths report only 8-bit 4:2:0.
The core filters codecs by the requested color mode before both Auto and manual selection, so
an HEVC decoder supporting Main but not Main10 cannot allocate a 10-bit session, and the shared
Vulkan path cannot allocate 4:4:4. Missing or malformed advanced-color profile information on
Linux/Vulkan fails closed; other platforms retain their existing behavior when this optional
field is absent. The selected codec and color remain session-local and never downgrade the
user's requested color mode.
Manual unavailable codecs/backends return streamer_codec_unavailable or
streamer_backend_unavailable, respectively. streamer.prepare also validates the negotiated
codec on resume; it never changes the codec of an already allocated stream. Older callers without
this optional object retain the external-streamer probe path. The additive fields do not change
the JSON protocol version or native FFI ABI.
Windows graphics preference
settings.get, settings.set, and settings.reset expose windowsGpuDeviceId.
The default empty string selects Automatic. Explicit values are opaque device
identities, limited to 1024 UTF-8 bytes with no NUL characters. Invalid persisted
values normalize to Automatic; invalid writes are rejected without changing the
saved preference.
Before creating the Qt graphics device, the shell may run:
opennow-core --graphics-preferences
This mode emits one JSON line, then exits without initializing account, network, catalog, telemetry, or streaming services:
{"version":1,"windowsGpuDeviceId":""}
It uses the normal data-directory resolution, including --data-dir,
OPENNOW_DATA_DIR, and legacy-directory discovery. The read is limited to 1 MiB
and never saves migrations, creates directories, or renames corrupt settings.
Missing, corrupt, or oversized input selects Automatic. Qt bounds the subprocess
and its output and also uses Automatic if bootstrap fails.
Qt resolves the saved identity to a current-boot Windows adapter LUID. The same LUID selects Qt's D3D11 adapter and the native runtime's capability probes; LUIDs are not persisted. A missing saved GPU falls back for that launch without erasing the preference. The settings selector appears only with at least two detected hardware adapters, excluding software adapters. It is on the Stream settings page. Saving a different GPU affects the next application launch, not the active graphics device or session.
Adapters are enumerated high-performance first. Before that launch, each adapter is indexed for H.264, HEVC, and AV1 hardware decode profiles at 1920×1080 or 1280×720. Automatic uses the first adapter in that order that exposes one of those profiles. A hybrid laptop whose discrete GPU has no decoder, such as a GeForce MX110 beside Intel HD Graphics 620, therefore uses the integrated GPU instead of failing the session. An explicit saved GPU is still used even when its index is empty. Each settings choice lists the codecs that index found.
The embedded streamer's protocol-7 hello may include graphicsAdapters. The
field is omitted when no adapters were indexed. Each entry has name, active,
codecs (h264, h265, av1), h265Main10, and an optional reason. It does
not include the adapter LUID. active marks the adapter selected for that
process. When no hardware backend is available and another indexed adapter can
decode, the session error names that GPU and points to Settings → Stream →
Graphics processor. Diagnostics copy the same allowlisted fields.
Recording and replay capture
The Qt/native recorder and replay exporter preserve the negotiated source video and
Opus game audio in Matroska without decoding or re-encoding. Recording resolution,
frame rate and bitrate follow the stream; the retained legacy recordingResolution,
recordingFps and recordingBitrateMbps preferences do not configure native capture.
settings.get / settings.set expose replayBufferEnabled (default false),
replayBufferSeconds (default 30, clamped to 15–120), replayBufferMemoryMiB
(default 256, clamped to 64–512), and shortcutSaveClip (default Ctrl+F12).
streamer.prepare includes these settings in the session context and maps
shortcutSaveClip to shortcuts.saveClip. Enabling replay and changing its limits
apply to the next native session. Disabling it sends replay-stop immediately,
clears buffered media and cancels an in-progress clip export.
These commands use the embedded streamer's protocol-7 JSON payload without changing the C ABI:
- Manual
recording-startuses its commandidas the recording identity. Arecording-stateterminal event carries that identity asrequestIdand astateofsavedorfailed. A saved result includespath,videoPackets,audioPackets, andcompletion. Normal completion is{"kind":"complete"}. A preserved valid prefix is{"kind":"cut","reason":"discontinuity"},{"kind":"cut","reason":"queue-overflow"}, or{"kind":"cut","reason":"interrupted"}. A cut stops manual recording and produces a visible early-save notice; it does not start another file or change replay capture. recording-stoppedrepeats the terminal result and its originatingrequestId; itsidstill identifies the stop command. Qt applies a correlated terminal result once, whether the event or stop response arrives first. A repeated stop returnsrecording-not-activewithout replacing an earlier cut or failure. Packet-write, trailer, publication, and no-valid-keyframe failures remain failures, not saved prefixes.- Completion metadata and event correlation are additive protocol-7 fields. Qt ignores uncorrelated terminal events and stale recording identities. A missing completion field means ordinary saved output only on an authoritative, correlated stop response. Historical producers without correlated terminal events do not provide the new unsolicited-completion behavior. These fields do not guarantee callback delivery or preservation after a process crash.
- The
startresponse includesreplayEnabledfor the actual session. clip-saveacceptsidand an absolute.mkvoutputPathallocated bymedia.recording.target. It returnsclip-savingpromptly or a typed error if replay is disabled, not yet decodable, or another export is still running.- A
clip-stateevent reportsstate(savedorfailed),requestId,pathandmessage. The shell correlatesrequestIdwith the outstanding export and ignores completion from a previous session. Cancelled exports do not publish a completed file or a stale success event. replay-stopreturnsreplay-stopped. A new session is required to enable buffering again.
Replay retains encoded packets with bounded memory, frame count and duration.
Clips start on a retained video keyframe, so their length may be shorter than the
requested duration. Export transfers the retained buffer to a single worker;
buffering rebuilds from a subsequent keyframe within the remaining memory budget.
There is no assumed periodic-keyframe guarantee: when a whole GOP exceeds the
configured limit, replay returns replay-not-ready until a new source keyframe.
Capture does not issue periodic keyframe requests that would change stream traffic.
Discontinuity or producer contention clears replay history rather than blocking
playback or publishing a clip with missing references. There is no additional
video encoder or GPU readback. Packet bookkeeping, container muxing and disk I/O
still consume CPU and bandwidth; zero CPU usage or zero performance impact is not
a supported guarantee.
HDR session contract
settings.enableHdr is a persisted boolean with default false; HDR requires explicit user
opt-in. Qt adds nativeHdrSupported: boolean to params.runtimeCapabilities on each
session.create and streamer.prepare request. It must describe the actual stream window's
current HDR output, including the active monitor, compositor/OS HDR state, and presentation
surface support, not merely a GPU or decoder capability. Missing, false, or malformed values
deny HDR. This value is transient: settings.set rejects nativeHdrSupported, the settings
loader discards legacy copies, and the core never saves runtime capability results.
With HDR enabled, an HDR session needs an available hardware HEVC or AV1 decoder whose
colorQualities explicitly includes the requested ten-bit profile. The optional per-codec
hdrSupported: true permits 10bit_420 when colorQualities is absent, but does not establish
4:4:4 support. The optional per-codec hdrColorQualities array lists verified HDR profiles.
When present, it must contain the requested profile; empty or malformed values deny HDR.
HDR 4:4:4 requires an explicit 10bit_444 entry in both color-quality arrays.
Missing hdrColorQualities retains the existing HDR 4:2:0 checks only. Windows reports
explicit SDR color-quality lists and HDR support from actual decoded profile fixtures and GPU conversion;
it no longer infers advanced formats from an eight-bit codec probe. macOS HEVC HDR and
ten-bit 4:4:4 similarly require hardware-required fixture decode and Metal conversion.
Linux uses exact attached-device profiles for Vulkan Video. An explicit false or
malformed hdrSupported denies HDR even if 10-bit profiles exist. A true value never
overrides an explicit empty or incompatible colorQualities array. Neither setting
changes SDR capability filtering. HDR constrains the session-local color quality to ten
bits while preserving the selected chroma format and saved SDR color preference. HEVC
supports 10bit_420 and 10bit_444; AV1 remains limited to 10bit_420.
Unsupported color and HDR requests degrade before a seat is allocated instead of failing.
The core resolves them in this order and returns the effective codec, colorQuality,
enableHdr, resolution, and fps that
CloudMatch and the streamer use:
- Missing HDR output (
nativeHdrSupportednottrue) clears HDR. - Software decoding resolves to 8-bit 4:2:0 SDR.
- A 4:4:4 request selects HEVC, replacing Auto or any explicit codec, when the selected backend decodes HEVC at that 4:4:4 profile (or HEVC HDR 10-bit 4:4:4 with HDR). Otherwise the chroma becomes 4:2:0 and the bit depth is kept.
- HDR that the selected codec cannot decode is cleared. Explicit H.264 is SDR-only. Auto prefers AV1, then HEVC, then H.264 for both SDR and HDR, independent of bitrate and platform. When neither AV1 nor HEVC decodes HDR, Auto continues as SDR.
- Ten-bit SDR that the selected codec, or every Auto candidate, cannot decode falls back to 8-bit 4:2:0 BT.709.
- H.264 caps the frame rate at 120 FPS and the image area below 4,953,600 pixels, including explicit requests and Auto with only H.264 decode. Resolution reduction selects the closest aspect ratio among supported settings modes that fit the limits, then the largest image at that ratio. For example, 3440x1440 becomes 2560x1080.
- AV1 remains eligible for Auto at up to 120 FPS and 5120x2880 pixels. No runtime probe currently confirms higher AV1 frame rates, so explicit AV1 above 120 FPS also caps at 120.
- Each codec may report
maxDecodeDimensions:{width,height}inruntimeCapabilities. Both values are positive uint32 dimensions. Windows reports the decoder's enforced 4096x2304 envelope; the attached Linux Vulkan device reports the conservative intersection of its advertised color-profile limits; the opt-in MediaCodec bridge reports 2560x1440. Other producers omit unknown limits rather than estimating them. Core reduces oversized modes before allocation using the same closest-aspect rule. It rejects malformed limits or a request with no supported mode within the limits.
session.create records each applied fallback as a streamer/stream_profile_fallback
diagnostics event. An explicitly selected codec that the selected backend cannot decode at
all, an unavailable backend, or a backend that cannot decode 8-bit 4:2:0 with any candidate
still fails with streamer_codec_unavailable or streamer_backend_unavailable. The core
never substitutes another codec for an unavailable explicit codec except for the HEVC 4:4:4
rule above. streamer.prepare repeats the same resolution against the accepted session; when
the accepted codec, color quality, or HDR mode differs from what the current decoder can
present, it fails with streamer_color_unavailable instead of attaching a mismatched decoder.
Accepted native resolution and FPS override current saved preferences on attachment.
An accepted mode requiring resolution or FPS normalization fails with
streamer_mode_unavailable; preflight never changes an already allocated stream's mode.
Without HDR, the saved color preference is used, subject to exact hardware profiles and the
GFN codec restrictions below. Callers without embedded runtime
capabilities cannot request HDR through the external-streamer probe path.
CloudMatch receives sessionRequestData.sdrHdrMode=1 and monitor sdrHdrMode=1
only for this validated HDR request. requestedStreamingFeatures.trueHdr=false remains
separate because TrueHDR is the server's AI SDR-to-HDR filter, not native HDR. CloudMatch
uses bit-depth/chroma enums 1/0 for 10-bit 4:2:0 and 1/1 for 10-bit 4:4:4.
For HDR, monitor displayData carries validated output luminance
when the current output reports it. desiredContentMaxLuminance is the peak in nits;
desiredContentMinLuminance is the minimum in 0.0001-nit units, rounded after
multiplication by 10000. Wayland color-management supplies only this luminance pair.
desiredContentMaxFrameAverageLuminance is omitted for a pair-only snapshot because
Wayland exposes no comparable sustained full-frame value. When the runtime supplies
a complete validated optional group, the core also writes its full-frame nits into
that field and writes the red, green, blue, and white chromaticities as rounded
xy * 50000 integers in displayPrimaryX0/Y0, displayPrimaryX1/Y1,
displayPrimaryX2/Y2, and displayWhitePointX/Y, respectively. The official PC
client's Bifrost serializer confirms the field order and scales; the mapping from
the display's maximum full-frame luminance to the frame-average field is inferred
from native struct offsets, not an observed HDR session.
Without a validated output snapshot, HDR requests keep the fixed requested-content
defaults of maximum luminance 1000 nits, minimum luminance 0, and maximum frame-average
luminance 400 nits, matching the Mac native session payload. Those defaults are requested
content characteristics rather than measurements of the physical display and are not
presented as calibration. SDR sends displayData:null. HDR does not invent display
primaries or a white point; those fields require validated chromaticities from the
current runtime output.
The validated snapshot travels from Qt in runtimeCapabilities.nativeHdrDisplay as
minimumNits and maximumNits in cd/m², omitting either value the output does not
report. Optionally it also carries maximumFullFrameNits and normalized floating-point
redX/redY, greenX/greenY, blueX/blueY, and whiteX/whiteY. The core validates
the pair again and drops it when the bounds are not finite, negative, above 10000 cd/m²,
or not strictly increasing. It accepts the optional group only when every coordinate
is finite, within [0, 1], has a valid xy sum and positive y, the primaries form a
nondegenerate triangle, and minimumNits < maximumFullFrameNits <= maximumNits.
Missing or invalid optional fields discard the entire group but retain a valid pair.
The snapshot is transient:
settings.set rejects it, the settings loader discards persisted copies, and the core
never saves runtime capability results.
Stale snapshots are discarded rather than reused. Qt injects the snapshot only while the current output reports a validated range and removes any caller-supplied or previously injected value when it does not; the core strips any earlier snapshot from the resolved settings before carrying the current capability, so a display change that invalidates the output falls back to the requested-content defaults instead of replaying the previous display's luminance. Claim and resume requests do not carry monitor settings at all, so they cannot replay one either.
The normalized server response carries negotiatedStreamProfile.enableHdr: boolean. It
comes from the returned session's sdrHdrMode, then the returned monitor's mode, then the
returned session-request mode; missing or unsupported modes mean SDR. An explicit server
SDR response wins over saved HDR intent. trueHdr is not used to infer accepted dynamic
range. Resume preserves that returned mode rather than renegotiating from current settings.
The claim request intentionally omits monitor settings and requested streaming features, so
its only copied dynamic-range field is the accepted session sdrHdrMode. Fresh creation
sends the full request in its POST, with the requested session mode, monitor mode,
requested-content luminance, and trueHdr; only an existing-session claim uses PUT RESUME.
Attachment revalidates the session's HDR codec/color profile and current window output, so
moving to an SDR display cannot silently resume an HDR stream as SDR.
Fresh creation also applies the launched store version's catalog HDR support. When
enableHdr is on, the window output reports native HDR, and the exact variant that
catalog.launch.inspect validated for this launch has a features array without hdr,
the core requests that one session as SDR before resolving the embedded profile: the
request's enableHdr is false, so sdrHdrMode is 0, displayData is null, and
trueHdr stays false. Codec and color selection then run as for any SDR request. The saved
enableHdr preference is not changed. A variant whose features is null (the catalog
returned no feature list), a Steam store launch, and every case where HDR was not effectively
requested keep the request unchanged; missing metadata never downgrades HDR. The normalized
session carries hdrDowngrade: "game-unsupported" when this core downgraded the request,
otherwise null. Polls, resume, and reconnects preserve it only for the same session ID;
sessions this core did not create report null. Shells use it to explain the SDR stream and
must not repeat the catalog lookup. The session also carries catalogAppId, the parent catalog
game ID of the launch (appId stays the launched store version's CloudMatch ID), with the same
same-session preservation; it is null for sessions this core did not create. Shells key
once-per-game state on it, so every store version of a game shares one identity.
The normalized session also carries keyboardLayout when this core created or resumed
the session. It records the exact layout sent in the CloudMatch request, not the current
saved preference. Polls and ad updates preserve it only for the same session ID; a successful
resume replaces it with the newly requested layout. Qt uses this value for physical key
mapping, so changing settings during a stream does not change input before the remote
layout changes. An unclaimed session whose layout is unknown omits this field.
Color negotiation overlays each returned finalizedStreamingFeatures field on the server's
returned sessionRequestData.requestedStreamingFeatures. An empty or partial finalized object
must not erase the echoed codec, bit depth, or chroma. Explicit finalized values, including
invalid values, take precedence; missing values never come from current saved preferences.
CloudMatch chroma enums are 0 for 4:2:0 and 1 for 4:4:4; NVST chroma-format IDs 2 and
3 are not accepted as CloudMatch 4:4:4 values.
When present, session.negotiatedStreamProfile.codec takes precedence over the numeric
feature-map codec. H.264/AVC and H.265/HEVC names normalize to H264 and H265;
AV1 remains unchanged. An explicit null or unsupported codec stays unknown rather
than falling back to a requested codec. The request itself names no codec: like the
official client, codec selection stays client-side and reaches the seat in the RTSP
ANNOUNCE (x-nv-vqos bit-stream format), so a negotiated codec is only ever
server-reported (echo, finalized features, or a direct profile). When the server omits
every codec field, downstream stages resolve the codec from current saved preferences
instead. Polling, direct-server
responses, claims, and ad updates preserve that evidence only for the same session ID.
codecSource distinguishes request, server, and unreported; a reported codec supersedes
the request and remains authoritative in later partial responses. Unknown discovered sessions
never borrow a codec from current saved preferences. Preparation failures log bounded
codec/color evidence and a redacted reason, never the full session or credentials.
Embedded session preflight rejects H.264 with advanced color and AV1 with 4:4:4 before allocation, even if a decoder capability lists those formats. These combinations are not requested by the supported GFN wire policy. Auto selects HEVC for 4:4:4 rather than silently reducing chroma; an explicit incompatible codec remains an error.
The native context preserves the resolved profile and codec provenance. Its accepted
enableHdr initializes the native HDR mode (missing means false). Invalid accepted HDR
profiles are rejected before stream startup. NVST ANNOUNCE states color explicitly on
every session using literal bit depth 8 or 10 with chroma_format_idc
(chromaFormat=1 for 4:2:0, 3 for 4:4:4); dynamicRangeMode=1 is sent for HDR
only, and SDR omits the line. This matches the vendor capture of a 10bit_420
session (bitDepth:10 chromaFormat:1) and the working third-party reference
clients: a lone bitDepth line is never sent, because seats cannot initialize
an encoder from an incomplete color spec. The internal 0/1 chroma value from the
client's app-to-NVST conversion is mapped back to idc at SDP emission and never
reaches the wire. CloudMatch keeps its own bit-depth enum (0 or 1) with
chroma 0/1.
The ANNOUNCE also carries the encoder identity the seat reads before
initializing (maxCodecProfile/maxCodecLevel and the maxH264 pair, profile
3 / level 61, as captured). One resolved configuration feeds the wire values,
the media runtime, and the decoder, so a server color choice cannot leave the
decoder expecting a different format. The stored CloudMatch profile and user
preferences are not rewritten. Full SDP must not be logged because it contains
ICE credentials and encryption material.
After an update check, updater.highlights.get returns the latest published
release notes for the selected channel, even when that release is equal to or
older than the installed app. Its version and title identify that published
release, independently of updater.state.get.availableVersion. Historical notes
do not emit updater.highlights.show or enable downloading a downgrade. Missing
release bodies and empty channels return an explanatory note instead of the
pre-check placeholder.
Updater preferences are independent. autoCheckForUpdates defaults to true;
autoDownloadUpdates defaults to false and requires an explicit opt-in. Neither
preference authorizes installation or application shutdown. New profiles use the
nightly update channel when the embedded application version has a nightly
prerelease identifier; existing persisted channel choices are preserved.
updater.install requires the boolean parameter confirmed: true. The core
serializes update preparation against session creation, claiming, polling, and
streamer startup. It rejects installation while a CloudMatch session exists or
the streamer is starting, negotiating, streaming, or recovering. The shell must
also check its local native-runtime state before requesting installation.
updater.state.get is authoritative after an error or request timeout. The core
emits updater.changed after update operations even if the original request was
cancelled, because cancellation does not undo an installation already prepared
by the native helper.
While updater.download runs, the updater state carries the additive field
downloadProgress: {"receivedBytes": n, "totalBytes": n}, where totalBytes is
the signed asset size. It is null in every other state. The core emits
updater.changed when the download starts and each time the received bytes cross
another whole percent of the signed size, so a download produces at most about
101 progress events before its response. Progress is advisory: hash and size
verification still decide whether the download succeeds. Clients must not synthesize canDownload, canInstall, or
canCheck from an error message. A failed check or a later release check does not
discard an already verified download.
Inside Flatpak, the updater reports status: "unsupported" and
updateSource: "flatpak". canCheck, canDownload, canInstall, and
exitRequired are false. updater.check returns that state without contacting
GitHub. Download and install requests fail with the package-manager instruction
in message. The core does not recover native update transactions inside the
sandbox, and the native update helper rejects execution there. Flatpak owns
package replacement and updates.
The additive updater state fields exitRequired and installVersion describe
the prepared installation, separately from availableVersion and
downloadedVersion. The shell may quit for an update only after a confirmed
install request in that same shell process, with authoritative
status: "awaiting-exit" and exitRequired: true, and while the local session
remains inactive. preparing, applying, and restarting are not permission to
quit. Terminal outcomes are succeeded, rolled-back, and failed;
managed-pending and reboot-required require native package-manager or operating
system completion. Spawning an installer or the replacement application never
counts as success.
On a later launch, the core reconciles these managed outcomes against the native
package registration and its running version. A known live installer keeps
managed-pending active. A completed installer resolves to succeeded or
failed, and the core clears the persisted active transaction. Terminal helper
outcomes (succeeded, rolled-back, failed) are likewise reported for that
launch only; the core clears the persisted transaction after the first
reconciliation so the same failure dialog does not reappear on every restart.
An MSI reboot
warning remains until Windows' per-boot sequence number changes. Sessions
remain available, but another update must wait for the required reboot so it
cannot overlap pending Windows file replacements. Reopening the app before
reboot does not count as successful installation.
If an installer process cannot be identified, the core keeps the transaction pending until a recorded boot change proves that the previous installer has stopped. Legacy transactions without a boot marker establish a baseline and may require one additional restart rather than guessing that installation finished.
Windows portable replacement requires a volume with persistent ACL support; FAT/exFAT installations are refused before shutdown because private staging cannot be enforced there. Preserved portable profile data retains its ownership and effective access permissions. Preparation also fails before shutdown if the replacement overlaps user data or exceeds the bounded copy limits. MSI packages use Windows Installer registration and preserve the registered installation root; they are not treated as portable directories.
updater.startup.ack accepts no parameters and returns { "acknowledged": true }
only for a valid helper-launched update attempt. A normal launch returns
acknowledged: false. The shell calls it after its UI and core connection are
ready. The core validates the prepared version, per-attempt nonce, and running
Qt application identity before acknowledging startup to the waiting helper.
These changes are additive within protocol version 1; they do not change the
native streamer ABI.
updater.highlights.show announces unread release notes, not a navigation
command. The shell keeps the current stream and its video item alive, defers the
announcement during sessions, and acknowledges the notes only when the user
opens them.
Setting themePack applies its default appearance (light for Bone/Cobalt, dark
for the other built-in packs) and clears themeAccentOverride in the same save.
Setting appAccentColor enables themeAccentOverride in the same save. The
settings.set response and settings.changed event include these coupled values
in changes; clients can still override appearance or restore the pack accent
by setting appTheme or themeAccentOverride independently.
settings.shortcuts.update writes stream shortcut bindings as one transaction:
{"bindings":{"shortcutToggleStats":"Ctrl+F11","shortcutScreenshot":""}}. Only the
existing shortcut* setting keys are accepted, each value is a string of at most 80
bytes (empty means unbound), and Ctrl+G and Shift+F3 stay reserved. After the
change is merged, no two non-empty bindings may share a chord (case and modifier
order are ignored). Any rejection leaves every binding unchanged. The core persists
the whole map in one save and rolls it back in memory if the save fails. The response is
{"bindings":{...applied}}; the settings.changed event names the first applied
key and carries the full map in changes. Qt uses this for moving a chord from one
command to another, clearing, resetting one binding, and resetting all bindings.
Each successful settings write publishes settings.changed before its own
response. A client that starts its next per-key write from that response has
already consumed the previous event. Other response/event pairs, including
settings.reset, retain their existing response-first order.
Qt delivers settings.changed before the corresponding response rather than deferring
it through the general event queue. The settings owner serializes writes per key, keeps
ordinary controls optimistic, and retains a confirmed snapshot for failure rollback.
Later edits use the latest intended value; a failed queued tail restores the last confirmed
value and its coupled changes. Confirmation-sensitive settings and collection callbacks
retain their existing behavior.
Settings writes use a temporary file plus recoverable backup and normalize
compatibility-sensitive values. audioOutputDevice is an opaque native output identifier
(at most 1024 UTF-8 bytes, without NUL characters); an empty string follows the
system default. It is persisted and passed unchanged in the prepared stream
context for the next session. A missing fixed output fails playback startup
instead of falling back to another device. Setting launchInConsoleMode=false atomically
sets switchToConsoleOnPad=false too, so a manual desktop choice survives restart.
That response and settings.changed event additionally contain
"changes":{"switchToConsoleOnPad":false}; consumers apply these coupled values
before the primary key. Automatic console switching defaults off. Existing
pre-opt-in settings receive a one-time reset of automatic switching only;
explicit subsequent opt-ins and the independent startup preference are preserved.
Existing microphone device selections are cleared only when explicitly selecting Open
microphone; that write likewise reports "changes":{"microphoneDeviceId":""} so the
shell follows the system-default capture selection. Setting colorQuality repairs an
explicitly saved codec (or fallbackCodec) the new color mode cannot use toward
auto in the same save — H.264 is 8-bit 4:2:0 only, AV1 is 4:2:0 only — and reports
the repair in changes. Explicit codec/fallbackCodec selections the saved color
cannot use are rejected as invalid_setting instead; unknown spellings still clamp
to Auto.
onboardingCompleted is a persisted boolean, defaulting to false for a new
profile or an unreadable or malformed settings file. A valid existing settings
JSON object without the key migrates to true and is saved during loading, so
upgrades do not trigger first-run setup. Explicit false and true values survive
reloads and unrelated writes, including startup preferences and window geometry.
Non-boolean values normalize to false under the standard settings type rules.
settings.reset preserves the current completion value while resetting preferences;
it does not replay onboarding for an existing user. Failed saves leave the previous
in-memory value and persisted settings unchanged.
gameCollections defaults to []. settings.set replaces the complete ordered
array with at most 100 objects of the form
{"id":"collection-id","name":"Collection name","gameIds":["game-id"]}.
Collection IDs are caller-owned stable strings, unique across the array, and
must not be regenerated when renaming a collection. IDs are preserved verbatim,
must contain a non-whitespace character, and are limited to 128 Unicode characters.
Names are trimmed and must contain 1–80 Unicode characters after trimming; names
need not be unique. Each gameIds array contains at most 10,000 unique strings
with the same nonempty/128-character ID constraints. Game IDs may appear in
multiple collections, and empty collections are allowed. Array order is preserved.
Malformed types, missing or extra fields, duplicate IDs, or exceeded limits return
an error without modifying the in-memory settings or persisted file. Save failures
also restore the previous in-memory settings, including when resetting settings.
Reloads trim valid persisted names and preserve collections across unrelated writes;
invalid persisted collections cause an InvalidData load error before any write,
rather than silently dropping collections or truncating identifiers. A successful
settings.reset clears collections along with other preferences.
controllerLeftStickDeadzone, controllerRightStickDeadzone (integers 0–50,
default 5) and controllerVibrationIntensity (integer 0–100, default 100) stay the
global controller tuning and the default for every pad. controllerProfiles
defaults to {} and holds per-pad overrides keyed by pad identity. Qt builds the
key as serial:<vendor>:<product>:<serial> (four-digit lowercase hex vendor and
product IDs) when SDL reports a serial number, and as guid:<SDL GUID string>
otherwise. Two identical pads without a serial therefore share one key and one
profile. Each value has the form
{"name":"DualSense","leftStickDeadzone":8,"rightStickDeadzone":5,"vibrationIntensity":70,"lastSeen":1760440000000}.
Every tuning field is optional; a missing field means the global setting applies.
settings.set replaces the whole map and normalizes it rather than rejecting it:
keys are trimmed and must hold 1–160 characters; tuning fields that are not
integers are dropped and integers are clamped to the global ranges; name is
trimmed to at most 80 characters and dropped when empty; lastSeen (Unix
milliseconds) defaults to 0. Entries that are not objects or keep no tuning field
are dropped, so deleting a pad's fields resets it to the globals. At most 32
profiles are kept, preferring the highest lastSeen. Non-object values normalize
to {}. Settings saved before this key existed load with {}, and
settings.reset clears it. These values apply live in Qt before input reaches the
streamer; they never require a new session.
Provider discovery falls back to NVIDIA's default service when discovery is unavailable. Device-login tokens are stored through the OS credential store (DPAPI/Credential Manager, Keychain or Secret Service), with an explicit memory-only fallback when that facility is unavailable; the shell never receives a password. Public catalog results are cached in the core process and bounded per response.
CloudMatch session methods preserve one client/device identity through create,
poll and stop, retain pending queue responses before signaling is available,
and return the complete ordered connection, ICE and negotiated-feature payload
needed by the native streamer. streamer.prepare returns the normalized session
context used by the native runtime linked into the Qt shell. The in-process runtime
owns secure NVIDIA signaling, ICE/DTLS/SCTP, RTSPS, Mjolnir, RTCP and native
gameplay input, while Qt owns the graphics device, scene graph, video item and
all top-level windows. Legacy streamer lifecycle methods remain protocol
compatibility routes and are not used by the Qt shell.
webrtcCompatibilityMode selects auto, on, or off for new allocations.
The default auto uses WebRTC for a detected, authenticated alliance provider and
NVST for NVIDIA. on explicitly selects WebRTC for either provider; off selects
NVST. Provider selection is resolved in the core before codec validation and
allocation, not inferred by Qt or changed after allocation. The UI calls it
WebRTC compatibility mode and warns about lower performance than NVST.
An older allianceWebrtcCompatibility: true preference migrates to on; the old
default false migrates to auto. The historical boolean remains a compatibility
alias for explicit on/off writes. Session ownership and authentication remain
required. Legacy persisted
transportMode values still normalize to nvst; only the core-owned session's
transport selects the embedded WebRTC path. An explicit H.265 selection preserves
the requested resolution and frame rate, subject to the normal allocation and
decoder checks, and supports 8-bit or 10-bit 4:2:0 SDR. Both WebRTC and NVST
CloudMatch requests use requestedStreamingFeatures.bitDepth: 1 for 10-bit
and 0 for 8-bit, rather than the literal media bit depth. The owned session
profile carries the selected codec through polling, restart, and attachment;
changed preferences cannot reinterpret an existing stream. H.264, Auto, and AV1
selections retain the H.264 compatibility profile, at most 1920×1080 at 60 FPS
with 8-bit 4:2:0. Both WebRTC codecs use SDR, stereo, and no microphone.
WebRTC startup rejects profiles outside the native runtime's dimensions or frame
rate bounds rather than substituting a different viewport in its SDP answer.
WebRTC signaling endpoints remain separate
from RTSPS endpoints, including their server-provided paths and ports. The native
runtime owns the WebSocket offer, answer, NVIDIA quality SDP, and ICE exchange.
It delivers compressed media to the existing decoder and GPU presentation path.
The setting does not authorize a live NVST seat to be converted, deleted, or replaced.
For an owned WebRTC allocation that supplies only legacy RTSP descriptors,
the core derives wss://<descriptor-host>/nvst/ on port 443, matching Android's
WebRTC signaling contract. It does not reuse the RTSP port as a WebSocket or UDP
media port. Explicit WebSocket descriptors take priority and keep their paths
and ports. prepare_endpoints diagnostics record bounded descriptor types and
numeric protocol/port fields, never hosts, URLs, session IDs, or credentials.
WebRTC offers may contain additional microphone or inactive media sections.
Negotiation keeps their order and MIDs, disables RTP upload, and accepts one
incoming video track matching the selected H.264, H.265 Main, or H.265 Main10
profile and at most one incoming Opus audio track. Unsupported
microphone codecs are rejected in place with valid SDP format identifiers rather
than rejecting the whole session. Offers remain bounded to eight media sections.
The webrtc-offer diagnostic records section kinds and directions without SDP
credentials. Keyframe feedback uses the transport's negotiated video MID.
For an actpass offer, the native client takes the active DTLS role and sends
ClientHello, matching browser behavior against NVIDIA's ICE-lite endpoint.
Explicit active or passive remote roles retain their complementary local role.
Connection diagnostics distinguish ICE completion from DTLS establishment and
record redacted candidate classes, ports, and packet-family counters without
addresses, credentials, or payloads.
The Qt video item remains visible while the native backend is connecting,
including reconnect attempts, so it can create the graphics context before the
first frame. Gameplay focus/input still waits for streaming; startup overlays
may cover the same video item without preventing presentation initialization.
acceptance.export is available only through the Qt shell's Diagnostics screen. It rejects
headless window systems and writes an atomic, redacted opennow.live-acceptance JSON file. The
file records machine-observed ten-minute streaming, first-frame, guide/input ownership, surface,
microphone, recording, hashed media, bounded recovery and terminal-error checks. It contains no
account identifiers, session identifiers, URLs, process identifiers, executable paths or local
media paths. A false check is retained as evidence of an incomplete run; it is never promoted to
a pass by the release verifier.
Network work runs outside the protocol reader with a fixed concurrency ceiling, connect/request deadlines, one serialized output writer and best-effort response suppression after cancellation. The full Electron API inventory remains tracked in the machine-readable parity manifest, validated against its JSON schema and executable golden-fixture tests. A method is not considered ported until its owner, wire shape, fixtures and replacement disposition are recorded there.
Push invalidation capability
Protocol 5 advertises account.pushInvalidation.v1 when the core ships the native
push subscriber. The capability only describes the accelerator below; the shell
must keep working when it is absent.
The core may open a native FCM/PNS subscription for the signed-in account. The subscription is provider-scoped and bounded: it exists only while an account is signed in, and it is torn down or paused on sign-out, account switch, or shutdown.
push.json in the data directory is an optional override, never required. When it is genuinely
absent, the core uses a bundled default built from the vendor's public client identifiers (see
provenance below). When it is present, it always wins: the core never falls back to the bundled
default for an existing override. The override is either a single object or an array of objects,
each with providerIdpId, projectId, apiKey, senderId, appId, firebaseAppId, optional
vapidKey, pnsServer, optional pnsVersion, and pnsClientId, plus an optional enabled
boolean. The entry whose providerIdpId matches the signed-in provider is the only one used. A
present override suppresses the default when it disables push ("enabled": false, whole-file or
per entry), is unreadable, malformed, or larger than 64 KiB, or carries no complete entry for the
signed-in provider. The override file is read-only deployment input: the core never writes it,
never logs it, never returns it from settings.get, and never stores it in the user settings
schema.
The bundled default contains only public client identifiers: a Firebase web API key, app, project, and sender identifiers, the VAPID public key, and the PNS client id and server. It carries no credentials and the core never writes it to the data directory. Per-account and per-device secrets — the ECE key pair, the auth secret, and the GCM/FCM tokens — are generated locally and stay in the OS credential store, and the PNS bearer token is the user's own sign-in token. The default is bound to the authenticated provider and generation snapshot by the same owner guards as an override, so it is re-evaluated on account and provider changes. Whether the PNS backend accepts registrations for providers other than the vendor's own is unverified; the bundled default mirrors the vendor client's authenticated-account gate and does not claim guaranteed acceptance.
The bundled default derives from the vendor's public client configuration asset
(shared/assets/config/config.json inside the official package, SHA256
8e7db09026e5b48b0eabb364395c726543fcab9778b3561529fcb6a96208db65; official package archive
SHA256 47ddbe0425b9ab560f64fa42a0052794c9de335ded0fd59637f082dd7a161ad4), mapping
firebase.pns to the Firebase identity and pnsServerConfig to the PNS endpoint. A subscription
delivers invalidation hints only. Each hint is emitted as an ordinary event envelope:
{"type":"event","name":"account.push.changed","payload":{"generation":7,"kind":"library","changedIds":["app-id"]}}
kind is one of library, favorites, subscription, linked-account, or
platform-sync. generation is the GFN state generation the hint belongs to;
a shell drops hints whose generation does not match its current account
generation. changedIds is bounded and advisory.
Hints never assert a result. platform-sync carries the store's reported
platformCode, syncState, syncDate, and syncGameCount and only makes the
shell observe the existing sync earlier; completion still requires a fresh
syncDate with syncState SYNC_SUCCESS from
account.connections.sync.status. A hint that arrives while its account is no
longer current is discarded, and a subscription never serves another account's
registration.
Push registration state is per account and stored in the OS credential store. No token, key, or message body is written to settings, diagnostics, or logs. The subscriber uses only deadline-bounded network operations, and a configuration change, sign-out, or account switch retires the current subscription before another one starts. Every registration stage is guarded between requests, so a retired scope or shutdown stops the remaining stages after at most one in-flight request deadline.
A refused MCS login (a non-zero LoginResponse.error.code) is a session failure, not a
credential verdict: it triggers one bounded registration refresh that keeps the stored device
identity and replaces only the registration keys and tokens. A LoginResponse that carries a
zero error code is accepted as a successful login. The device identity is replaced only when the
check-in authority rejects it with HTTP 400 or 401.
Every received frame counts toward the last_stream_id_received the session advertises. The
session acknowledges incoming heartbeat pings, answers an immediate-ack data message or every
ten unacknowledged persistent messages with an IQ stream acknowledgement (extension id 13),
and honours the heartbeat interval the server negotiates through LoginResponse.heartbeat_config
within bounded limits. A heartbeat that stays unanswered past the acknowledgement deadline, or a
login request without a response within its deadline, ends the session so the owner reconnects
with the stored registration rather than holding a half-open connection.
Encrypted bodies are selected the way the maintained client selects them: a declared
content-encoding of aes128gcm uses the RFC 8291 body header (salt, record size, key id),
aesgcm uses the legacy Crypto-Key/Encryption headers, any other declared value is
rejected, and an absent declaration falls back to the legacy headers when both are present and
to the RFC 8291 body otherwise. This follows Chromium's
components/gcm_driver/crypto/gcm_encryption_provider.cc, where content-encoding is the
kContentEncodingProperty discriminator and the legacy path is keyed on the presence of both
Encryption and Crypto-Key. No ciphertext shape is guessed: an unsupported declaration is an
error, not a heuristic.
Live delivery remains unverified. The subscriber ships complete in code with the bundled default and is covered by fixtures, but no live Google check-in, c2dm, FIS, FCM, PNS, or end-to-end encrypted delivery has been exercised, and hardware and account-backed validation are out of scope for the fixture path.
Catalog page and metadata capabilities
Protocol 4 requires catalog.libraryPages.v1, catalog.metadata.v1,
account.syncObservation.v1, and catalog.languages.v1 in the core handshake.
The Qt client and both relocated package probes check these capabilities.
The JSON envelope and native streaming ABI do not change.
catalog.library.list accepts limit from 1 to 100, an opaque cursor up to
4,096 bytes, and a traversalId up to 256 bytes. Continuations must carry the
catalogRevision and opaque catalogContext returned by the first page. The context binds the cursor to the provider, account, generation, endpoint, resolved VPC, proxy route and locale. Results contain games, count,
nullable totalCount, hasNextPage, nextCursor, fetchedAt, freshness,
traversalId, catalogRevision, catalogContext, and the authenticated scope. One result is
at most 768 KiB. Oversized pages are retried at the same cursor with a smaller
count; a record that cannot fit is an error. Invalid identities or missing
pagination state are errors, not an empty complete library.
CatalogState stages these pages and detects cursor cycles. A complete library
means the traversal reached a validated end; it does not imply a transactional
snapshot of concurrently changing vendor data. Refresh preserves the previous
complete snapshot until the new traversal ends. The foreground slice is 30
seconds, with an explicit Continue action. The hard aggregate bounds are 20,000
games and 32 MiB of conservative serialized-size accounting. Partial/error
results retain usable data, the failed cursor where safe, and the error text.
catalogLastCompleteAt changes only when the aggregate traversal completes.
catalog.game.get accepts exactly one appId or variantId. The former is a
parent LCARS string; the latter must fit a positive GraphQL Int. The request
selects library-aware metadata and verifies the returned identity. It always
revalidates rather than authorizing from cached browse cards. The result has
game, catalogRevision, scope, fetchedAt, and freshness.
Game variants retain nullable librarySelected, libraryStatus, playStatus,
installed, subscription, gfnStatus, stateDetails, paymentModels,
subscriptions, and supportedLanguages. Patch details distinguish automatic
patches, manual patches, maintenance, and unknown types. Games retain app-level
favorited, catalogSkuStrings, campaignIds, and fallback paymentModels.
App availability, favorites, payment models, and GFN membership do not establish
ownership of another variant. Visible detail metadata refreshes every 30 seconds;
patch duration history is an estimate, not a promised completion time.
Every game variant also carries features, an array of lowercase strings
parsed from the variant's gfn.features key/value list: rtx from
RTX_ENABLED, hdr from HDR_ENABLED or a non-empty
SUPPORTED_HDR_VERSION, and reflex from REFLEX_ENABLED. Disabled, null,
and unknown keys produce nothing, so the array is empty when the catalog does
not declare a feature. features is null when the catalog response carried no
feature list for that variant, so consumers can tell unknown from none.
The catalog has no per-game DLSS key, so the core, and only the core, derives a
game-level dlss field from NVIDIA's published DLSS games list (the JSON behind
NVIDIA's RTX games page) by title. Shells still must not infer features from
titles or genres themselves, and a "dlss" string in a variant's features
means nothing. While the list is loaded, every game in every catalog.* result carries dlss, including
catalog.public.list, catalog.library.list, catalog.game.get,
catalog.launch.inspect, catalog.launch.store.inspect,
catalog.favorites.list, the favorites and ownership mutation results,
catalog.store.local, catalog.store.list, and catalog.store.presentation.
The value is either null (not on NVIDIA's list) or:
{"superResolution":"native","frameGeneration":"override",
"multiFrameGeneration":{"maxMultiplier":4},"rayReconstruction":null,
"dlaa":"override","source":"nvidia-rtx-games-list"}
superResolution, frameGeneration, rayReconstruction, and dlaa are
native when the game supports the technology itself, override when a DLSS
override acts on it (the list's "NV, …" cells: an upgraded SR/RR/DLAA or frame
generation model, or DLAA enabled through the SR mode override), and null when
the list does not show it. multiFrameGeneration is null or the highest
multiplier an override enables. dlss is null when the title has no match and
when the matched row lists no DLSS technology. When the list is unavailable, games
have no dlss key at all: an absent key means DLSS support is unknown, and shells
must not present it as "not on NVIDIA's list".
Matching removes ™, ®, ©, and zero-width characters, folds the title to ASCII
with NFKD, lowercases it, spells & as "and", and collapses every other
non-alphanumeric run to one space. An exact match wins; otherwise a loose match
also drops the words "the" and "tm" and trailing edition words (game of the
year, goty, definitive, enhanced, complete, deluxe, standard, ultimate,
director's cut, anniversary, edition, pc). "Remastered" is never dropped,
because remasters are listed separately. Only rows of type "Game" count.
The core keeps the list in the store cache for 24 hours (stale copies are used
when a refresh fails), rejects documents over 4 MiB or 5,000 rows, and applies
it when a catalog response is sent, so cached catalog pages are unaffected and
the scope stays catalog-v3. Fetching never fails or holds a catalog response:
only one request waits for the core's first attempt, for at most 1.5 seconds; a failed attempt
retries on a catalog request at least 60 seconds later. The field is additive
within protocol version 5.
Every game also carries requiresPaidMembership, true when the catalog's
minimumMembershipTierLabel names a tier other than Free (the catalog reports
Premium today). It is the rule the core applies before a launch, so shells
compare it with the account's membershipTier instead of parsing the label.
Both fields are additive within protocol version 5; store-catalog cache scopes moved from
catalog-v2 to catalog-v3 so cached cards are refetched with it.
catalog.definitions.get returns independently fetched stores, genres, and
subscriptions sections. Each section has items, source, status,
freshness, fetchedAt, expiresAt, and nullable error. Static definitions
expire after 24 hours. Store definitions retain the feature union and per-variant
linking metadata. They drive account rows and allowed actions. Unknown stores
are display-only; unavailable definitions use labelled, action-disabled fallback
rows. A current server supported:false overrides older capability data.
Store subscription IDs are separate from MES/GFN membership.
catalog.store.presentation retains parsed filter expressions and sortOrders.
catalog.store.list can receive a filterId or sortId; the core resolves these
to the returned server expressions rather than sending an ID as a filter object.
revalidate:true invalidates only the addressed page key; use it for an explicit
search submission rather than refresh:true, which resets a browse chain.
Local Store facets remain local. catalog.store.local returns
localHasNextPage, cacheComplete, upstreamCoverage, and facetsSource
alongside its existing demand-driven cursor. Local exhaustion does not prove
upstream coverage. Browse disk pages expire after 15 minutes, and explicit local
refresh first revalidates the upstream first page before rebuilding the index.
Confirmed account changes persist an increasing catalog revision, so old pages cannot join
a new traversal or reappear after a core restart. Failure to persist the revision is an explicit cache-invalidation error, not completion. Cache identities include provider/account, generation,
endpoint, resolved VPC, proxy route, locale and schema revision.
Store synchronization observation
account.connections.sync sends one ALS POST and accepts only HTTP 202. It
returns operationId, provider, and a local phase. Repeated starts for the
same active provider return the existing operation instead of repeating POST.
There are at most eight account-scoped operations. Mutating requests are never
automatically replayed after a 401, timeout, cancellation, or ambiguous send.
account.connections.sync.status accepts operationId. Each poll reads fresh
userAccount at most once. Calls are spaced at two seconds initially and five
seconds after 20 seconds, with a 120-second observation deadline. The operation
records the baseline date and state. Only a changed valid RFC3339 syncDate
with SYNC_SUCCESS enters refreshing_library; unchanged old success, an
unchanged old failure, and changed counts alone do not prove completion. New
failure, disconnection, and expiry enter failed. Missing completion evidence
ends as timed_out, meaning completion is unconfirmed.
After refreshing_library, Qt starts the final library traversal. Only a
complete traversal displays completion and acknowledges it with
sync.status({operationId, libraryRefreshed:true}). Partial refresh retains a
separate incomplete notice. account.connections.sync.cancel stops observation,
not accepted remote work. Account/provider generation changes clear pending
work; late results cannot complete another account's operation. Polls do not
sleep across their observation lifetime or hold authentication or scheduler
locks across HTTP. Link callbacks and unlink acknowledgements require a fresh
account read before claiming the connection changed.
Overall supported game languages
catalog.languages.get({refresh:false}) works without sign-in. Its anonymous
HTTP document is exactly { overallGfnSupportedLanguages { language } }.
There are no variables and no Authorization header. It returns exact wire IDs
in languages, status (success, stale, or error), source, cache timing,
nullable error, and scopeGeneration. The bounded cache is shared with the
existing disk-cache owner, keyed separately by public endpoint, provider context,
and proxy route. Its TTL is 14 days. At most 512 safe IDs of 64 bytes are accepted;
duplicate IDs are removed without normalization. Invalid or empty metadata does
not replace a previous good list. Failure with a previous list is explicitly
stale; failure without one has an empty list and error status. This reference
data does not select the interface locale, keyboard map, or a game's preferences.
Independent language preferences and settings choices
appLanguage defaults to system and selects a bundled Qt interface locale.
gameLanguage defaults to en_US; keyboardLayout defaults to en-US.
Changing one does not change either of the others. Game language identifiers
retain exact case, separators, script, and numeric-region subtags. They have an
ASCII alphabetic first subtag of 2–8 bytes, subsequent alphanumeric subtags of
1–8 bytes separated by _ or -, and a total limit of 64 bytes. auto and
system are rejected, case-insensitively. Safe future IDs need not appear in
current metadata to remain saved.
settings.get returns keyboardLayouts beside settings, never inside the
persisted values. Each descriptor has value, label, and aliases. The table
in language.rs is the authority for the supported Windows-rig keyboard subset
on all Qt platforms. Historical ja-JP and Japanese106 request ja-106;
historical es-ES requests es-ES_tradnl. Valid saved aliases retain their
original spelling on disk. This does not select proprietary Mac keyboard IDs.
New unrecognized keyboard values and malformed game IDs return invalid_setting.
Restored strings remain visible, but a shared request resolver replaces corrupt
game or keyboard values with the existing respective defaults before create,
immediate resume, or claim requests. The interface locale never enters these
query parameters.
settings.choices.get({runtimeCapabilities}) also returns frameRates for the documented
frame-rate tiers, using the same value, disabled, and nullable reason descriptor shape.
The conditional top tier reports a reason for each unconfirmed condition: a resolution outside
full HD, an unreported capability probe, or a reported probe without a hardware decoder for the
selected codec. Missing or unreported capabilities never imply support, and only rates at or
below 240 FPS are unconditional. The entitlement limit stays a Qt-side decision because the
core holds no subscription data.
settings.choices.get({runtimeCapabilities}) returns colorQualities for the current
persisted settings and embedded streamer capability snapshot. Each of the four
descriptors contains value, disabled, and nullable reason. The operation
calls the same profile resolver as final launch. A color quality is disabled when
resolution fails or when the launch would fall back to a lower bit depth or a
different chroma format; the reason names the delivered profile. Codec descriptors
are disabled only when the codec itself cannot decode 8-bit 4:2:0 SDR on the selected
backend. Missing or incompatible capabilities do not imply support. This read does not persist or coerce any setting. Protocol 5 and native
streamer protocol 7 are unchanged.
CoreClient injects the current native window's nativeHdrSupported into
runtimeCapabilities, overriding any caller-supplied flag, just as it does for
session.create and streamer.prepare. It injects nativeHdrDisplay alongside it only
when the output reported a validated luminance range, so an unavailable snapshot is
omitted rather than sent as zero. SettingsState observes
HdrOutput.supported only to cancel and refetch choices when the display changes;
it does not author the wire capability or expose platform handles.
Qt SettingsState owns shared desktop/console choices and the single lazy
language request. Settings entry loads idle or expired metadata. Explicit retry
sets refresh:true; there is no retry loop. Requests have a 15-second deadline.
Readiness, account/provider generation, or proxy changes clear request ownership
before cancellation and discard old metadata, but preserve saved preferences.
Only a response for the current request and generation is accepted. cacheHit,
stale/error status, saved IDs absent from metadata, and local fallback choices
remain distinguishable. Language and profile edits serialize per key and become
selected only after persistence succeeds; older failures cannot roll back a
newer successful edit. These local settings operations do not restart media.