Files
DroidDeck/external/opennow/docs/core-protocol.md
T
The412Banner f0f17b9b63 Vendor OpenNOW's core and native streamer (MIT, by Zortos)
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.
2026-10-26 18:25:13 +00:00

120 KiB
Raw Blame History

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.list returns 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.inspect resolves 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-start uses its command id as the recording identity. A recording-state terminal event carries that identity as requestId and a state of saved or failed. A saved result includes path, videoPackets, audioPackets, and completion. 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-stopped repeats the terminal result and its originating requestId; its id still identifies the stop command. Qt applies a correlated terminal result once, whether the event or stop response arrives first. A repeated stop returns recording-not-active without 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 start response includes replayEnabled for the actual session.
  • clip-save accepts id and an absolute .mkv outputPath allocated by media.recording.target. It returns clip-saving promptly or a typed error if replay is disabled, not yet decodable, or another export is still running.
  • A clip-state event reports state (saved or failed), requestId, path and message. The shell correlates requestId with the outstanding export and ignores completion from a previous session. Cancelled exports do not publish a completed file or a stale success event.
  • replay-stop returns replay-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:

  1. Missing HDR output (nativeHdrSupported not true) clears HDR.
  2. Software decoding resolves to 8-bit 4:2:0 SDR.
  3. 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.
  4. 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.
  5. Ten-bit SDR that the selected codec, or every Auto candidate, cannot decode falls back to 8-bit 4:2:0 BT.709.
  6. 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.
  7. 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.
  8. Each codec may report maxDecodeDimensions:{width,height} in runtimeCapabilities. 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.