lib/conditional-settings
Conditional settings: settings whose default depends on other state (HiDPI defers to whether a manual resolution is set, rate control to the encoder, ...).
Each is a declarative spec, and the precedence ladder, resolution, and
(through the dashboards' thin useConditionalSetting hook) initialization,
server sync and dependency re-derivation are generic; adding a setting is
one more spec. A spec fully describes both the read side and the write
side so the dashboards touch neither postMessage nor localStorage keys
directly.
Resolution precedence, highest first:
- locked server value: the operator forces it, the client cannot override;
- explicit client choice, from localStorage, which must satisfy
isValid; - explicit server choice, a CLI or environment override, which must
satisfy
isValid; - conditional default, derived from other state, which must satisfy
isValid; - built-in server default, the ground-truth fallback.
Interfaces
SettingSpec
Defined in: lib/conditional-settings.js:25
Properties
id
id: string;Defined in: lib/conditional-settings.js:26
Name of the setting in the dashboards.
serverKey
serverKey: string;Defined in: lib/conditional-settings.js:27
Key into server_settings.
storageKey
storageKey: string;Defined in: lib/conditional-settings.js:28
localStorage key for the client's choice.
parse?
optional parse?: (stored) => any;Defined in: lib/conditional-settings.js:29
Interprets the stored string; identity by default.
Parameters
| Parameter | Type |
|---|---|
stored | string |
Returns
any
conditional?
optional conditional?: (ctx) => any;Defined in: lib/conditional-settings.js:31
State-derived default, or
undefined when the state implies nothing.
Parameters
| Parameter | Type |
|---|---|
ctx | any |
Returns
any
isValid?
optional isValid?: (value, ctx) => boolean;Defined in: lib/conditional-settings.js:33
Rejects invalid candidates at every rung.
Parameters
| Parameter | Type |
|---|---|
value | any |
ctx | any |
Returns
boolean
fallback?
optional fallback?: any;Defined in: lib/conditional-settings.js:35
Value used when nothing else resolves.
toUi?
optional toUi?: (serverValue) => any;Defined in: lib/conditional-settings.js:36
Maps the server domain to the UI domain.
Parameters
| Parameter | Type |
|---|---|
serverValue | any |
Returns
any
toServer?
optional toServer?: (uiValue) => any;Defined in: lib/conditional-settings.js:38
Inverse of toUi; identity by
default.
Parameters
| Parameter | Type |
|---|---|
uiValue | any |
Returns
any
serialize?
optional serialize?: (uiValue) => string;Defined in: lib/conditional-settings.js:40
localStorage form; String
by default.
Parameters
| Parameter | Type |
|---|---|
uiValue | any |
Returns
string
propagate?
optional propagate?: (serverValue, ctx, io) => void;Defined in: lib/conditional-settings.js:42
Pushes a change to the server or the core.
Parameters
| Parameter | Type |
|---|---|
serverValue | any |
ctx | any |
io | { postSetting: Function; postToCore: Function; } |
io.postSetting | Function |
io.postToCore | Function |
Returns
void
Variables
ENCODER_RC_DEFAULTS
const ENCODER_RC_DEFAULTS: object;Defined in: lib/conditional-settings.js:57
Rate-control default per encoder for WebSocket streams when nothing explicit is chosen: quality-driven (CRF).
WebRTC streams default to CBR regardless of encoder (RATE_CONTROL_SPEC):
a congestion-controlled transport needs the encoder holding a bandwidth
target. So does OpenH264, the software H.264 encoder of a GPL-free
pixelflux build: a session known to encode on the CPU defaults to CBR when
the server reports that build (softwareH264RcDefault, the same rule as
the server's resolve_rate_control_default).
Type Declaration
h264enc
h264enc: string = "crf";h264enc-striped
h264enc-striped: string = "crf";jpeg
jpeg: string = "crf";HIDPI_SPEC
const HIDPI_SPEC: object;Defined in: lib/conditional-settings.js:153
HiDPI, shown as the inverse of use_css_scaling. A manual or preset
resolution wants CSS scaling on (HiDPI off). The core owns useCssScaling,
applying and persisting it on the propagated message.
Type Declaration
id
id: string = "hidpi";serverKey
serverKey: string = "use_css_scaling";storageKey
storageKey: string = "useCssScaling";parse
parse: (v) => boolean;Parameters
| Parameter | Type |
|---|---|
v | any |
Returns
boolean
conditional
conditional: (ctx) => boolean;Parameters
| Parameter | Type |
|---|---|
ctx | any |
Returns
boolean
fallback
fallback: boolean = false;toUi
toUi: (cssScaling) => boolean;Parameters
| Parameter | Type |
|---|---|
cssScaling | any |
Returns
boolean
toServer
toServer: (hidpi) => boolean;Parameters
| Parameter | Type |
|---|---|
hidpi | any |
Returns
boolean
serialize
serialize: (hidpi) => string;Parameters
| Parameter | Type |
|---|---|
hidpi | any |
Returns
string
propagate
propagate: (cssScaling, _ctx, io) => any;Parameters
| Parameter | Type |
|---|---|
cssScaling | any |
_ctx | any |
io | any |
Returns
any
RATE_CONTROL_SPEC
const RATE_CONTROL_SPEC: object;Defined in: lib/conditional-settings.js:167
Rate control: CBR on WebRTC, else the per-encoder default.
Type Declaration
id
id: string = "rate_control_mode";serverKey
serverKey: string = "rate_control_mode";storageKey
storageKey: string = "rate_control_mode";conditional
conditional: (ctx) => string;Parameters
| Parameter | Type |
|---|---|
ctx | any |
Returns
string
isValid
isValid: (v, ctx) => any;Parameters
| Parameter | Type |
|---|---|
v | any |
ctx | any |
Returns
any
fallback
fallback: string = "crf";propagate
propagate: (mode, _ctx, io) => any;Parameters
| Parameter | Type |
|---|---|
mode | any |
_ctx | any |
io | any |
Returns
any
USE_BROWSER_CURSORS_SPEC
const USE_BROWSER_CURSORS_SPEC: SettingSpec;Defined in: lib/conditional-settings.js:198
The core owns use_browser_cursors, applying and persisting it on the
propagated message, so this spec posts to the core rather than a settings
message.
VIDEO_FULLCOLOR_SPEC
const VIDEO_FULLCOLOR_SPEC: SettingSpec;Defined in: lib/conditional-settings.js:200
VIDEO_STREAMING_MODE_SPEC
const VIDEO_STREAMING_MODE_SPEC: SettingSpec;Defined in: lib/conditional-settings.js:202
USE_PAINT_OVER_QUALITY_SPEC
const USE_PAINT_OVER_QUALITY_SPEC: object;Defined in: lib/conditional-settings.js:209
Paint-over spends encoder effort a bandwidth-targeted stream budgets for
motion, so it defaults off under CBR and back on under CRF until someone
chooses (the same rule as the server's resolve_paint_over_default).
Type Declaration
id
id: string;Name of the setting in the dashboards.
serverKey
serverKey: string;Key into server_settings.
storageKey
storageKey: string;localStorage key for the client's choice.
parse?
optional parse?: (stored) => any;Interprets the stored string; identity by default.
Parameters
| Parameter | Type |
|---|---|
stored | string |
Returns
any
isValid?
optional isValid?: (value, ctx) => boolean;Rejects invalid candidates at every rung.
Parameters
| Parameter | Type |
|---|---|
value | any |
ctx | any |
Returns
boolean
fallback?
optional fallback?: any;Value used when nothing else resolves.
toUi?
optional toUi?: (serverValue) => any;Maps the server domain to the UI domain.
Parameters
| Parameter | Type |
|---|---|
serverValue | any |
Returns
any
toServer?
optional toServer?: (uiValue) => any;Inverse of toUi; identity by
default.
Parameters
| Parameter | Type |
|---|---|
uiValue | any |
Returns
any
serialize?
optional serialize?: (uiValue) => string;localStorage form; String
by default.
Parameters
| Parameter | Type |
|---|---|
uiValue | any |
Returns
string
propagate?
optional propagate?: (serverValue, ctx, io) => void;Pushes a change to the server or the core.
Parameters
| Parameter | Type |
|---|---|
serverValue | any |
ctx | any |
io | { postSetting: Function; postToCore: Function; } |
io.postSetting | Function |
io.postToCore | Function |
Returns
void
conditional
conditional: (ctx) => boolean;Parameters
| Parameter | Type |
|---|---|
ctx | any |
Returns
boolean
USE_CPU_SPEC
const USE_CPU_SPEC: SettingSpec;Defined in: lib/conditional-settings.js:214
FORCE_ALIGNED_RESOLUTION_SPEC
const FORCE_ALIGNED_RESOLUTION_SPEC: SettingSpec;Defined in: lib/conditional-settings.js:216
Functions
softwareH264Path()
function softwareH264Path(encoder, useCpu): boolean;Defined in: lib/conditional-settings.js:72
Whether a session with this encoder is known to encode H.264 on the CPU:
the striped encoder has no hardware path, and h264enc does when software
encoding is forced (without it h264enc may still land on the CPU, which
nothing here can know in advance).
Parameters
| Parameter | Type | Description |
|---|---|---|
encoder | string | Encoder wire value. |
useCpu | boolean | Whether software encoding is forced. |
Returns
boolean
softwareH264RcDefault()
function softwareH264RcDefault(
encoder,
softwareH264Encoder,
useCpu
): string;Defined in: lib/conditional-settings.js:84
The WebSocket rate-control default for an encoder.
Parameters
| Parameter | Type | Description |
|---|---|---|
encoder | string | Encoder wire value. |
softwareH264Encoder | string | The server's software H.264 encoder from the settings payload, x264 or openh264. |
useCpu | boolean | Whether software encoding is forced. |
Returns
string
cbr or crf; undefined for an unknown encoder.
resolveConditionalSetting()
function resolveConditionalSetting(input): any;Defined in: lib/conditional-settings.js:101
Resolves one setting to its value in server terms through the module's precedence ladder.
Parameters
| Parameter | Type | Description |
|---|---|---|
input | { server: { value: any; locked?: boolean; overridden?: boolean; }; stored: string; parse?: (stored) => any; conditional?: () => any; isValid?: (value) => boolean; } | - |
input.server | { value: any; locked?: boolean; overridden?: boolean; } | The setting's entry in server_settings. |
input.server.value | any | - |
input.server.locked? | boolean | - |
input.server.overridden? | boolean | - |
input.stored | string | The client's stored choice. |
input.parse? | (stored) => any | Interprets the stored string. |
input.conditional? | () => any | State-derived default. |
input.isValid? | (value) => boolean | Rejects invalid candidates. |
Returns
any
The resolved value; undefined without a server entry.
resolveSpec()
function resolveSpec(
spec,
serverSettings,
ctx,
readStored
): any;Defined in: lib/conditional-settings.js:122
Resolves a spec to its UI value.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | SettingSpec | The setting. |
serverSettings | any | The server_settings payload. |
ctx | any | State the spec's conditional and validator read. |
readStored | (key) => string | localStorage reader. |
Returns
any
The value in the UI domain.
isSettingPinned()
function isSettingPinned(
spec,
serverSettings,
readStored
): boolean;Defined in: lib/conditional-settings.js:143
Whether a setting is explicitly pinned, so a dependency change must not re-derive it: the client stored a choice, or the operator overrode or locked it.
Parameters
| Parameter | Type | Description |
|---|---|---|
spec | SettingSpec | The setting. |
serverSettings | any | The server_settings payload. |
readStored | (key) => string | localStorage reader. |
Returns
boolean
boolSpec()
function boolSpec(
key,
fallback,
propagate
): SettingSpec;Defined in: lib/conditional-settings.js:189
A spec for a plain boolean setting that carries a server truth. Routing it
through the ladder makes the displayed state track the real applied value,
so a locked or overridden operator value reaches the toggle. serverKey
and storageKey are the same key.
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The server and storage key. |
fallback | boolean | Value when nothing else resolves. |
propagate | (serverValue, ctx, io) => void | Pushes a change. |
Returns
storageKeyForServerKey()
function storageKeyForServerKey(serverKey): string;Defined in: lib/conditional-settings.js:242
The localStorage key a server setting's client choice lives under, which is what the cores ask "has the user overridden this?" about.
Parameters
| Parameter | Type | Description |
|---|---|---|
serverKey | string | Key into server_settings. |
Returns
string