PixelFX API reference

Schema files: vp_control/v1/settings_service.proto, vp_control/v1/settings.proto, fx/v1/options.proto (generated on 2026-11-21 19:29).

Schema id 3092366499 (0xb851c4a3): GetInfo.schema_id of a unit built from the same schema.

Example clients, with code generated from these files: vp_control-client-example.zip (JavaScript), vp_control-client-example-esp32.zip (ESP32, C).

Changes since 4.1.10

No changes to the API since 4.1.10.

PixelFX settings API (vp_control.v1)

vp_control/v1/settings_service.proto

Reads and changes the video settings of a PixelFX unit (Morph 4K) over its web server: everything the OSD's video pages set, as one tree, vp_control.v1.Settings.

Protocol

Unary Connect over HTTP:

  • POST http://<unit>/vp_control.v1.SettingsService/<Method>
  • Request and reply bodies are binary protobuf: Content-Type: application/proto. The unit has no JSON codec; another content type gets 415 Unsupported Media Type.
  • Request bodies need a Content-Length header. A body sent with chunked transfer encoding is refused (invalid_argument) and the connection closed; firmware before 4.1.8 read it as an empty request. HTTP clients that stream request bodies send them chunked (e.g. @connectrpc/connect-node over HTTP/1.1): use one that sends the body whole, such as one built on the Fetch API.
  • HTTP digest authentication with the web UI's user and password (none when the unit's web login is off).
  • Errors are a JSON body {"code": "...", "message": "..."} with the HTTP status of the code:
CodeHTTPWhen
invalid_argument400The request does not decode, names no such layer, list or save mode, has a field this firmware does not know (outside UpdateSettingsRequest.set), or its body comes without a Content-Length (chunked).
failed_precondition400if_settings_epoch is no longer the unit's settings epoch: read the settings again.
not_found404RunAction names an entry its list does not have.
aborted409The settings were replaced (mode change, console or game context, preset) before a save or action ran.
resource_exhausted429The request body is larger than the method accepts.
internal500The firmware's tables and messages disagree (a firmware bug).
unimplemented501No such method, or not on this product / not yet (a layer, a list).
unavailable503Out of memory, or busy (an apply in progress, another action waiting): try again.

A field the unit cannot take is no protocol error: UpdateSettings answers with accepted = false and a FieldIssue per field.

Concepts

  • Settings tree. Settings holds every setting of this API. Messages are proto2: each field has presence. A reply of the live settings sets every field; a layer or an update sets only the fields it carries.
  • Field paths. A field is named by its field numbers from the root (FieldPath), stable across renames. Clients map names through the descriptors of these files.
  • Layers. The live settings are merged from layers (Layer): the firmware's defaults, global settings, the video mode's settings, ... Changes are saved into one of them (Info.save_layer).
  • Apply sequence. Each accepted update gets an apply_seq; Info.applied_seq tells when it is done.
  • Settings epoch. The unit replaces its live settings as a whole on a video mode or engine change, a console or game context, or a preset; each time Info.settings_epoch counts up. Changes and saves belong to the epoch they were made in: an update accepted in one epoch is never applied in another (it is dropped, see Info.dropped_first), and a save never stores another epoch's settings. Pass the epoch you read as if_settings_epoch to make a call fail instead of acting on settings you have not seen.

Typical use

  1. GetInfo: product, schema id, settings_epoch.
  2. GetSettings: the live settings; show them.
  3. UpdateSettings with the changed fields in set and if_settings_epoch; on accepted, poll GetInfo until applied_seq >= apply_seq. By default the change is saved as the OSD saves (SAVE_LIKE_OSD).
  4. On failed_precondition, start again at 1.

Versions and compatibility

vp_control.v1 changes by additions only: new fields, messages, enum values, actions and lists. The number, type and meaning of an existing field never change, a removed field's number is never used again, and a range can only get wider. A change that breaks this would come as a new package (vp_control.v2), served next to v1. The reference page of each firmware version lists its changes since the version before.

For a client this means:

  • Send only what the unit has. Live GetSettings sets every field this firmware knows. An update with a settings field it does not know is refused with FieldIssue.NOT_ON_THIS_PRODUCT and that field's path; another unknown field in a request is invalid_argument. (Firmware before these rules ignored such fields.)
  • Absent means older. An Info field, a Feature or a list entry a client knows but the unit does not send comes from a newer firmware than the unit's.
  • Expect newer values. An enum value a client does not know (a FieldIssue.Kind, a Feature) comes from a firmware newer than the client; proto2 libraries keep it as an unknown field and report the default instead.
  • Keep what you do not know. Settings read from the unit and sent back should keep their unknown fields (protobuf libraries do this when a message is read and written again), so nothing a client does not know gets lost.
  • The schema id names the exact files (Info.schema_id). It changes with every addition, so it says which reference page matches a unit, not whether a client works with it.

service SettingsService

The settings API. See the file overview for the protocol, errors and concepts.

GetInfo (InfoRequest) → Info

POST /vp_control.v1.SettingsService/GetInfo

The unit, its firmware, and the state of its settings (epoch, applied updates, save layer).

GetSettings (GetSettingsRequest) → Settings

POST /vp_control.v1.SettingsService/GetSettings

The live settings (every field), the defaults, or one stored layer (only the fields it sets).

POST /vp_control.v1.SettingsService/UpdateSettings

Changes settings, all or nothing: it validates every present field first (nothing changes if one has an issue), then queues the update for the video processor and returns. Updates arriving less than 50 ms apart are applied together, the later value of a field winning. Some settings that the unit renders itself (the bezel raster, Analog Path Simulation) can take effect some seconds after Info.applied_seq says the update was applied.

POST /vp_control.v1.SettingsService/SaveSettings

Saves the live settings into the save layer and returns once they are saved.

POST /vp_control.v1.SettingsService/ListChoices

The entries of one of the OSD's choice lists, and which one is current.

POST /vp_control.v1.SettingsService/RunAction

Runs one of the OSD's combined actions (pick a look or bezel, reset the analog path) after the updates queued before it; returns once it is applied.

GetStatus (StatusRequest) → Status

POST /vp_control.v1.SettingsService/GetStatus

The unit's readouts and the reasons a feature does not run (the OSD's texts), worked out for each request.

Messages

message InfoRequest

GetInfo takes no arguments.

message Info

The unit, its firmware and the state of the settings: read it before GetSettings, and poll it to see when an update is done.

firmware_version = 1 string

The firmware version, e.g. 4.0.87.

product = 2 string

The firmware's product: morph4k for the Morph 4K.

schema_id = 3 fixed32

A hash of this API's schema (settings.proto and this file) as the firmware was built with it: the API reference page of the same schema shows the same id. Every addition changes it, so a different id is no incompatibility (see "Versions and compatibility" in the file overview).

context_id = 4 string

Where the live settings come from: engine, console, video standard, output resolution, then the console or game context. For display; the format may change.

loaded_preset = 5 string

The name of the preset loaded last, if any.

applied_seq = 6 uint32

The highest apply_seq that is done: applied, or dropped because the settings were replaced first (then it lies in dropped_first..dropped_last). An update is done when applied_seq >= UpdateSettingsReply.apply_seq.

settings_epoch = 7 uint32

Counts each time the live settings are replaced as a whole (video mode or engine change, a console or game context, a preset). See "Settings epoch" in the file overview.

dropped_first = 8 uint32

The apply_seq range of the last updates that were dropped because the settings epoch changed before they were applied; 0 and 0 when none was dropped yet.

dropped_last = 9 uint32

The end of that range (see dropped_first).

The layer saves of these settings go into (Morph 4K: LAYER_VIDEO_MODE). Settings of the global layer are saved there whatever this says.

active_resolution = 11 string

The output resolution as it runs, e.g. 4K or 1080p. It can differ from the configured Settings.output while a mode forces another one (Tate's Triple Buffer, the output limits' fallback, FX Direct).

active_buffer_mode = 12 uint32

The buffer mode as it runs (values as Output.buffer_mode); see active_resolution.

active_true_vrr = 13 bool

Whether True VRR runs; see active_resolution.

The triple buffer mode as it runs (values as Output.triple_buffer_mode); see active_resolution.

bezel_status = 15 string

Bezel Art's state, as the Bezel & Glass page shows it: loading 45% while the art loads into the unit, a reason when it cannot be shown (not on SD card, raster missing, needs 4K or 1080p, ...), empty when it is shown or no bezel is picked. Absent on a product without bezel art.

bezel_shown = 16 bool

Whether bezel art is on screen now. Absent on a product without bezel art.

bezel_folders = 17 uint32

The Bezel Studio folders this firmware reads, which the Studio checks before it saves: 2 = format 2 folders (the Morph makes the hardware files on the first load) under /sdcard/user/bezels/<tv>/<framing>/. Absent: an older firmware (to 4.1.0: format 1 folders in /sdcard/bezel/), or a product without bezel art.

features = 18 repeated Feature

What the running video engine and the unit's tier offer: the OSD shows a page or line only where its Feature is listed here, and a client can do the same. Settings of a missing feature can still be read and set; they have no effect. Only the values the unit's tier lacks are rejected (FieldIssue.NOT_IN_THIS_TIER). It changes when another engine loads. Absent (empty) on firmware before it: show everything.

settings_hash = 19 fixed32

A checksum (CRC-32) of the live settings: it changes whenever any setting of Settings changes, whoever changes it (the OSD, this API, the console, a preset, the web UI). A client that polls GetInfo reads GetSettings again when it moves, instead of polling GetSettings. Its value means nothing beyond that and may change between firmware versions.

deinterlacer_max = 20 uint32

The highest Method of the Deinterlacer (Scaler.deinterlacer) the unit's tier offers; the OSD lists the methods up to it. Absent on firmware before it.

output_trial_left = 21 uint32

The seconds left before an output change on trial (UpdateSettingsRequest.trial) is reverted; absent when none is on trial.

System › Preset Auto-Load for the running engine as stored (a change takes effect after a restart); absent where the unit has none.

preset_loading = 23 bool

A preset load this API started (a Color Profile, a preset, an auto preset, Restore previous or default settings) is under way: they run one at a time, and saves wait. Absent on firmware without them.

engine_status = 24 string

An engine or input pick of this API's (ENGINES, INPUTS): "Loading" with the engine's name while it loads, why it did not load (the OSD's words, e.g. "Spatial Super Resolution is not installed. Still running ..."), or empty. Absent on firmware without them.

auto_rotation = 25 uint32

Processing Engine › Auto Rotation (AutoRotation.mode). Absent where there is none.

The captures (RunAction capture_input and capture_output): whether one runs, and how the last one this API started ended. Absent on a product without captures.

message CaptureState

The state of the captures (Info.capture).

running = 1 bool

A capture runs now: one of this API's, or one from the remote or the console. A new one is refused (unavailable) until it ends.

done_seq = 2 uint32

The highest RunActionReply.capture_seq that has ended (saved, failed or canceled); 0 before the first. A capture is done when this reaches its number.

file = 3 string

The file the last one saved, e.g. /sdcard/user/captures/output_0003.png (with CaptureOutput.crc_only the .crc). Download it with a GET of this path from the unit's web server. Empty when it did not save.

error = 4 string

Why the last one did not save, in a few words (e.g. "no capture in this engine", "canceled"); empty when it saved.

moving = 5 bool

The last screenshot was saved, but the picture kept changing while it was read: some lines may come from other frames.

progress = 6 uint32

While a screenshot runs (also one from the remote or the console): how far it is, in percent. 0 while the picture freezes, then by the parts read, at most 99 until it ends. Absent while none runs and for an input capture (about a second).

message GetSettingsRequest

Which settings GetSettings returns.

layer = 1 Layer default LAYER_RESOLVED

The live settings (default), the defaults, or one stored layer (sparse).

message FieldPath

A field of Settings, by field numbers from the root: [4, 103, 7] is Settings.input (4) › Input.bezel (103) › Bezel.strength (7). A path that ends at a message names all of it. Field numbers do not change when fields are renamed.

tag = 1 repeated uint32

The field numbers, root first (up to 6).

message UpdateSettingsRequest

Changes settings: all of the request or nothing.

The new values: every field present here is set; absent fields keep their value. Sub-messages merge field by field.

clear = 2 repeated FieldPath

Fields to remove from the save layer, so they take the value of the layers below again (a path to a message clears all of its fields). Done before set, and it needs a save: not with SAVE_NONE. Up to 8 paths. A value below that the unit's tier does not have is lowered to the tier's limit, as a settings load does (see FieldIssue.NOT_IN_THIS_TIER).

save = 3 SaveMode default SAVE_LIKE_OSD

When to save the change (default: as the OSD does).

Where to save: absent or Info.save_layer (no other layer yet: unimplemented).

dry_run = 5 bool

Validate only: the reply says whether the update would be accepted and lists the issues; nothing changes.

Act only if the unit's settings epoch is still this one (else failed_precondition).

trial = 7 bool

Try the output change, as the OSD's Output Resolution and Frame/Sync Lock confirm it: Output.resolution, buffer_mode, true_vrr and true_vrr_tate only (anything else, or a clear, is invalid_argument). The change applies but is not saved, and the unit puts the output it replaced back after 30 s (Info.output_trial_left) unless RunAction.keep_output keeps it, so a client that drops off the network still gets its picture back. A second trial before then keeps the first one's output to go back to. An update without trial that sets these fields ends the trial (it stays as set). A change to what already runs starts no trial.

message FieldIssue

Why a field of an update cannot be taken.

The field.

What is wrong with it.

min = 3 double

The lowest value the field takes (OUT_OF_RANGE, INVALID).

max = 4 double

The highest value the field takes (OUT_OF_RANGE, INVALID).

enum FieldIssue.Kind

The kind of problem.

OUT_OF_RANGE = 1

The value is outside the field's range (min / max).

NOT_ON_THIS_PRODUCT = 2

The field does not exist on this product or firmware build, or this firmware does not know it (a client built for a newer schema).

READ_ONLY = 3

The field can be read but not set.

INVALID = 4

The value is no value of the field: a text that is no fraction, NaN, a zoom of 0. min / max give the range for reference.

NOT_IN_THIS_TIER = 5

The value needs a feature this unit's tier (edition) does not have: Smoothing, a deinterlacer Method above the tier's, a zoom other than Fill, Adaptive scanlines, the Mask. The fields' documentation names what the tier allows; no min / max. The OSD hides these lines on such a unit.

message UpdateSettingsReply

The result of UpdateSettings.

accepted = 1 bool

Whether the update was taken: false if there is any issue, and then nothing changed.

issues = 2 repeated FieldIssue

One entry per field that cannot be taken.

apply_seq = 3 uint32

When accepted: the update's sequence number. It is done (applied, or dropped because the settings were replaced first) when Info.applied_seq >= apply_seq.

settings_epoch = 4 uint32

The settings epoch the update belongs to.

message SaveSettingsRequest

Saves the live settings into a layer (a "Save" button), after any update still pending.

The layer: absent or Info.save_layer (no other layer yet: unimplemented).

Act only if the unit's settings epoch is still this one (else failed_precondition).

message SaveSettingsReply

The result of SaveSettings.

The layer the settings were saved into.

message ListChoicesRequest

Lists one choice list.

The list.

message Choice

An entry of a choice list.

name = 1 string

The entry's name as the OSD shows it.

folder = 2 string

BEZELS: the bezel's folder under /sdcard/user/bezels/, <tv>/<framing> or <tv> ("" for Off). COLOR_PROFILES: the file's folder under /sdcard/presets ("" at the top).

variant = 3 string

BEZELS: the variant within the folder.

refused = 4 string

BEZELS: why the running engine cannot show this bezel; empty if it can. It can still be picked, as on the OSD.

value = 5 string

OUTPUT_RESOLUTIONS: the value to set as Output.resolution (the name is the OSD's).

detail = 6 string

OUTPUT_RESOLUTIONS: the size and rate the OSD shows next to the name, e.g. 3840x2160 or 1920x1080 120Hz. GAME_PRESETS: the level's preset file, as the OSD shows it.

read_only = 7 bool

PRESETS: one of Pixel FX's (under System/): it can be loaded, not saved over or deleted.

saved = 8 bool

GAME_PRESETS: a preset is saved at this level.

about = 9 string

ENGINES: the OSD's description of the engine.

message ListChoicesReply

The entries of a choice list.

choices = 1 repeated Choice

The entries in the OSD's order, Off first.

current = 2 sint32

The index of the entry the current settings were set from, also when its values were changed since (the OSD then shows the name with a star, e.g. "Soft Tube*"); -1 for none (custom values, a bezel not on the card).

modified = 3 bool

Whether a value the current entry sets was changed since it was picked: the OSD shows the name with a star then ("Soft Tube*"). False for the lists where the OSD shows none.

message Choose

Picks an entry of a choice list, as the OSD does.

The list.

name = 2 string

The entry's name (case-insensitive).

folder = 3 string

BEZELS: the entry by folder instead of name ("" = Off). A folder put on the card since the last scan is found too: the unit scans the card again once when the folder has a bezel.json (~1-2 s). Picking the bezel that is shown again after its files were replaced on the card loads it again. COLOR_PROFILES: the file's folder (with name, the file's name).

variant = 4 string

BEZELS: the variant ("" = the folder's first).

message ApsConsoleDefaults

Analog Path Simulation › Reset to Console Defaults: the analog path's values for the selected console. AnalogPath.enable and console stay as they are.

message CrtFitBezel

Curvature › Fit Bezel to Curve: Bezel Sides and Bezel Top/Bottom (and, where the engine has them, the two Bow lines) just deep enough to hide the curved edge, as the OSD's action sets them.

message KeepOutput

The output change on trial (UpdateSettingsRequest.trial) is kept and saved, as the OSD's OK on its Keep this resolution? screen does. failed_precondition if none is on trial. Not tied to a settings epoch: the output change itself starts a new one.

message RevertOutput

The output the trial replaced comes back at once, as the OSD's Back on its confirm screen. failed_precondition if none is on trial. Not tied to a settings epoch, as KeepOutput.

message SavePreset

Presets › Create new preset (a new name) or a save over one of the user's presets (overwrite; it keeps the parts the file holds, as the OSD's save to the loaded preset). All settings, as the OSD saves them. failed_precondition for a name that exists without overwrite, for Pixel FX's presets and for Auto/ (save_game_preset). RunActionReply.saved_as names the file.

folder = 1 string

The folder under /sdcard/presets; absent: New, where the OSD puts a new preset.

name = 2 string

The preset's name: also its file name, without .ini.

overwrite = 3 bool

Replace an existing preset of the user's.

message PresetRef

A preset by its place in PRESETS.

folder = 1 string

The folder under /sdcard/presets ("" at the top).

name = 2 string

The file name without .ini.

message GamePreset

Presets › Auto preset save as / Delete auto preset at one of the levels GAME_PRESETS lists, by its name there. All settings, as the OSD saves them.

level = 1 string

The level's name in GAME_PRESETS.

message RestorePrevious

Presets › Restore previous settings: the settings from before the last preset load (the OSD's, when its Presets menu opened; this API's, before its own load). A preset load: a new settings epoch.

message RestoreDefaults

Presets › Restore default settings: the running engine's video settings as on a fresh start; the output, HDR, the input and the buffer mode stay. A new settings epoch.

message PresetAutoLoad

System › Preset Auto-Load for the running engine: loads the matching auto preset when a source mode is recognized; as on the OSD, a change takes effect after a restart.

on = 1 bool

On or off.

message AutoRotation

Processing Engine › Auto Rotation: what a vertical arcade core does (Info.auto_rotation).

mode = 1 uint32

0 Off (engines change only when picked), 1 Switch Engine (a vertical core loads Tate Mode, a horizontal one the engine before), 2 In Tate Mode (Tate Mode stays and runs horizontal cores too).

message BezelFit

Bezel Art › Fit Picture to Opening with one of the shown bezel's sizing profiles (its bezel.json profiles): the picture's size, position and curvature from that profile, as the OSD's Fit does with the current one. The profile then becomes the bezel's current one, so the OSD's Fit applies it too. Needs a bezel shown (else failed_precondition). The fit runs in the background after the reply, ~1-2 s; a profile the folder does not have leaves the picture as it is (the OSD shows "profile missing").

profile = 1 string

The profile's id in the folder's bezel.json (e.g. flat, flat_integer); "" or absent: the current one.

message CaptureInput

Input capture: the source frame as the unit stored it, before any processing, saved as a PNG on the SD card (/sdcard/user/captures/capture_NNNN.png), as the remote's input capture key does. Needs an engine with input capture (Universal Adaptive) and a progressive source; elsewhere the capture ends with a reason in Info.capture.error. It takes about a second; the picture keeps running. As with the key, the OSD shows "Capturing ..." and the result while no menu is open.

message CaptureOutput

Screenshot (output capture): the output picture as it goes to the TV, saved as a PNG on the SD card (/sdcard/user/captures/output_NNNN.png) with a CRC-32 of each line (.crc) and the settings of that moment as a preset (.ini), as the remote's capture key does. The picture freezes while it is read: about 2 minutes at 4K60, less for fewer lines. The remote's capture key or cancel_capture stops it. Needs an engine with output capture; elsewhere the capture ends with a reason in Info.capture.error. As with the key, while no menu is open the OSD shows a notice with the progress and then the result; not with with_osd, whose screenshot would show it.

with_osd = 1 bool

Capture after the OSDs: what the HDMI output carries, menus and notices included. Default: before them, the picture only.

crc_only = 2 bool

Only the line CRCs (.crc), no PNG: to compare two pictures line by line.

fast = 3 bool

Read each part once, without the check read: faster, but a picture that changes during the capture goes unnoticed.

no_freeze = 4 bool

Do not freeze the picture: the capture then needs a still picture.

first_line = 5 uint32

With line_count: the first line to capture (0 is the top).

line_count = 6 uint32

Only this many lines from first_line (0 or absent: the whole picture). A range outside the picture ends the capture with an error.

message CancelCapture

Stops the running screenshot (capture_output, also one from the remote or the console); it ends as canceled. failed_precondition when none runs. An input capture cannot be stopped.

message RunActionRequest

Runs one of the OSD's combined actions.

Pick an entry of a choice list.

Reset the analog path to the console's defaults.

Fit the picture to the shown bezel's opening with one of its sizing profiles.

Fit the bezel to the curve (Curvature).

Keep the output change on trial (UpdateSettingsRequest.trial).

Put back the output the trial replaced.

Save the settings as a preset.

Delete a preset of the user's.

Save the settings as the auto preset of a level (GAME_PRESETS).

Delete the auto preset of a level.

Put back the settings from before the last preset load.

The running engine's settings back to their defaults.

Preset Auto-Load for the running engine.

Auto Rotation (Processing Engine).

Save the source frame as a PNG (input capture).

Save the output picture as a PNG (screenshot).

Stop the running screenshot.

save = 8 SaveMode default SAVE_LIKE_OSD

When to save the result (default: as the OSD does).

Act only if the unit's settings epoch is still this one (else failed_precondition).

message RunActionReply

The result of RunAction.

apply_seq = 1 uint32

The action's sequence number; it is applied when the reply comes.

settings_epoch = 2 uint32

The settings epoch the action ran in.

saved_as = 3 string

save_preset, save_game_preset: the file saved, under /sdcard/presets.

capture_seq = 4 uint32

capture_input, capture_output: this capture's number. It runs in the background after the reply and has ended (saved, failed or canceled) when Info.capture.done_seq reaches it.

message StatusRequest

Asks for the unit's readouts (GetStatus).

message Status

The unit's readouts and the reasons a feature does not run, as the OSD's pages show them: texts in the OSD's words. A client asks for them only while it shows one: unlike Info, they are worked out for each request. A field is absent where the product or the running engine has no such line.

source_width = 1 uint32

Source: the active picture the unit samples, per line (the Scaler page's per-input size).

source_height = 2 uint32

The active lines of that picture.

source_hz = 3 uint32

The source's frame rate: 50 or 60 (Hz), 0 when there is no signal or another rate.

interlaced = 4 bool

Whether the source is interlaced.

engine = 5 string

The running engine's name.

scale_h = 6 float

Scaler › Zoom: the horizontal scale factor as the OSD shows it (screen horizontal; a rotated Tate picture's factors swapped, as there).

scale_v = 7 float

The vertical scale factor (see scale_h).

decimator_auto_h = 8 uint32

Decimator › Detected: the factor Auto found across.

decimator_auto_v = 9 uint32

The factor Auto found down.

captured_width = 10 uint32

The samples per line the unit captures before decimation: Custom's starting point and largest Out Width.

captured_height = 11 uint32

The lines it captures (Custom's Out Height).

Deinterlacer › Detected (Film (Auto)): what the source is right now, e.g. "3:2, locked" or "progressive"; absent without the film detector.

aps_status = 13 string

Analog Path Simulation › APS Status › Status: "Off", "Starting", "Paused", "Running x2".

aps_reason = 14 string

APS Status › Reason: why it is paused; empty when it is not.

beam_game = 15 string

Beam Scan › Game: "60 Hz", "50 Hz" or "No Signal".

beam_output = 16 string

Beam Scan › Output: the output and what it needs, e.g. "4K60 (need 1080p120)".

beam_buffering = 17 string

Beam Scan › Buffering: "MagicLock2", "Triple Buffer" or "Frame Lock".

beam_status = 18 string

Beam Scan › Status: "Off", "Active", "Retro FX Off" or "Waiting for Setup".

beam_output_ok = 19 bool

Whether the output is the one Beam Scan needs (the OSD shows Output orange when not).

Whether the buffering is the one Beam Scan needs.

Amplifier Blur: the Look needs a wider sampling mode, such as generic 1280 (off until then).

Amplifier Blur: with the Analog Path running, the Look is the set's (set_preset), not the connection's (preset).

gamut_needs_csc = 23 bool

Gamut & White Point: on, but Color Correction › HDR is Disabled (Needs Setup).

mask_too_fine = 24 bool

Mask: the tube's mask is too fine for this output and is drawn coarser.

Tube Sag › Picture Edge: true "Behind Bezel", false "Visible".

bezel_tracking = 26 sint32

Bezel Reflection: the shown bezel's own Tracking (what Bezel.tracking -1 uses); -1 none.

bezel_edge_gloss = 27 sint32

The shown bezel's own Edge Gloss (what Bezel.edge_gloss -1, Auto, uses); -1 none.

tate_rotated = 28 bool

Scanlines: the picture is turned (Tate): the lines run across the horizontal axis.

Enums

enum Layer

A source of settings: the live settings are these layers merged, later ones over earlier ones.

GetSettings of a single layer is sparse: only the fields that layer sets. On the Morph 4K the settings of this API live in the defaults, the global layer (Output and Hdmi) and the running engine's video mode layer, which is where saves go (Info.save_layer).

LAYER_RESOLVED = 0

The live settings: all layers merged (every field set).

LAYER_DEFAULTS = 1

The firmware's defaults (every field set).

LAYER_GLOBAL = 2

Settings stored for the whole unit, whatever the video mode: Output and Hdmi.

LAYER_VIDEO_MODE = 3

Settings stored for the current video standard and output resolution of the running engine.

LAYER_CONSOLE = 4

Settings stored for the detected console. Holds none of this API's settings yet (empty).

LAYER_ENGINE = 5

Not a layer of its own: the engine selects which tree of layers is used (empty).

LAYER_GAME = 6

Settings of the detected game (Morph: the context preset). Not available yet (unimplemented).

enum Feature

A page or line of the OSD's Video menu that only some video engines or tiers have (Info.features). Named after what the OSD shows, in its words.

FEATURE_UNSPECIFIED = 0

Not a feature (never listed).

FEATURE_ANALOG_PATH = 1

Analog Path Simulation: the engine has APS (AnalogPath).

FEATURE_APS_EDGE_SMEAR = 2

APS Edge Smear.

FEATURE_APS_CHROMA_DELAY = 3

APS Chroma Delay.

FEATURE_APS_BLACK_LEVELS = 4

APS TV Black Level and Console Setup.

FEATURE_APS_COLOR_KILLER = 5

APS Auto Color (ACC) and Color Killer.

FEATURE_APS_BLACK_BREATHING = 6

APS Black Breathing.

FEATURE_APS_IF_RESPONSE = 7

APS IF Response (RF Reception).

FEATURE_APS_HUE_JITTER = 8

APS Hue Jitter (RF Reception).

FEATURE_APS_CHROMA_WAVEFORM = 9

APS Chroma Waveform (Console Output).

FEATURE_APS_OUTPUT_CLIPPING = 10

APS Output Clipping (Console Output).

FEATURE_APS_VCR = 11

APS VCR / Tape.

FEATURE_BEZEL = 12

Bezel & Glass: bezel art (Bezel).

FEATURE_BEZEL_REFLECTION = 13

Bezel Reflection.

FEATURE_PHOSPHOR_GLOW = 14

Phosphor Glow (PhosphorGlow).

FEATURE_GLOW_DITHER = 15

Phosphor Glow's Dither.

FEATURE_EDGE_DIMMING = 16

Edge Dimming and Dimming Shape.

FEATURE_AMPLIFIER_BLUR = 18

Amplifier Blur.

FEATURE_AMPLIFIER_BLUR_APS = 19

Amplifier Blur's looks while Analog Path Simulation runs (Input.crt_blur_set_preset).

FEATURE_SCANLINES = 20

Scanlines (the Retro FX page with Normal and Dynamic).

FEATURE_SCANLINES_ADAPTIVE = 21

Scanlines Adaptive.

FEATURE_WIDTH_FOLLOWS = 22

Scanlines Width Follows.

FEATURE_CONVERGENCE = 23

Convergence: Horizontal Look, Red and Blue.

FEATURE_CORNER_CONVERGENCE = 24

Convergence's Vertical Look, Stretch and Tilt (Corner Convergence).

FEATURE_MASK = 25

Mask (with its tube mask).

FEATURE_CURVATURE = 26

Curvature.

FEATURE_CURVATURE_VERTICAL = 27

Curvature's Vertical Curve.

FEATURE_CURVATURE_BEZEL = 28

Curvature's Bezel Sides, Bezel Top/Bottom and Fit Bezel to Curve.

FEATURE_BEZEL_BOW = 29

Curvature's two Bow lines (Bezel Bow).

FEATURE_FITTED_WINDOW = 30

Bezel Art's Window Shape (Fitted to Art) and Window Inset; the OSD shows them while a bezel is shown.

FEATURE_TUBE_SAG = 31

Tube Sag.

FEATURE_GAMUT = 32

Gamut & White Point.

FEATURE_BEAM_SCAN = 33

Beam Scan (CRT Simulation).

FEATURE_BEAM_SCAN_PERSISTENCE = 34

Beam Scan's Persistence and Strobe Length.

FEATURE_BFI = 35

BFI (Advanced Video), on engines without Beam Scan.

FEATURE_SCALER_4TAP = 36

The Scaler's Mitchell, Catmull-Rom and Lanczos, and Anti-Ringing Light / Strong.

FEATURE_ANTI_RINGING = 37

The Scaler's Anti-Ringing.

FEATURE_SMOOTHING = 38

Smoothing.

FEATURE_SMOOTHING_FILTER = 39

Smoothing's Filter (super-xBR, xBRZ, Super Eagle).

FEATURE_ROTATION = 40

The Scaler's Rotation (the Tate Mode engine).

FEATURE_ROTATION_UPRIGHT = 41

Rotation Off (upright).

FEATURE_FREE_SCALING = 42

A Zoom set by hand (Zoom Mode Manual and the custom size).

FEATURE_COLOR_CORRECTION = 46

Color Correction.

FEATURE_DEINTERLACER = 47

Deinterlacer.

FEATURE_FILM = 48

The Deinterlacer's Film (Auto).

FEATURE_FILM_CADENCE = 49

The Deinterlacer's Film Cadence.

FEATURE_EDGE_SMOOTHING = 50

The Deinterlacer's Edge Smoothing.

FEATURE_EDGE_SMOOTHING_LEVELS = 51

Edge Smoothing Medium and High (else Low only).

FEATURE_MOTION_DETAIL = 52

The Deinterlacer's Motion Detail.

FEATURE_IP_CHANGE_BLANK = 53

The Deinterlacer's I/P Change Blank.

FEATURE_VRR_OUTPUT = 54

VRR (True VRR) in the Frame/Sync Lock list.

FEATURE_MAGICLOCK = 55

Magiclock 2 / Genlock in the Frame/Sync Lock list.

FEATURE_FRAME_LOCK = 56

The Frame Lock modes in the Frame/Sync Lock list.

FEATURE_VRR_SIGNALLING = 57

Inject VFR-EMP (VRR signalling).

FEATURE_BEZEL_MIRROR = 58

Bezel Reflection's Mirror, Mirror Depth and Mirror Offset (Bezel.mirror ..).

enum SaveMode

When an update is saved.

SAVE_LIKE_OSD = 0

As the OSD saves: 3 s after the last change, one save for a burst of changes, into the layer the OSD saves into now.

SAVE_NOW = 1

Right after the change is applied.

SAVE_NONE = 2

Not saved by this update: the change is lost at the next reload (resolution, console, engine or game change), unless another save (the OSD's, another update's, SaveSettings) stores it first, together with everything else.

enum ChoiceList

A list of the OSD's whose entries each set several fields together, from data on the unit (a look's values for the running engine, the bezels on the SD card).

ListChoices shows a list; RunAction with Choose picks an entry as the OSD does. UpdateSettings stores fields as they are (as a preset does) and never does this.

CHOICE_LIST_UNSPECIFIED = 0

No list (invalid in a request).

PHOSPHOR_GLOW_LOOKS = 1

Phosphor Glow looks: Off, then the looks. Off turns PhosphorGlow.on off; a look turns it on and sets look, strength, size_q and tint.

BEZEL_REFLECTION_LOOKS = 2

Bezel Reflection looks: Off, Subtle, Normal, Strong. Off turns Bezel.reflection off; a look turns it on and sets strength (from the shown bezel's measured peak brightness, or its own tuned look), response, cap, falloff, falloff_shape, soft_start, soft_end, tracking and edge_gloss; the Mirror lines stay as they are.

ANALOG_PATH_LOOKS = 3

Analog Path Simulation looks: Off, then one per connection. Sets AnalogPath.enable and connection.

BEZELS = 4

Bezel Art: Off, then the bezels on the SD card. Sets Bezel.folder and variant.

CURVATURE_PRESETS = 5

Curvature › Preset: sets CrtCurve.profile and the four curve lines (Horizontal Curve, Side Bow, Vertical Curve, Corner Radius).

TUBE_SAG_LOOKS = 6

Tube Sag's look: sets TubeSag.sag_look, breathing (Picture Size), line_bulge (Line Width) and speed.

CONVERGENCE_H_LOOKS = 7

Convergence › Horizontal Look: sets ConvergenceCorner.side_look and Convergence Red and Blue.

CONVERGENCE_V_LOOKS = 8

Convergence › Vertical Look: sets ConvergenceCorner.corner_profile, corner_size (Stretch) and corner_tilt (Tilt).

GAMUT_LOOKS = 9

Gamut & White Point › Look: sets Gamut.look, phosphors, white, and decoder to Auto.

MASK_TUBES = 10

Mask › Tube (Physical): sets TubeMask.tube, layout, size and pitch.

BEAM_PROFILES = 11

Scanlines › Beam Profile (Dynamic): sets DynamicScanlines.profile and its values.

ADAPTIVE_LOOKS = 12

Scanlines › Look (Adaptive): sets the Adaptive2 depths, widths and brightness; ramp (Width Growth) stays.

OUTPUT_RESOLUTIONS = 13

Output Resolution: the modes the OSD lists, current the running one. Listed only: a client sets Output.resolution to an entry's value with UpdateSettings, best with trial as the OSD confirms it (choose is failed_precondition).

MASK_TYPES = 14

Mask › Type (Pattern): the masks on the SD card (/sdcard/presets/mask.cache). Sets the pattern; On / Off stays.

COLOR_PROFILES = 15

Color Correction › Color Profile: the preset files under /sdcard/presets (folder and name). Choosing one loads its color settings (input and output gamma, CSC) as the OSD does: a preset load, so a new settings epoch, done in the background just after the reply. A file without color settings is failed_precondition. current is always -1. The card is read again when the list is asked for more than 5 s after the last time.

PRESETS = 16

Presets: the same preset files as COLOR_PROFILES (folder and name; read_only for Pixel FX's under System/). Choosing one loads all of it as the OSD's preset browser does: the settings as they were are kept for RunAction.restore_previous first, then a preset load (a new settings epoch) in the background just after the reply; Info.loaded_preset names it. current is the loaded one, -1 for none. The card is read again as for COLOR_PROFILES.

GAME_PRESETS = 17

Presets › auto presets for what runs now: the OSD's levels (by the game, the console system, the analog input or the mode, each for the input's width and height, its width only, or neither, and the Default), those the source has; detail is the preset file under Auto/ as the OSD shows it, saved whether there is one. Choosing a saved one loads it as PRESETS does; the others are failed_precondition. current is the loaded one, -1 for none.

INPUTS = 18

Input Select: HDMI, then the signal types of the analog ports the OSD lists (those of a fitted Analog Bridge, not hidden), folder the port as the connector card names it ("A: SCART"), detail the OSD's description. Choosing one switches the input as the OSD does, in the background just after the reply (a new settings epoch). current is the active input.

ENGINES = 19

Processing Engine: the OSD's engines with their limits (detail) and description (about); refused when the engine's file is missing or not for this unit (the OSD's words). Choosing one loads it as the OSD does, in the background just after the reply: the picture blanks for a few seconds, a new settings epoch follows, Info.engine_status tells how it went. current is the running engine.

PixelFX video settings (vp_control.v1.Settings)

vp_control/v1/settings.proto

The video settings of a PixelFX unit (Morph 4K) as one tree: what the OSD's Video pages set, for the picture the unit shows now. The settings API (settings_service.proto) reads and changes them; preset files carry the same settings as INI sections.

Reading these docs

  • Names. Each setting is named in bold as the OSD names it, with its place in the menus where it has one (OSD: **Video › Retro FX › Bezel & Glass**).
  • Range. A number's valid range is in its (fx.v1.min) / (fx.v1.max) options; the API rejects values outside it (FieldIssue.OUT_OF_RANGE). The text names the values that have a meaning of their own (-1 Auto, 0 Off,...). Fields without a range take any value of their type.
  • Numbered choices. Choices are plain integers; a table lists what each number means, in the OSD's words.
  • Units are given in the text; a suffix in the field name repeats them (_pct: percent, _deg: degrees, _ns: nanoseconds).
  • Text formats. A string with (fx.v1.fraction) holds a fraction "num/den"; one with (fx.v1.matrix) holds a square matrix of numbers, row by row, joined by |.
  • Products. The settings exist on the Morph 4K. A field marked (fx.v1.only_if) exists only on builds where that feature is; elsewhere the API answers NOT_ON_THIS_PRODUCT.
  • Tiers. Some values need a feature of the unit's tier (edition): Smoothing, the higher deinterlacer Methods, a zoom other than Fill, Adaptive scanlines, the Mask. On a unit whose tier lacks it the OSD does not offer the value, a settings load lowers it, and the API rejects it (NOT_IN_THIS_TIER). The fields name their limits.

Presence and layers

The messages are proto2, so each field has presence. GetSettings of the live settings sets every field; an update, a stored layer or the defaults carry only the fields they set, and absent fields mean "unchanged" or "inherited". Most settings are stored per video mode (video standard and output resolution, per engine); the settings of the whole unit (Output and Hdmi) are stored globally. See Layer in settings_service.proto.

Settings tree

Every message of Settings by its path, the name a client uses for a field (input.bezel.strength).

  • scaler Scaler Scaler processing: the Deinterlacer, Smoothing, Anti-Ringing, and black frame insertion or Beam Scan.
    • scaler.film_set FilmSet Film (Auto)'s own Deinterlacer settings: the same settings as Motion Adaptive's in Scaler, used while the Method (Scaler.deinterlacer) is Film (Auto) on a bitstream that has it.
  • input Input Input settings: what happens to the source picture before it is scaled (crop, the Decimator's manual factor), the Amplifier Blur and Convergence of CRT Simulation, and the Retro FX features (fields from 100 on).
    • input.analog_path AnalogPath Analog Path Simulation (APS) recreates the console's video signal on its way to a TV: the console's encoder, the cable or antenna, and the TV's decoder, with their dot crawl, rainbows and color bleed.
    • input.phosphor_glow PhosphorGlow Phosphor Glow is the light scattered in the tube's glass: a soft glow around bright areas.
    • input.crt_curve CrtCurve CRT Curvature bends the picture like the curved glass of a tube, rounds its corners and frames it with a bezel.
    • input.bezel Bezel Bezel & Glass frames the picture with bezel art from the SD card (Bezel Art) and lets the picture light the bezel's angled plastic around the glass (Bezel Reflection).
    • input.retro_fx RetroFx Retro FX master switches: Retro FX, CRT Simulation and Bezel & Glass, each On or Off.
    • input.convergence_corner ConvergenceCorner Corner Convergence splits red and blue above and below green toward the edges and corners, as on real tubes; the center stays clean.
    • input.tube_sag TubeSag Tube Sag makes the picture swell a little on bright scenes, as a tube's power supply sags.
  • gamma_input_table GammaInputTable Input Gamma / Transfer Function decodes the source's 8-bit levels into linear light for the color space conversion: bit_crush_amount, input_gain and input_lift on each level, then the transfer curve (gamma_transfer_func, trans_func_threshold, gamma).
  • gamma_output_table GammaOutputTable Output Gamma / PQ encodes the processed picture for the TV: a gamma curve for SDR and HLG, PQ (SMPTE 2084) for HDR10, with optional dithering.
  • polyphase Polyphase Scanline shape of the Normal (and older Adaptive) scanlines per axis, the scaler's mask flip, anode sag and coefficient file, and the Dynamic and Adaptive scanlines' own values (fields from 100 on).
  • scaler_meta ScalerMeta Picture size and place: the Zoom, Aspect Ratio and Rotation of the Scaler page and the Shift lines of Shift / Crop.
  • csc Csc Color Space Conversion converts the decoded colors to the output's color space and sets their saturation.
  • gamut Gamut Gamut & White Point recreates a CRT tube's phosphor colors and white point in the output's color matrix.
  • input_signal InputSignal Input signal settings written with the input stage: Deblur, Field Order, and the analog video output's format and filter.
  • output Output Output settings: the output resolution and how the output is timed against the source (Frame/Sync Lock, Triple Buffer, VRR).
  • hdmi Hdmi HDMI signalling to the TV: the RGB range, the HDR mode (which also switches the Color Correction pipeline) and VRR signalling.
  • interpolation Interpolation Interpolation: the scaler's kernel per axis and Disable Interpolation at integer scale factors.
  • scaler_polyphase ScalerPolyphase Scanlines mode per axis, and how the scaler rounds its phase steps.
  • mask Mask Mask draws the tube's phosphor mask or aperture grille over the picture: a pattern of up to 16 x 16 cells, one output pixel each, repeated across the screen, that sets each color's gain.
    • mask.tube TubeMask Tube mask (the Mask page's Mode Physical): the unit builds the mask from a real tube's phosphor layout, screen size and pitch, scaled to the picture, instead of using the pattern.

Messages

message AnalogPath

path input.analog_path · preset section [analog-path]

Analog Path Simulation (APS) recreates the console's video signal on its way to a TV: the console's encoder, the cable or antenna, and the TV's decoder, with their dot crawl, rainbows and color bleed. It is made for 15 kHz sources (240p, 288p, 480i, 576i).

OSD: Video › Retro FX › Analog Path Simulation, with these pages:

More:

  • Morph 4K, on a video engine with APS. It runs while enable is On and Retro FX is On (RetroFx.off false).
  • APS pauses by itself while the source does not suit it, and starts again once it does. The OSD's APS Status page gives the reason: "not a 15 kHz source", "already composite" (a composite or S-Video input), "FX-direct source", "sampling rate too low", "line too wide".
  • Some lines need an optional stage of the engine. The OSD hides them where it is missing, and the field then has no effect.
  • APS applies on a task of its own: a change can take effect some time after the update's apply.
  • RunAction ANALOG_PATH_LOOKS (the Retro FX row: Off, Composite, S-Video, RF (Antenna), Blend Only) sets enable and connection. RunAction aps_console_defaults (Reset to Console Defaults) sets every field but enable and console to its default. The defaults are the same for every console; chroma_wave Auto follows the console.
  • While APS runs, Amplifier Blur offers its APS looks (Input.crt_blur_set_preset). APS never turns the blur on or off.
enable = 1 int32 0 … 1 preset [analog-path] aps_enable
input.analog_path.enable

Analog Path: turns the whole analog path on (1) or off (0). Off passes the picture through untouched.

The Retro FX page's Analog Path Simulation row switches the same field.

console = 2 int32 0 … 14 preset [analog-path] aps_console
input.analog_path.console

Console: sets the subcarrier timing, so dot crawl and artifact colors behave like this console's.

ValueMeaning
0Genesis
1SNES
2NES
3PlayStation
4PC Engine
5Nintendo 64
6Master System
7Atari 8-bit
8Commodore 64
9Apple II
10Amiga
11Generic NTSC
12Generic PAL
13Amiga (PAL)
14C64 (PAL)

12 to 14 are PAL consoles (pal_delay_line applies), the others NTSC (decoder applies). A change of console changes no other field; RunAction aps_console_defaults resets them.

connection = 3 int32 0 … 3 preset [analog-path] aps_connection
input.analog_path.connection

Connection: how the console reaches the TV.

ValueMeaning
0Composite
1S-Video (yc_crosstalk_pct leaks some of the composite look into it)
2RF (Antenna): the RF Reception fields apply
3Blend Only: keeps dither blending and color smear without rainbows

The Cable fields apply to every connection but RF.

yc_crosstalk_pct = 4 int32 0 … 50 preset [analog-path] aps_yc_crosstalk_pct
input.analog_path.yc_crosstalk_pct

Y/C Crosstalk (%): leaks a little of the composite look into S-Video, as cheap cables and inputs did. Only with connection S-Video; 0 is clean S-Video.

decoder = 5 int32 0 … 3 preset [analog-path] aps_decoder
input.analog_path.decoder

TV Decoder: how the TV separates color from detail.

ValueMeaning
0Notch Filter
12-Line Comb
23-Line Comb
3Adaptive Comb (comb_sensitivity_pct)

The OSD shows it with connection Composite or RF and an NTSC console. Comb filters suit 227.5-cycle consoles. On a console whose color does not alternate from line to line (Genesis, Master System, Atari 8-bit, Apple II, Amiga) a comb would leave the picture nearly grey, so the Notch Filter runs instead and the OSD says "Comb off: Notch"; the field keeps the comb.

comb_sensitivity_pct = 6 int32 0 … 100 preset [analog-path] aps_comb_sensitivity_pct
input.analog_path.comb_sensitivity_pct

Comb Sensitivity (%): how quickly the adaptive comb falls back to the notch filter on vertical detail. Only with decoder Adaptive Comb.

pal_delay_line = 7 int32 0 … 1 preset [analog-path] aps_pal_delay_line
input.analog_path.pal_delay_line

PAL Decoder: the PAL TV's decoder. Only with a PAL console.

ValueMeaning
0Simple (PAL-S): shows phase errors as Hanover bars
1Delay Line (PAL-D): hides phase errors
dot_crawl_locked = 8 int32 0 … 1 preset [analog-path] aps_dot_crawl_locked
input.analog_path.dot_crawl_locked

Dot Crawl: whether the dots move.

ValueMeaning
0Natural: the dots move like the console's own timing
1Locked: the dots stand still

The OSD shows it with connection Composite or RF.

sharpness = 9 int32 0 … 100 preset [analog-path] aps_sharpness
input.analog_path.sharpness

Sharpness: the TV's peaking control. Higher values add edge ringing.

luma_bw_dmhz = 10 int32 20 … 60 preset [analog-path] aps_luma_bw_dmhz
input.analog_path.luma_bw_dmhz

Luma Bandwidth (tenths of a MHz: 35 = 3.5 MHz): the detail the TV keeps. Lower is softer.

chroma_bw_cmhz = 11 int32 30 … 150 preset [analog-path] aps_chroma_bw_cmhz
input.analog_path.chroma_bw_cmhz

Color Bandwidth (hundredths of a MHz: 60 = 0.60 MHz): how sharp color edges are. Real sets used about 0.5 to 1.3 MHz.

tint_deg = 12 sint32 -30 … 30 preset [analog-path] aps_tint_deg
input.analog_path.tint_deg

Tint (degrees): the TV's hue knob.

color_pct = 13 int32 0 … 200 preset [analog-path] aps_color_pct
input.analog_path.color_pct

Color (%): the TV's saturation knob.

edge_smear_pct = 14 int32 0 … 100 preset [analog-path] aps_edge_smear_pct
input.analog_path.edge_smear_pct

Edge Smear (%): 0 is Symmetric, for digital sets. Above 0 it is Trailing, for analog sets, whose smear and ringing fall to the right.

chroma_delay_ns = 15 int32 0 … 400 preset [analog-path] aps_chroma_delay_ns
input.analog_path.chroma_delay_ns

Chroma Delay (ns): color arriving late against detail, as on sets with slow chroma filters.

tv_black_dire = 16 int32 0 … 75 preset [analog-path] aps_tv_black_dire
input.analog_path.tv_black_dire

TV Black Level (tenths of IRE): the black level the TV expects. A mismatch with the console's (console_setup_dire) raises or crushes blacks.

ValueMeaning
00 IRE (Japan)
757.5 IRE (USA)

The OSD offers these two and shows any other value as Custom.

diff_phase_deg = 17 int32 0 … 15 preset [analog-path] aps_diff_phase_deg
input.analog_path.diff_phase_deg

Diff. Phase (degrees): hue shifting with brightness, as in a worn set.

diff_gain_pct = 18 int32 0 … 30 preset [analog-path] aps_diff_gain_pct
input.analog_path.diff_gain_pct

Diff. Gain (%): saturation changing with brightness.

acc = 19 int32 0 … 1 preset [analog-path] aps_acc
input.analog_path.acc

Auto Color (ACC): holds color and rainbow strength steady when the signal weakens or tuning drifts. 0 Off, 1 On.

killer = 20 int32 0 … 3 preset [analog-path] aps_killer
input.analog_path.killer

Color Killer: drops color entirely when the chroma signal falls too far.

ValueMeaning
0Off
1Low
2Medium
3High
black_breathing = 21 int32 0 … 100 preset [analog-path] aps_black_breathing
input.analog_path.black_breathing

Black Breathing: black level shifting with picture brightness, from imperfect DC restoration. 0 is Off; higher is stronger.

signal_strength_pct = 22 int32 0 … 100 preset [analog-path] aps_signal_strength_pct
input.analog_path.signal_strength_pct

Signal Strength (%): a lower signal means more snow. Only with connection RF.

ghost_pct = 23 int32 0 … 50 preset [analog-path] aps_ghost_pct
input.analog_path.ghost_pct

Ghost (%): the strength of a delayed echo from a reflection off buildings or hills. 0 is Off. Only with connection RF; ghost_delay_dus places it.

ghost_delay_dus = 24 int32 2 … 40 preset [analog-path] aps_ghost_delay_dus
input.analog_path.ghost_delay_dus

Ghost Delay (tenths of a µs: 15 = 1.5 µs): how far right the ghost sits. Only with connection RF and ghost_pct above 0.

sound_beat = 25 int32 0 … 100 preset [analog-path] aps_sound_beat
input.analog_path.sound_beat

Sound Beat: the 920 kHz pattern from the sound carrier, strongest on saturated colors. 0 is Off. Only with connection RF.

drift = 26 int32 0 … 2 preset [analog-path] aps_drift
input.analog_path.drift

Tuning Drift: fine tuning wandering over time. The color pumps unless acc holds it. Only with connection RF.

ValueMeaning
0Off
1Slow
2Fast
fine_tuning = 27 sint32 -20 … 20 preset [analog-path] aps_fine_tuning
input.analog_path.fine_tuning

Fine Tuning: a static tuning error, 0 for none. Color and dither rainbows fade together; acc brings both back. Only with connection RF.

if_slope_pct = 28 int32 0 … 100 preset [analog-path] aps_if_slope_pct
input.analog_path.if_slope_pct

IF Response (%): the tuner's sloped IF filter on the whole signal. 0 is Symmetric; above 0 it is Trailing, with the smear trailing right. acc restores the color it costs. Only with connection RF.

hue_jitter = 29 int32 0 … 3 preset [analog-path] aps_hue_jitter
input.analog_path.hue_jitter

Hue Jitter: hue wobbling from line to line on a weak signal. Only with connection RF.

ValueMeaning
0Auto: follows signal_strength_pct
1Off
2Low
3High
cable_length = 30 int32 0 … 3 preset [analog-path] aps_cable_length
input.analog_path.cable_length

Cable Length: longer cables soften fine detail. With every connection but RF.

ValueMeaning
0Short
1Medium
2Long
3Very Long
reflection = 31 int32 0 … 2 preset [analog-path] aps_reflection
input.analog_path.reflection

Reflection: a faint echo from a mismatched connection. With every connection but RF; reflection_ns places it.

ValueMeaning
0Off
1Light
2Heavy
reflection_ns = 32 int32 50 … 500 preset [analog-path] aps_reflection_ns
input.analog_path.reflection_ns

Reflection Delay (ns): the distance of the echo from the edge that causes it. Only with reflection not Off.

tape = 33 int32 0 … 100 preset [analog-path] aps_tape
input.analog_path.tape

Tape: not on the OSD and no effect on the Morph 4K. It is kept and saved as set.

console_setup_dire = 34 int32 0 … 75 preset [analog-path] aps_console_setup_dire
input.analog_path.console_setup_dire

Console Setup (tenths of IRE): the console's black pedestal. US consoles may add 7.5 IRE.

ValueMeaning
00 IRE
757.5 IRE

The OSD offers these two and shows any other value as Custom. See tv_black_dire.

chroma_wave = 35 int32 0 … 2 preset [analog-path] aps_chroma_wave
input.analog_path.chroma_wave

Chroma Waveform: the waveform of the console's color signal. NES and Atari 8-bit made square-wave chroma; its harmonics give a harder dot pattern.

ValueMeaning
0Auto: the console's own (Square for NES and Atari 8-bit, else Sine)
1Sine
2Square
output_clip = 36 int32 0 … 3 preset [analog-path] aps_output_clip
input.analog_path.output_clip

Output Clipping: where the console's encoder clips bright saturated colors like yellow and cyan.

ValueMeaning
0Off
1130 IRE
2120 IRE
3110 IRE
enc_color_bw_dmhz = 37 int32 5 … 20 preset [analog-path] aps_enc_color_bw_dmhz
input.analog_path.enc_color_bw_dmhz

Encoder Color BW (tenths of a MHz: 15 = 1.5 MHz): the console's own chroma filter, before the TV.

artifact_phase_deg = 38 int32 0 … 355 preset [analog-path] aps_artifact_phase_deg
input.analog_path.artifact_phase_deg

Artifact Phase (degrees): shifts artifact colors against the pixels, for matching a capture.

message PhosphorGlow

path input.phosphor_glow · preset section [phosphor-glow]

Phosphor Glow is the light scattered in the tube's glass: a soft glow around bright areas. The message also holds the tube's Edge Dimming and the room's Room Light.

OSD: Video › Retro FX › CRT Simulation › Phosphor Glow. room_light is on Video › Retro FX › Bezel & Glass (on the Phosphor Glow page when the engine has no bezel layer).

  • Morph 4K, on a video engine with Phosphor Glow (the OSD hides the page otherwise).
  • The glow, Edge Dimming and Damper Wires run while CRT Simulation and Retro FX are On (RetroFx.crt_off, RetroFx.off); Room Light while Bezel & Glass and Retro FX are On (RetroFx.bezel_off).
  • Edge Dimming, Damper Wires and Room Light also work with the glow Off (on false).
  • RunAction PHOSPHOR_GLOW_LOOKS (Off, Clean Set, Soft Tube, Arcade Glare) sets on, and for a look also strength, size_q and tint, as the OSD's Look line does.
on = 1 bool preset [phosphor-glow] phosphor_glow
input.phosphor_glow.on

Phosphor Glow: the glow On (true) or Off. Off leaves the picture untouched by the glow; Edge Dimming, Damper Wires and Room Light do not depend on it.

strength = 3 uint32 0 … 30 preset [phosphor-glow] glow_strength
input.phosphor_glow.strength

Strength (%): how much of the light becomes glow. It changes how bright the glow is, not how far it spreads; 0 shows no glow. An engine with the fine glow map takes at most 25.

size_q = 4 uint32 2 … 16 preset [phosphor-glow] glow_size_q
input.phosphor_glow.size_q

Glow Size (quarters of a percent of the screen width: 3 = 0.75%): how far the glow spreads. Very small sizes stop at the hardware's limit.

tint = 5 sint32 -10 … 10 preset [phosphor-glow] glow_tint
input.phosphor_glow.tint

Glow Tint: the glow's color against the picture. Warm glass glows redder, cool glass bluer.

Below 0 Cool, 0 Neutral, above 0 Warm (the OSD shows "Cool 4", "Warm 10"). At 10 the glow's red is 30% stronger and its blue 30% weaker; at -10 the reverse.

dither_anim = 6 bool preset [phosphor-glow] glow_dither: still, animated
input.phosphor_glow.dither_anim

Dither: hides the fine grain at the glow's faint edge. true Animated moves it every frame, so it disappears; false Still.

The OSD shows it on engines with the glow's dither.

stop_edge = 7 bool preset [phosphor-glow] glow_stops_at: bezel, picture_edge
input.phosphor_glow.stop_edge

Glow Stops At: true Picture Edge keeps the glow on the picture; false Bezel lets it reach the dark band around it, as real glass does.

It has an effect only while the picture's edge is behind a bezel: Curvature On with Bezel Sides, Bezel Top/Bottom or a Bezel Bow (CrtCurve.bezel_h, CrtCurve.bezel_v, CrtCurve.bow_h, CrtCurve.bow_v), or Window Shape Fitted to Art (CrtCurve.window_shape 0) with bezel art shown. The OSD shows the line only then; otherwise the glow stops at the picture edge.

room_light = 8 uint32 0 … 4 preset [phosphor-glow] room_light
input.phosphor_glow.room_light

Room Light: room light on the screen, as a share of peak white. It lifts black to a soft gray, as on a real tube, and lifts the bezel art a little too. Off is the deepest black.

ValueMeaning
0Off
10.25%
20.5%
31%
42%

Runs while Bezel & Glass and Retro FX are On, also with the glow Off. It has no effect while the output uses a gamma file or HDR mode is Disabled (Hdmi.hdr_mode 3); the OSD then reads "Gamma File" or "Needs Setup". It stacks on Analog Path Simulation's TV black level (AnalogPath.tv_black_dire).

edge_dim = 9 uint32 0 … 10 preset [phosphor-glow] edge_dimming
input.phosphor_glow.edge_dim

Edge Dimming: the picture is darker toward the edges and corners, as on a real tube; the center stays bright. 0 is Off; each step makes the middle of the edges 3.5% darker (10: 35%).

Works with the glow Off; edge_shape sets its shape. The OSD shows it on engines with Edge Dimming.

edge_shape = 10 uint32 0 … 1 preset [phosphor-glow] dimming_shape: round, wide
input.phosphor_glow.edge_shape

Dimming Shape: the shape of Edge Dimming. Only with edge_dim above 0.

ValueMeaning
0Round: dims every edge alike
1Wide: keeps a larger bright center and dims mostly the sides
room = 12 uint32 0 … 5 preset [phosphor-glow] room: off, night, dim_room, lamp_lit, daylight, arcade
input.phosphor_glow.room

Room: the retired Room preset. It has no OSD line and no effect on the picture: Cabinet Brightness (Bezel.cabinet) and room_light replaced it. It is kept and saved as set.

ValueMeaning
0Off
1Night
2Dim Room
3Lamp-Lit
4Daylight
5Arcade

message Bezel

path input.bezel · preset section [bezel]

Bezel & Glass frames the picture with bezel art from the SD card (Bezel Art) and lets the picture light the bezel's angled plastic around the glass (Bezel Reflection).

OSD: Video › Retro FX › Bezel & Glass, with the Bezel Art and Bezel Reflection pages.

  • Morph 4K, on a video engine with the bezel layer (the OSD hides the page otherwise).
  • The bezel shows while Bezel & Glass and Retro FX are On (RetroFx.bezel_off, RetroFx.off), on a 4K or 1080p output (at 1080p a 960 x 540 version, half the detail). Bezel Reflection needs a 4K output.
  • A new bezel loads from the SD card in the background, and the layer stays off until it is complete (the OSD title shows "loading 40%"): it shows some seconds after the update.
  • RunAction BEZELS picks a bezel as the OSD does: folder, variant, and Window Inset (CrtCurve.window_inset) from the bezel once it shows. ListChoices BEZELS lists the bezels on the card, with the reason where this engine cannot show one.
  • RunAction BEZEL_REFLECTION_LOOKS (Off, Subtle, Normal, Strong) sets reflection, and for a look also every Bezel Reflection value.
  • The Bezel Art page's Window Shape and Window Inset are CrtCurve.window_shape and CrtCurve.window_inset; the Room Light line is PhosphorGlow.room_light.
folder = 1 string preset [bezel] bezel; empty as off
input.bezel.folder

Bezel Art: the folder of a TV or cabinet picture drawn around the screen, on the SD card at /sdcard/user/bezels/<folder>/ (folders made with Pixel FX Bezel Studio): <tv>/<framing> (e.g. sony_kv27s42/full_set), or <tv> for a TV with one framing; at most 63 bytes. "" is Off. To 4.1.0 the folders were in /sdcard/bezel/, one level, which is no longer read.

A folder that is not on the card shows nothing (the OSD says "not on SD card"). Picking a bezel with RunAction BEZELS also sets CrtCurve.window_inset to the bezel's own value; setting folder with UpdateSettings does not.

variant = 2 string preset [bezel] bezel_variant
input.bezel.variant

Bezel Art variant: the id of one of the folder's variants in its bezel.json (e.g. night, day). "" is the folder's first.

An id the folder does not have shows nothing (the OSD says "variant missing").

reflection = 4 bool preset [bezel] bezel_reflection
input.bezel.reflection

Bezel Reflection (On / Off): the picture lighting the bezel's angled plastic around the glass.

It needs a bezel made for it: it has an effect only with a 4K output, a bezel shown whose bezel.json carries the reflection (its lip), and an engine with Bezel Reflection. The values below shape it.

strength = 7 uint32 0 … 80 preset [bezel] reflection_strength
input.bezel.strength

Strength (%): the reflection's light at the glass edge for a full-white picture.

The OSD shows it in cyan where it differs from this bezel's Normal.

response = 8 uint32 25 … 100 preset [bezel] reflection_response
input.bezel.response

Response (hundredths: 45 = 0.45): how the reflection follows the picture's brightness. Low values light up dark scenes more.

cap = 9 uint32 25 … 100 preset [bezel] reflection_cap
input.bezel.cap

Cap (%): the most the reflection can be, as a share of the picture that lights it.

falloff = 10 uint32 10 … 40 preset [bezel] reflection_falloff
input.bezel.falloff

Falloff (tenths: 22 = 2.2): how fast the reflection fades across the lip, away from the glass. For the other falloff_shapes it sets how tight the shape is: higher is tighter to the glass, 22 the shape as designed.

soft_start = 11 uint32 0 … 4 preset [bezel] reflection_soft_start
input.bezel.soft_start

Soft Start: fades the reflection in from the glass edge instead of starting at full strength. 0 is Off; 1-4 fade it in over that many 32nds of the lip's depth.

tracking = 12 sint32 -1 … 6 preset [bezel] reflection_tracking; negative as folder
input.bezel.tracking

Tracking: how smoothly the reflection follows the picture along each edge. Higher values spread it further along the edge; 0 does not smooth.

-1 takes the bezel's own value; the OSD shows that value, in cyan once Tracking differs from it.

edge_gloss = 13 sint32 -1 … 15 preset [bezel] edge_gloss; negative as auto
input.bezel.edge_gloss

Edge Gloss: the sheen on the glass edge's soft pixels. -1 is Auto: the bezel variant's own measured value.

It has an effect only with a bezel shown whose variant carries gloss (the OSD shows the line only then); it does not need reflection.

cabinet = 15 uint32 0 … 4 preset [bezel] cabinet_brightness
input.bezel.cabinet

Cabinet Brightness: how bright the bezel art is, in linear light; lower for a dim room. PhosphorGlow.room_light lifts it a little too.

ValueMeaning
015%
125%
240%
360%
4100%

With BFI or Beam Scan on, the art shows at half that, as the picture does.

falloff_shape = 16 uint32 0 … 7 preset [bezel] reflection_falloff_shape
input.bezel.falloff_shape

Falloff Shape: the reflection's shape across the lip, away from the glass. falloff sets how tight it is.

ValueMeaning
0Power
1Linear
2Near: a near light
3Exp
4Lip Band: a rounded lip highlight
5Rim: a rim at the glass, then even
6Fade: even, with a soft fade at the outer edge
7Cosine: a bevel turning away from the screen
soft_end = 17 uint32 0 … 9 preset [bezel] reflection_soft_end
input.bezel.soft_end

Soft End (tens of %: 3 = 30%): fades the reflection out smoothly toward the lip's outer edge, over this share of its depth. 0 is Off.

mirror = 18 uint32 0 … 16 preset [bezel] reflection_mirror
input.bezel.mirror

Mirror (16ths: 8 = 50%): how much of the reflection is the picture itself, mirrored in the plastic, instead of the glow of the picture's edge. 0 is the glow alone, 16 the mirror alone. Only with an engine that has it (FEATURE_BEZEL_MIRROR); the looks leave it as it is.

mirror_depth = 19 uint32 0 … 7 preset [bezel] reflection_mirror_depth
input.bezel.mirror_depth

Mirror Depth: how fast the reflection moves into the picture, away from the glass: 1 is a true mirror, more suits a shallow glossy bevel.

ValueDepth
00.5
11
21.25
31.5
42
52.5
63
74
mirror_offset = 20 uint32 0 … 1000 preset [bezel] reflection_mirror_offset
input.bezel.mirror_offset

Mirror Offset (4K px): how far into the picture the reflection starts.

message Settings

All video settings: the root of the tree, what GetSettings returns and UpdateSettingsRequest.set carries.

The scaler's processing: Deinterlacer (with the Motion Adaptive and Film settings), Smoothing, black frame insertion, anti-ringing and related settings.

The input's picture: crop, the manual prescale (Decimator), Amplifier Blur and other per-input settings, and the Retro FX features (Analog Path Simulation, Phosphor Glow, CRT Curvature, Bezel & Glass, Corner Convergence, Tube Sag).

The input color table: Bit Crush, Crossover, gamma, lift, gain and the transfer function the input is decoded with.

The output color table: gamma, the HDR10 peak brightness and output dithering.

The scanlines' look (strength, thickness, glow, saturation per axis), mask flip, anode sag, the scaler coefficient file, and the Dynamic Scanlines.

The picture's size and place: Zoom, Aspect Ratio, position, rotation.

csc = 11 Csc

The color space conversion: its matrices, Saturation and how out-of-range colors are handled.

Gamut & White Point: the phosphors and white point of the simulated tube.

Signal settings of the input: field order.

The output: Resolution, Buffer Mode, Triple Buffer, True VRR (stored for the whole unit).

hdmi = 16 Hdmi

The HDMI transmitter: quantization range, HDR and VRR signalling (stored for the whole unit).

The scaling kernels per axis, integer scaling (nearest neighbour) and center alignment.

The scanline mode per axis and how the scaler rounds its phase steps.

mask = 19 Mask

The Mask: the pattern, its intensity and conversion, and the tube mask.

message Input

path input

Input settings: what happens to the source picture before it is scaled (crop, the Decimator's manual factor), the Amplifier Blur and Convergence of CRT Simulation, and the Retro FX features (fields from 100 on).

crop_left = 1 uint32 0 … 4096
input.crop_left

Left (Crop): source pixels trimmed at the picture's left edge.

  • In effect while crop_enabled is true.
  • The OSD allows up to half the source's width.
  • The source's own left edge: on the Tate Mode engine with the picture turned, the OSD's lines name the screen's sides and edit the matching source side.
crop_right = 2 uint32 0 … 4096
input.crop_right

Right (Crop): source pixels trimmed at the picture's right edge. In effect while crop_enabled is true; the source's side, as crop_left.

crop_top = 3 uint32 0 … 4096
input.crop_top

Top (Crop): source lines trimmed at the top of the picture. In effect while crop_enabled is true; the OSD allows up to half the source's height; the source's side, as crop_left.

crop_bottom = 4 uint32 0 … 4096
input.crop_bottom

Bottom (Crop): source lines trimmed at the bottom of the picture. In effect while crop_enabled is true; the source's side, as crop_left.

crop_enabled = 5 bool
input.crop_enabled

Crop: trims the source's edges by crop_left, crop_right, crop_top and crop_bottom. Off (the default) keeps the amounts.

OSD: Video › Shift / Crop.

prescale_h = 6 string num / den in 0 … 64 text "num/den", kept as written
input.prescale_h

Mode (Decimator, Horizontal): how many of the samples captured per line reach the scaler, as a fraction "num/den": the decimation factor num / den.

ValueMeaning
"0/1"Auto (default): the factor comes from the source
"1/1"Off: every captured sample reaches the scaler
"N/1"Fixed: keep one sample in every N
"M/K"Custom: keep K of every M captured samples (rational decimation)
  • Text: an integer, or two integers joined by /; no spaces, decimals or : ("2" is "2/1"). Another text is rejected (FieldIssue.Kind.INVALID); the range applies to the value num / den.
  • Kept as written, also in what GetSettings returns: "4/4" is Custom (all 4 of 4 kept), not Off; "4/2" is Custom, "2/1" Fixed.
  • The OSD's Custom uses M = the samples captured per line and K = its Out Width.
  • prescale_phase_h picks which samples are kept. Ignored while the source is FX Direct (the source sets the factor).

OSD: Video › Decimator.

prescale_v = 7 string num / den in 0 … 16 text "num/den", kept as written
input.prescale_v

Mode (Decimator, Vertical): how many of the captured lines reach the scaler. Format and values as prescale_h; the OSD's Custom uses M = the captured lines and K = its Out Height. prescale_phase_v picks which lines are kept.

prescale_phase_h = 8 sint32 0 … 63
input.prescale_phase_h

Keep Pixel (Fixed) / Offset (Custom) of the horizontal Decimator: which of the captured samples are kept.

  • Fixed "N/1": which sample of each group of N, 0 = the first (the OSD shows "1 of N").
  • Custom: the OSD offers 0 to 15, below the numerator of the reduced prescale_h.
  • The OSD shows it only in Fixed and Custom and sets it to 0 when the mode changes.
  • The scaler takes the low 4 bits (0 to 15).
prescale_phase_v = 9 sint32 0 … 63
input.prescale_phase_v

Keep Pixel / Offset of the vertical Decimator: which of the captured lines are kept, as prescale_phase_h (Custom: below the numerator of the reduced prescale_v).

crt_blur_enable = 10 bool
input.crt_blur_enable

Amplifier Blur: softens the picture the way the video amplifiers of a TV did. Off (the default) leaves it sharp.

  • OSD: Video › Retro FX › CRT Simulation › Amplifier Blur (also the Amplifier Blur On / Off on the CRT Simulation page).
  • The look: crt_blur_preset (crt_blur_set_preset while Analog Path Simulation runs); the strength: crt_blur_amount (the OSD sets 1.0 when it turns the blur on at 0).
  • Takes effect only while Retro FX and CRT Simulation are on (RetroFx.off and RetroFx.crt_off false). A look the source's sampling cannot carry is bypassed (OSD: "Needs a wider sampling mode").
crt_blur_preset = 11 sint32 0 … 4
input.crt_blur_preset

Look (Amplifier Blur): what the set was plugged into, from softest to sharpest.

ValueMeaning
0Composite (default)
1S-Video
2RGB Monitor
3Arcade
4PVM

While Analog Path Simulation runs (on bitstreams whose blur follows it), the look is crt_blur_set_preset instead; each list keeps its own choice.

crt_blur_amount = 12 double 0 … 1
input.crt_blur_amount

Amount (Amplifier Blur): scales between no blur and the look, as a fraction: 1.0 is the look as designed (the OSD's 100%), 0 (the default) no blur.

The OSD sets 0 to 1.0 in steps of 0.05 (shown as 0 to 100%).

crt_blur_set_preset = 13 sint32 0 … 3 only where VP_HAS_V4
input.crt_blur_set_preset

Look (Amplifier Blur) while Analog Path Simulation runs: the set's own sharpness; Analog Path Simulation sets the connection.

ValueMeaning
0Sharp: a well-kept set
1Soft: a typical consumer set (default)
2Worn: a tired set
3Exaggerated: soft, with an overshoot halo on edges

Used on bitstreams whose blur follows Analog Path Simulation, while it runs; else crt_blur_preset. Exists on the Morph 4K only.

input.convergence_enable

Convergence: red and blue land a little apart from green, as on a real tube. Off (the default) keeps them together.

convergence_red = 15 sint32 -50 … 50
input.convergence_red

Red (Convergence, %): how far red sits beside green; plus moves it right. 100% is one pixel of a 256-wide game.

In effect while convergence_enable is true. The OSD's Horizontal Look sets red and blue together (ConvergenceCorner.side_look names it).

convergence_blue = 16 sint32 -50 … 50
input.convergence_blue

Blue (Convergence, %): how far blue sits beside green; plus moves it right. 100% is one pixel of a 256-wide game. In effect while convergence_enable is true.

input.analog_path

Analog Path Simulation (Video › Retro FX): see AnalogPath.

input.phosphor_glow

Phosphor Glow (Video › Retro FX › CRT Simulation): see PhosphorGlow.

input.crt_curve

Curvature (Video › Retro FX › CRT Simulation) and the bezel art's window: see CrtCurve.

bezel = 103 Bezel
input.bezel

Bezel & Glass (Video › Retro FX): see Bezel.

input.retro_fx

The Retro FX master switches (Retro FX, CRT Simulation, Bezel & Glass): see RetroFx.

input.convergence_corner

Corner Convergence (Convergence's Vertical Look, Stretch, Tilt) and the Horizontal Look's name: see ConvergenceCorner. Switched by convergence_enable.

input.tube_sag

Tube Sag (Video › Retro FX › CRT Simulation): see TubeSag.

message CrtCurve

path input.crt_curve · preset section [crt-curvature]

CRT Curvature bends the picture like the curved glass of a tube, rounds its corners and frames it with a bezel. The message also holds Bezel Art's Window Shape and Window Inset.

OSD: Video › Retro FX › CRT Simulation › Curvature; window_shape and window_inset: Video › Retro FX › Bezel & Glass › Bezel Art.

on = 1 bool preset [crt-curvature] curvature
input.crt_curve.on

Curvature: bends the picture like the curved glass of a tube. Off (the default) leaves the picture flat.

The other fields, except window_shape and window_inset, take effect only while it is on. TubeSag works without it.

profile = 2 string preset [crt-curvature] curvature_profile
input.crt_curve.profile

Preset: the curvature preset the curve was started from. The OSD shows its name, with a * once curve_h, side_bow, curve_v or radius differs from the preset's value.

It is a label: setting it changes no other field. To apply a preset, send its values with it:

ValueMeaning: curve_h, side_bow, curve_v, radius
"flat"Flat: 0, 0, 0, 0
"studio"Studio: 4, 6, 8, 12
"consumer"Consumer (the default): 12, 12, 16, 24
"arcade"Arcade: 16, 16, 21, 32
"deep"Deep: 32, 16, 22, 48
""Custom: no preset (any other text too)
curve_h = 3 sint32 -16 … 64 preset [crt-curvature] curve_h
input.crt_curve.curve_h

Horizontal Curve (px): how far the left and right edges pull in at mid height. Below 0 bends the other way.

side_bow = 4 sint32 -16 … 32 preset [crt-curvature] side_bow
input.crt_curve.side_bow

Side Bow (px): extra pull-in at the corners, so the left and right edges bow out like a round tube.

curve_v = 5 sint32 -8 … 32 preset [crt-curvature] curve_v
input.crt_curve.curve_v

Vertical Curve (lines): how far the top and bottom edges bow at the corners. The scanlines follow the curve.

radius = 6 sint32 0 … 96 preset [crt-curvature] corner_radius
input.crt_curve.radius

Corner Radius (px): rounds the corners of the picture, or of the bezel opening when there is one. 0 = Off; the OSD steps by 2.

bezel_h = 7 sint32 0 … 160 preset [crt-curvature] bezel_sides
input.crt_curve.bezel_h

Bezel Sides (px): covers the left and right of the picture like a TV's frame. Deep enough, it hides the curved edge. 0 = Off (the default); the OSD steps by 2.

bezel_v = 8 sint32 0 … 96 preset [crt-curvature] bezel_top_bottom
input.crt_curve.bezel_v

Bezel Top/Bottom (lines): the frame's depth at the top and bottom of the picture. 0 = Off (the default).

window_shape = 12 uint32 0 … 1 preset [crt-curvature] window_shape: fitted, rounded; other values as fitted
input.crt_curve.window_shape

Window Shape (Bezel Art page): the shape of the black window around the picture while a bezel is shown.

ValueMeaning
0Fitted to Art (the default): follows the bezel's opening with a smooth curve, so its edge shows no stairs
1Rounded Box: radius, bezel_h and bezel_v make the window

Fitted to Art needs bezel art shown (Bezel.folder) and an engine with the outline window (the OSD hides the line otherwise); without them, or when the art's opening cannot be traced, the window is the Rounded Box. It does not need on.

window_inset = 13 uint32 0 … 32 preset [crt-curvature] window_inset
input.crt_curve.window_inset

Window Inset (4K output px; Bezel Art page): how far the black window sits inside the bezel's opening.

Used with window_shape 0 (Fitted to Art). Each bezel brings its own value (14 when it has none): choosing a bezel from the bezel list (the OSD's Bezel Art line, or RunAction with Choose and BEZELS) sets it. A change recomputes the window in the background (about a second); the fitted window shows once it is ready.

bow_h = 16 sint32 0 … 32 preset [crt-curvature] bezel_bow_h
input.crt_curve.bow_h

Bow (px; the line under Bezel Sides, Bezel Bow): curves the frame's left and right edges, further in at the corners than at the middle, like a tube's screen opening. 0 = straight edges (the rounded box; the default).

Needs an engine with the outline window (the OSD hides the line otherwise). Fitted bezel art (window_shape 0 with a bezel shown) takes precedence.

bow_v = 17 sint32 0 … 32 preset [crt-curvature] bezel_bow_v
input.crt_curve.bow_v

Bow (lines; the line under Bezel Top/Bottom, Bezel Bow): curves the frame's top and bottom edges, further in at the corners than at the middle. 0 = straight edges (the default).

Needs an engine with the outline window, as bow_h.

message TubeSag

path input.tube_sag · preset section [tube-sag]

Tube Sag makes the picture swell a little on bright scenes, as a tube's power supply sags.

OSD: Video › Retro FX › CRT Simulation › Tube Sag.

  • On while sag_on is true and breathing is above 0, and CRT Simulation and Retro FX are on (RetroFx.crt_off and RetroFx.off false). It works with CrtCurve.on false too.
  • Behind a bezel (Curvature's bezel or fitted bezel art) the growth is hidden, as on a TV; without one the edge grows into the black border (the OSD's Picture Edge line).
  • Its fields are part of the CRT curve's settings (CrtCurve); a change applies at once.
breathing = 1 uint32 0 … 10 preset [tube-sag] tube_breathing
input.tube_sag.breathing

Picture Size: how much wider a white screen gets as the supply sags. Each step widens a 4:3 picture by 0.3% of its width (and about half that of its height); 0 = Off (the default).

Unlike the OSD's line, setting it above 0 does not switch sag_on on: send both.

line_bulge = 2 uint32 0 … 10 preset [tube-sag] bright_line_bulge
input.tube_sag.line_bulge

Line Width: bright lines push the sides out further than the lines around them. Each step is about 0.14% of a 4:3 picture's width; 0 = Off, 5 the default.

Takes effect while Tube Sag is on.

speed = 3 uint32 0 … 2 preset [tube-sag] breathing_speed: fast, normal, slow; other values as normal
input.tube_sag.speed

Speed: how quickly the picture grows and settles back. The vertical change is always slower.

ValueMeaning
0Fast
1Normal (the default)
2Slow

Takes effect while Tube Sag is on.

sag_look = 4 string preset [tube-sag] tube_sag_look
input.tube_sag.sag_look

Tube Sag look: the look breathing, line_bulge and speed were set from. The OSD's Tube Sag line shows it, with a * once a value differs (Off while Tube Sag is off).

It is a label: setting it changes no other field. The looks' values:

ValueMeaning: breathing, line_bulge, speed
"subtle"Subtle: 2, 3, Normal
"normal"Normal (the default): 4, 5, Normal
"strong"Strong: 7, 8, Slow
""none: the OSD shows the look whose values match, else Custom (any other text too)
sag_on = 5 bool preset [tube-sag] tube_sag
input.tube_sag.sag_on

Tube Sag On / Off (the CRT Simulation page's Tube Sag line). Off keeps breathing, so On brings the same sag back.

Tube Sag runs only while this is true and breathing is above 0. Without a stored value it is true when breathing is above 0 (also after a clear).

message ConvergenceCorner

path input.convergence_corner

Corner Convergence splits red and blue above and below green toward the edges and corners, as on real tubes; the center stays clean. The message also holds the Horizontal Look.

OSD: Video › Retro FX › CRT Simulation › Convergence (the Horizontal Look, Vertical Look, Stretch and Tilt lines).

  • Takes effect only while Input.convergence_enable is true, CRT Simulation and Retro FX are on (RetroFx.crt_off and RetroFx.off false) and corner_profile is not "off".
  • The horizontal offsets themselves are Input.convergence_red and Input.convergence_blue.
  • Units: 100% is one line of a 240-line game (1/240 of the picture height), as red's offset from green; blue moves the other way, so the red-to-blue split is twice the value.
  • The split reaches about one source line at most: beyond it every term is scaled down together (a 480-line source shows TV at about 0.56 strength). The values stay as set.
  • A change applies at once.
corner_profile = 1 string
input.convergence_corner.corner_profile

Vertical Look: the corner convergence profile. Besides corner_size and corner_tilt it brings a static offset and a corner term of its own, which have no field.

ValueMeaning
"off"Off: no corner convergence
"pvm"PVM (Stretch 4, Tilt 4)
"tv"TV (Stretch 12, Tilt 8), the default
"worn"Worn (Stretch 16, Tilt 8)
"exaggerated"Exaggerated (Stretch 8, Tilt 4)
"none"Custom: only corner_size and corner_tilt, no profile terms

Any other text acts as "tv" (a load stores "tv"). The OSD shows a * once corner_size or corner_tilt differs from the profile's. Choosing a profile on the OSD writes them; over the API send them with it.

side_look = 2 string
input.convergence_corner.side_look

Horizontal Look: the side look Input.convergence_red and Input.convergence_blue were set from, from a well-kept set to a tired one. The OSD shows it, with a * once they differ.

It is a label: setting it changes no other field. The looks' values (red, blue; %):

ValueMeaning
"off"Off: 0, 0
"subtle"Subtle: -10, +10
"typical"Typical: -20, 0
"tired"Tired: -35, +20
""none (the default): the OSD shows the look whose values match, else Custom
corner_size = 3 sint32 -40 … 40
input.convergence_corner.corner_size

Stretch (%): red and blue drawn taller or shorter than green; 100% is one line of a 240-line game at the top and bottom. Plus makes red taller and blue shorter.

corner_tilt = 4 sint32 -40 … 40
input.convergence_corner.corner_tilt

Tilt (%): red and blue turned against green; 100% is one line of a 240-line game at the sides. Plus turns red clockwise and blue counterclockwise.

message GammaInputTable

path gamma_input_table · preset section [color_input_table]

Input Gamma / Transfer Function decodes the source's 8-bit levels into linear light for the color space conversion: bit_crush_amount, input_gain and input_lift on each level, then the transfer curve (gamma_transfer_func, trans_func_threshold, gamma).

OSD: Video › Color Correction, heading Input Gamma / Transfer Function.

  • Takes effect while Hdmi.hdr_mode is not 3 (Disabled). Disabled bypasses the color pipeline: fixed values apply, and the OSD dims these lines.
  • A Color Profile (a preset file from the SD card, on the same page) sets these fields together with Csc and GammaOutputTable.
  • Stored per video mode and engine. In FX Direct and passthrough the unit uses the defaults.
bit_crush_amount = 3 sint32 0 … 7 preset [color_input_table] bit_crush; inherit
gamma_input_table.bit_crush_amount

Bit Crush (bits): drops the lowest bits of each color for fewer, coarser shades, as on older hardware. 0 is Off (the default); 1 to 7 round each 8-bit level to a multiple of 2, 4 ... 128.

trans_func_threshold = 4 sint32 -1 … 256 preset [color_input_table] trans_func_threshold; inherit
gamma_input_table.trans_func_threshold

Crossover (input level): where a standard transfer curve hands over to the power curve gamma. Levels below it are decoded with the standard curve, levels from it up with gamma.

ValueMeaning
-1Auto (no step): where the power curve first reaches the standard curve
0-255that input level (the default is 50)
256Off: the standard curve throughout; gamma has no effect

Only with gamma_transfer_func 1 to 3. At a fixed level the two curves rarely meet, so the curve can step there (a faint line in dark gradients). With Auto, gamma has no effect when the curves do not meet (for example gamma 2.4 or more with sRGB) and with any bit_crush_amount.

gamma = 5 double 1 … 3 preset [color_input_table] gamma
gamma_input_table.gamma

Factor: the gamma the source was made for: 2.2 for most consoles (the default). Higher darkens the midtones, lower brightens them.

The whole curve with gamma_transfer_func 0 (Gamma); with a standard curve it applies from trans_func_threshold up. 1/0.45 (2.2222...) is the video camera standard that presets and Color Profiles use; the OSD steps by 0.1.

input_lift = 6 double 0 … 1 preset [color_input_table] lift
gamma_input_table.input_lift

Lift: raises the black level: 0.00 keeps true black (the default), higher values lift the shadows toward grey. Added to each level (0 to 1) before the transfer curve.

input_gain = 7 double 0 … 1 preset [color_input_table] gain
gamma_input_table.input_gain

Gain: overall brightness of the decoded picture: 1.00 leaves it unchanged (the default), lower values dim everything evenly. Multiplies each level (0 to 1) before input_lift is added.

gamma_transfer_func = 8 sint32 0 … 3 preset [color_input_table] trans_func: Gamma, sRGB, SMPTE-240M, Rec.709; other values as unknown
gamma_input_table.gamma_transfer_func

Transfer Function: the curve the source's brightness is decoded with.

ValueMeaning
0Gamma: the power curve gamma alone
1sRGB (the default)
2SMPTE-240M
3Rec.709

1 to 3 are standard curves with a straight part for the darkest levels; trans_func_threshold sets where they hand over to gamma.

message GammaOutputTable

path gamma_output_table · preset section [color_output_table]

Output Gamma / PQ encodes the processed picture for the TV: a gamma curve for SDR and HLG, PQ (SMPTE 2084) for HDR10, with optional dithering.

OSD: Video › Color Correction, heading Output Gamma / PQ.

  • Hdmi.hdr_mode picks the curve (the OSD's Transfer Function line, not a setting of its own): PQ with 2 (HDR10), where nits applies; a gamma curve otherwise, where gamma applies.
  • Takes effect while Hdmi.hdr_mode is not 3 (Disabled), which bypasses the color pipeline.
  • A Color Profile sets these fields together with GammaInputTable and Csc.
  • Stored per video mode and engine. In FX Direct and passthrough the unit uses the defaults.
gamma = 3 double 1 … 3 preset [color_output_table] gamma
gamma_output_table.gamma

Factor: the TV's gamma the picture is prepared for: 2.2 for most TVs (the default), 2.4 for a dark room. Not used with Hdmi.hdr_mode 2 (HDR10). 1/0.45 (2.2222...) is a value presets use; the OSD steps by 0.1.

nits = 5 double 50 … 10000 preset [color_output_table] nits; inherit
gamma_output_table.nits

Nits (cd/m²): the brightness HDR10 gives full white; match it to the TV's own brightness. The default is 1000.

Only with Hdmi.hdr_mode 2 (HDR10). The OSD steps by 50 and stops at the TV's average and peak luminance from its EDID. With Gamut & White Point on, the unit sends a higher value so that a bluer white stays as bright, at most the TV's peak; the stored value stays.

dithering = 6 sint32 0 … 1 preset [color_output_table] dithering: off, on; other values as inherit; inherit
gamma_output_table.dithering

Dithering: adds a fine noise that hides banding in smooth gradients.

ValueMeaning
0Off (the default)
1On

It dithers down to the HDMI transmitter's bits per color (nothing at 12 bits). The v4 engines have no output dither, so there it changes nothing.

message Csc

path csc · preset section [color_csc_matrix]

Color Space Conversion converts the decoded colors to the output's color space and sets their saturation.

OSD: Video › Color Correction, heading Color Space Conversion (Overflow, Saturation). The matrices have no line of their own: a Color Profile (a preset file from the SD card) sets them, with GammaInputTable and GammaOutputTable.

  • Hdmi.hdr_mode decides what applies: 0 Off (with CSC): sat only, no matrix; 1 HLG and 2 HDR10: sat, then the matrices; 3 Disabled: nothing.
  • While Gamut & White Point is on (Gamut.enable), its matrix replaces the matrices and prevent_clip; sat still applies.
  • A product of the two matrices with a coefficient outside the hardware's range (about ±4) is scaled down as a whole: hue kept, picture darker.
  • Stored per video mode and engine, with Gamut.
prevent_clip = 1 sint32 0 … 1 preset [color_csc_matrix] prevent_clip: clip, attenuate; other values as inherit; inherit
csc.prevent_clip

Overflow: colors pushed past full strength by the color matrix.

ValueMeaning
0Clip: the matrix as given; colors clip at the display's limit
1Attenuate (the default): the matrix scaled down until no row sums above 1.0, keeping detail

Only with Hdmi.hdr_mode 1 (HLG) or 2 (HDR10), and not while Gamut & White Point is on.

sat = 5 double 0 … 2 preset [color_csc_matrix] saturation; inherit
csc.sat

Saturation: color intensity: 1.00 leaves colors unchanged (the default), 0.00 is black and white, up to 2.00 for vivid colors. Applies with every Hdmi.hdr_mode but 3 (Disabled).

message InputSignal

path input_signal

Input signal settings written with the input stage: Deblur, Field Order, and the analog video output's format and filter.

  • On the Morph 4K's OSD only field_order: Video › Deinterlacer › Advanced › Field Order.
  • Stored: field_order per video mode and engine.
  • Loaded and applied also in FX Direct.
field_order = 2 uint32 0 … 1
input_signal.field_order

Field Order of an interlaced source.

ValueMeaning
0Normal (the default)
1Inverted

Swap it if every interlaced source looks jittery: some consoles send their fields in the other order.

message Output

path output

Output settings: the output resolution and how the output is timed against the source (Frame/Sync Lock, Triple Buffer, VRR). The configured values, stored globally (etc/main.json).

OSD: Video › Output Resolution and Video › Advanced Video.

  • An update applies the fields it names at once, as the web UI does: the output is set up again and the picture can drop out while the TV resyncs. There is no keep-or-revert timer as on the OSD: send the old values to go back.
  • A resolution change switches to that video mode's settings (a new settings epoch); the other fields of the same update are applied before it.
  • Only the update itself stores these fields (the keys of the fields it names), not SaveSettings: a change sent with SAVE_NONE stays unsaved.
  • GetSettings reads the stored values each time: an unsaved change shows only in Info (active_resolution, active_buffer_mode, active_true_vrr, active_triple_buffer_mode). The active values also differ where a mode is in force: Tate Mode's Triple Buffer, the output limits' fallback to Triple Buffer, FX Direct.
resolution = 1 string
output.resolution

Output Resolution: the name of an output modeline of the source's video standard (NTSC or PAL).

On the Morph 4K: native (the TV's preferred timing from its EDID; the default, 480p on the Basic Edition), 1080p, WQHD, 4K, 1080p_x2, WQHD_x2 (_x2: twice the source frame rate), and user modelines. An empty name or one the video standard has no modeline for is rejected (INVALID). A change loads that video mode's settings and can take several seconds (it may reload the FPGA).

buffer_mode = 2 uint32 0 … 4
output.buffer_mode

Frame/Sync Lock: how the output is timed against the source.

ValueMeaning
0Frame Lock (minimal): the lowest possible lag, worked out for each scale factor; a settings change may need a resync
1Triple Buffer (the Morph 4K's default): the output runs from its own clock at a standard rate; works with every TV, frames may repeat
2Frame Lock (normal): low lag with more margin, so settings changes need a resync less often
4Magiclock 2 / Genlock: the output clock follows the source: smooth motion at a standard output rate

3 does not exist (rejected, INVALID). The OSD's VRR entry is 2 with true_vrr. Sent without the running engine's True VRR field (true_vrr, or true_vrr_tate on Tate Mode), it turns VRR off; with VRR on, 2 is stored whatever was sent. The Tate Mode engine always runs Triple Buffer and does not change or store this field.

triple_buffer_mode = 3 uint32 0 … 2
output.triple_buffer_mode

Triple Buffer: the output rate in Triple Buffer and Magiclock 2: from the source, or forced.

ValueMeaning
0Auto (50/60Hz) (the default)
1Force 60Hz
2Force 50Hz

A change sets the output up again.

true_vrr = 4 bool
output.true_vrr

VRR (True VRR) for the Universal Adaptive, Physical Display Model and Spatial Super Resolution engines: the TV refreshes with each source frame, at Frame Lock's low lag. Needs a TV with VRR and an engine with VRR output.

While one of these engines runs: on sets buffer_mode 2 (Frame Lock (normal)); turned off without buffer_mode, the active buffer mode stays; on an engine without VRR output it is stored as off. While Tate Mode runs, a change is only stored (it applies when one of these engines loads). The signalling to the TV: Hdmi.vrr_mode.

true_vrr_tate = 5 bool
output.true_vrr_tate

VRR for the Tate Mode engine, its own choice (its Frame/Sync Lock list: Triple Buffer or VRR): the TV refreshes with each source frame, about one frame of lag. Applies while Tate Mode runs, as true_vrr does for the other engines; otherwise a change is only stored.

message Hdmi

path hdmi

HDMI signalling to the TV: the RGB range, the HDR mode (which also switches the Color Correction pipeline) and VRR signalling. The configured values, stored globally (etc/main.json).

OSD: Video › Advanced Video, heading HDMI, and Video › Color Correction › HDR.

  • An update applies the fields it names at once, as the OSD does: the HDMI transmitter is set up again and the TV may resync.
  • Stored as Output: only by the update itself, not by SaveSettings. GetSettings reads the stored values each time, so an unsaved change does not show there.
quantization_range = 1 uint32 0 … 2
hdmi.quantization_range

Color Space: the HDMI RGB range.

ValueMeaning
0Auto (the default): from the TV
1Limited (16-235)
2Full (0-255)
hdr_mode = 2 uint32 0 … 3
hdmi.hdr_mode

HDR: how the picture is sent to the TV, and whether the color pipeline (Color Correction) runs.

ValueMeaning
0Off (with CSC): standard (SDR) output with every Color Correction setting applied
1HLG: Hybrid Log-Gamma HDR signalling, for TVs that handle HLG better than HDR10
2HDR10: HDR with PQ, the TV's full brightness range; GammaOutputTable.nits sets the white
3Disabled: bypasses the color pipeline: the source's colors unchanged, Color Correction (GammaInputTable, Csc, GammaOutputTable) and Gamut off

With nothing stored, and after a clear, the mode is 3 (Disabled), the Morph 4K's default.

vrr_mode = 3 uint32 0 … 4
hdmi.vrr_mode

Inject VFR-EMP: variable refresh signalling to the TV (HDMI VRR packets).

ValueMeaning
0disabled (the default): no VRR packets
1off: packets that tell the TV VRR is off
2auto: VESA if the TV supports it, else FreeSync, else off
3vesa
4freesync

While True VRR is active (Output.true_vrr, Output.true_vrr_tate), 0 and 1 act as auto. A change to 0 sends off first, so every TV turns VRR off. The OSD shows the line on tiers with the feature.

message Gamut

path gamut

Gamut & White Point recreates a CRT tube's phosphor colors and white point in the output's color matrix.

OSD: Video › Retro FX › CRT Simulation › Gamut & White Point.

  • Only on bitstreams with the single HDR matrix (every v4 Morph 4K engine); elsewhere the OSD hides it.
  • Takes effect while Retro FX and CRT Simulation are on (RetroFx.off and RetroFx.crt_off false) and Hdmi.hdr_mode is not 3 (Disabled; the OSD then shows Needs Setup).
  • While on, its matrix replaces the Color Profile's matrices and Csc.prevent_clip; Csc.sat still applies. With HDR10 it also raises the PQ white level the unit sends (see GammaOutputTable.nits).
  • It assumes the TV in its standard mode: BT.709 at 6500K in SDR, BT.2020 in HDR10.
  • The OSD's Look sets look, phosphors, white and decoder (5, Auto) together. An update stores each field as sent: to pick a look, send all four (see look).
  • Stored per video mode and engine, with Csc.
enable = 1 bool
gamut.enable

Gamut & White Point: On, or Off (6500K) (the default), which shows colors as sent.

look = 2 uint32 0 … 4
gamut.look

Look: the starting point the values were taken from, stored so that the OSD can show it (with a *, such as Japan TV*, once phosphors or white differ from it).

ValueMeaning
0none: Custom (the default)
1US TV: phosphors 1 (SMPTE-C), white 0 (6500K)
2PAL TV: phosphors 2 (EBU), white 0 (6500K)
3Japan TV: phosphors 3 (Japan), white 2 (9300K TV)
4Japan PVM: phosphors 4 (Trinitron), white 1 (9300K Monitor)

It changes no other field: send phosphors, white and decoder 5 (Auto) with it. With decoder Auto it picks the TV Decoder's region.

white = 3 uint32 0 … 2
gamut.white

White Point: the tube's white.

ValueMeaning
06500K (the default): the broadcast white
19300K Monitor: bluer, as studio monitors
29300K TV: bluer, as Japanese home TVs

9300K dims SDR (about 25% with Monitor, 19% with TV); with HDR10 the unit keeps the brightness, up to the TV's peak. No effect with phosphors 6 (Color Profile), which brings its own white (the OSD dims the line).

phosphors = 4 uint32 0 … 6
gamut.phosphors

Phosphors: the tube's red, green and blue primaries.

ValueMeaning
0Modern (the default): BT.709, as the display
1SMPTE-C
2EBU
3Japan: the ARIB spec
4Trinitron: Sony's
5NTSC 1953: the 1953 broadcast target, a very saturated green
6Color Profile: primaries and white from the loaded Color Profile

6 works as Modern when the Color Profile gives no usable primaries (the OSD then does not offer it).

fit = 5 bool
gamut.fit

Fit to Display: pulls colors the display can't show just inside its range, so nothing clips. Off is exact but clips. The default is On.

decoder = 6 uint32 0 … 5
gamut.decoder

TV Decoder: the color decoder of a US or Japanese TV, which decoded color its own way: stronger reds, orange yellows. Meant for Composite, S-Video and RF sources.

ValueMeaning
0Standard (the default): no change
1US TV
2Japanese TV
3US Monitor
4Japanese Monitor
5Auto: by look on an NTSC Composite, S-Video or RF source; Standard on PAL, RGB and other sources

Auto's choice by look: US TV for 1 or none, Standard for 2, Japanese TV for 3, Japanese Monitor for 4. Such a source is Analog Path Simulation running on a Composite, S-Video or RF connection, or the analog input's composite / S-Video decoder.

message Scaler

path scaler

Scaler processing: the Deinterlacer, Smoothing, Anti-Ringing, and black frame insertion or Beam Scan.

  • OSD: Video › Deinterlacer (and its Advanced page), Video › Smoothing, Video › Scaler (Anti-Ringing), Video › Retro FX › CRT Simulation › Beam Scan or Video › Advanced Video (BFI).
  • The Deinterlacer acts on interlaced sources (480i, 576i) only; a progressive source bypasses it.
  • Motion Adaptive's settings are the ma_*, deint_ela*, motion_detail and source_noise fields; Film (Auto) has its own copy in film_set.
deinterlacer = 13 uint32 0 … 5
scaler.deinterlacer

Method (Deinterlacer): how 480i and 576i become progressive frames.

ValueMeaning
0Bob: each field alone, line-doubled. No combing and no extra delay; fine detail flickers
1Blend: mixes each pair of fields. Steady and comb-free; motion leaves a soft double image
2Weave: joins each pair of fields into one frame. Full detail on stills; moving objects comb
3Motion Adaptive (default): full detail where the picture is still, motion rebuilt pixel by pixel
4Simulate CRT: each field in its own scanline position, as a CRT: interlaced motion and flicker
5Film (Auto): rebuilds the frames of films and 30 fps games; other video runs Motion Adaptive
  • The OSD lists them as Film (Auto), Motion Adaptive, Weave, Blend, Bob, Simulate CRT, only those the product's tier allows; a load lowers a value above the tier's limit to it, and the API rejects it (NOT_IN_THIS_TIER).
  • Film (Auto) needs a bitstream with the film deinterlacer; elsewhere 5 runs as Motion Adaptive (with Motion Adaptive's settings).
smoothing = 14 uint32 0 … 255
scaler.smoothing

Smoothing: rounds off the stair-steps of pixel art: each game pixel becomes four, with smooth edges. One byte: bit 0 on, bit 2 the algorithm.

ValueMeaning
0Off (default)
1On; XBR on engines with the older smoothing stage
5HQX (engines with the older smoothing stage)
  • OSD: Video › Smoothing. On the Spatial Super Resolution engine it is Off / On (bit 0 alone counts), and smoothing_filter picks the filter.
  • Where the product's tier has no smoothing, a load sets 0, and the API rejects any other value (NOT_IN_THIS_TIER).
bfi_enable = 17 bool
scaler.bfi_enable

Beam Scan on, or BFI: black frames between picture frames. Default off.

  • On bitstreams with Beam Scan, true turns Beam Scan on with the method in beam_scan_mode (OSD: Video › Retro FX › CRT Simulation › Beam Scan; false is its Off). It runs only with a 1080p output at twice the game's rate (1080p120 for 60 Hz, 1080p100 for 50 Hz), MagicLock2 buffering and a progressive source (else the OSD shows "Needs Setup"), and while Retro FX and CRT Simulation are on.
  • Elsewhere it is BFI (OSD: Video › Advanced Video): every other output frame black, for motion clarity.
antiring_enable = 18 bool
scaler.antiring_enable

Anti-Ringing: stops the sharper interpolations from overshooting into bright or dark halos around hard edges.

OSD: Video › Scaler. On engines with the 4-tap scaler (Universal Adaptive) it is three choices with antiring_strong; elsewhere on / off. The default is on with the 4-tap scaler, else off.

antiring_enableantiring_strongMeaning (4-tap scaler)
falseanyOff: Lanczos and Catmull-Rom may draw thin light or dark halos around hard edges
truefalseLight: trims the strongest halos and keeps the most sharpness
truetrueStrong (default): no halos around hard edges
antiring_strong = 19 bool
scaler.antiring_strong

Anti-Ringing Strong (true) or Light (false), on engines with the 4-tap scaler while antiring_enable is true. The default is true with the 4-tap scaler, else false; unused elsewhere.

blank_timer = 22 uint32 0 … 15
scaler.blank_timer

I/P Change Blank (frames): blanks this many frames when the source switches between interlaced and progressive, to hide the glitch. 0 (the default): none.

OSD: Video › Deinterlacer › Advanced, on bitstreams that have it.

ma_sensitivity = 23 uint32 256 … 260
scaler.ma_sensitivity

Sensitivity (Motion Adaptive): how small a change counts as motion. Lower keeps more detail but can comb, most on noisy sources.

ValueMeaning
256Min
257Low
258Normal (default)
259High
260Max

OSD: Video › Deinterlacer › Advanced. Used only while source_noise is 3 (Custom); Clean runs Low, Noisy runs Normal.

ma_noise_threshold = 24 uint32 0 … 63
scaler.ma_noise_threshold

Noise Threshold (Motion Adaptive): changes below this are ignored. Keep it low: higher values add combing, even on noisy sources. Default 4.

OSD: Video › Deinterlacer › Advanced. Used only while source_noise is 3 (Custom); Clean runs 4, Noisy 0.

ma_interpolation = 25 uint32 0 … 2
scaler.ma_interpolation

Interpolator (Motion Adaptive): how moving areas are filled in. Average is smoothest; a field copy keeps one field's lines exactly.

ValueMeaning
0Lower Field
1Upper Field
2Average (default)

OSD: Video › Deinterlacer › Advanced. Edge Smoothing (deint_ela) works with Average only.

ma_detector = 26 uint32 0 … 1
scaler.ma_detector

Latency (Motion Adaptive): Zero-Lag adds no field of delay; +1 Field gives cleaner motion and seamless film switching.

ValueMeaning
0Zero-Lag (default)
1+1 Field (the symmetric detector)

OSD: Video › Deinterlacer. Film (Auto) always waits one field.

deint_ela = 27 bool
scaler.deint_ela

Edge Smoothing on (Motion Adaptive): smooths jagged diagonals in moving areas, at deint_ela_level. Default on.

OSD: Video › Deinterlacer (Off / Low / Medium / High), on bitstreams that have it. Works with the Average interpolator only (ma_interpolation 2); the OSD changes it only then.

deint_ela_level = 28 uint32 0 … 2
scaler.deint_ela_level

Edge Smoothing level (Motion Adaptive): higher catches shallower edges, with small errors in fine texture.

ValueMeaning
0Low (default)
1Medium
2High

In effect while deint_ela is true. Bitstreams that offer only Low run every level as Low.

motion_detail = 29 uint32 0 … 1
scaler.motion_detail

Motion Detail (Motion Adaptive): Clean has the least combing on moving areas; Sharp gives crisper moving edges, with a small risk of combing on fast motion.

ValueMeaning
0Clean (default)
1Sharp

OSD: Video › Deinterlacer, on bitstreams with the motion upgrades.

source_noise = 30 uint32 0 … 3
scaler.source_noise

Source Noise (Motion Adaptive): picks ma_sensitivity and ma_noise_threshold for the source.

ValueMeaning
0Auto (default): Clean for HDMI and RGB, Noisy for composite and S-Video
1Clean: for clean sources such as HDMI and RGB; sharper, steadier detail in moving areas
2Noisy: for composite, S-Video, VHS and RF; keeps their noise from causing combing
3Custom: ma_sensitivity and ma_noise_threshold as set

OSD: Video › Deinterlacer.

scaler.film_set

Film (Auto)'s own copy of the Motion Adaptive settings: see FilmSet.

film_cadence = 32 uint32 0 … 2
scaler.film_cadence

Film Cadence (Film (Auto)): the cadence Film holds.

ValueMeaning
0Auto (default): finds the cadence; falls back to Motion Adaptive whenever the source looks like video
12:2: for 30 fps sources, such as many PS2 games; holds film through slow and vertical motion
23:2: for 24 fps films, as on DVD; holds film through slow scenes where Auto falls back
  • 2:2 and 3:2: video parts may comb. The OSD's Method then reads Film (2:2) or Film (3:2).
  • OSD: Video › Deinterlacer › Advanced, with Method Film (Auto) on bitstreams that support it.
smoothing_filter = 33 uint32 0 … 2
scaler.smoothing_filter

Filter (Smoothing), on the Spatial Super Resolution engine.

ValueMeaning
0super-xBR (default): smooth curves and diagonals with soft, natural edges
1xBRZ: crisp outlines and clean corners; pixel art keeps its shapes with smooth diagonals
2Super Eagle: a softer, classic look; neighboring colors blend along the edges

OSD: Video › Smoothing. In effect while smoothing is on.

beam_scan_mode = 35 uint32 0 … 2
scaler.beam_scan_mode

Beam Scan method, used while bfi_enable is true on bitstreams with Beam Scan.

ValueMeaning
0BFI (default): black frames between picture frames: sharper motion, half the brightness
1Rolling Scan: a lit band sweeps down the screen like a CRT's beam; bright parts stay lit longer
2Bright Strobe: variable MPRT strobe, brighter pixels stay lit longer; full brightness, more flicker

OSD: Video › Retro FX › CRT Simulation › Beam Scan (its Off is bfi_enable false).

beam_persistence = 36 uint32 0 … 7
scaler.beam_persistence

Persistence (Beam Scan with BFI or Rolling Scan): how long each pixel stays lit, like a phosphor's decay. Lower gives sharper motion and a darker picture.

The lit time is (8 - value) / 8 of the pulse: 0 = 100% (the default), 1 = 88% ... 7 = 13%; the OSD shows the percentage. On bitstreams with the Beam Scan scale.

beam_strobe_length = 37 uint32 0 … 7
scaler.beam_strobe_length

Strobe Length (Beam Scan with Bright Strobe): how long each strobe flash lasts. Lower gives sharper motion and a darker picture. Units as beam_persistence: 0 = 100% (the default) to 7 = 13%.

message ScalerMeta

path scaler_meta

Picture size and place: the Zoom, Aspect Ratio and Rotation of the Scaler page and the Shift lines of Shift / Crop.

zoom_factor = 1 double -3 … 64
scaler_meta.zoom_factor

Zoom Mode / Zoom: the picture's size.

ValueMeaning
-1Fill (Morph 4K default): the zoom that fills the screen exactly, worked out again on a new source
-2Under: the largest whole-number zoom that fits the screen: even pixels, with a border
-3Over: the smallest whole-number zoom that fills the screen: even pixels, edges cropped
> 0Manual: the scale factor; the picture's height is the source's lines times it
aspect_ratio = 2 string num / den in -3 … 64 text "num/den", reduced
scaler_meta.aspect_ratio

Aspect Ratio: the picture's shape on screen, as a fraction "num/den".

ValueMeaning
"-3/1"Auto (Stable) (default): 4:3, 16:9 or 3:2, chosen by the source's shape
"-2/1"Auto (PAR): the source's exact shape, per video mode
"-1/1"1:1 PAR mode: square pixels
> 0the display aspect ratio, width : height (OSD: "4/3", "32/27", "160/119", "16/9", Custom)
  • Text: an integer, or two integers joined by /; no spaces, decimals or : ("-3" is "-3/1"). Another text is rejected (FieldIssue.Kind.INVALID); the range applies to the value num / den.
  • GetSettings returns it reduced: "8/6" reads back as "4/3".
  • On the Tate Mode engine with the picture turned, the ratio is the game's own (4:3); the screen shows its transpose (3:4).
horizontal_adjust = 3 sint32 -999 … 999
scaler_meta.horizontal_adjust

Input Horizontal (Shift): moves the source picture left or right before scaling, in source pixels: centers an off-center picture.

  • Stored negated: the OSD shows minus this value, so a negative value here moves the picture right.
  • The source's own axis: on the Tate Mode engine with the picture turned, the OSD's Input Horizontal edits vertical_adjust.
vertical_adjust = 4 sint32 -999 … 999
scaler_meta.vertical_adjust

Input Vertical (Shift): moves the source picture up or down before scaling, in source lines: brings lines at the edge into view.

Stored negated: a negative value here moves the picture down. The source's own axis, as horizontal_adjust.

xshift = 6 sint32 -999 … 999
scaler_meta.xshift

Output Horizontal (Shift): moves the finished, scaled picture left or right on the screen, in output pixels; plus moves it right.

yshift = 7 sint32 -999 … 999
scaler_meta.yshift

Output Vertical (Shift): moves the finished, scaled picture up or down on the screen, in output lines; plus moves it down.

rotation = 9 uint32 0 … 3
scaler_meta.rotation

Rotation: which way the picture is turned for a vertical screen.

ValueMeaning
0Auto (default): the way the source asks for (FX Direct, DV1), else clockwise
1CW
2CCW
3Off: upright (0 degrees)

OSD: Video › Scaler, on the Tate Mode engine only. Off is offered only where that engine can show the picture upright.

message FilmSet

path scaler.film_set

Film (Auto)'s own Deinterlacer settings: the same settings as Motion Adaptive's in Scaler, used while the Method (Scaler.deinterlacer) is Film (Auto) on a bitstream that has it.

  • OSD: Video › Deinterlacer and its Advanced page show and edit the selected Method's set.
  • A field never set for Film starts from Motion Adaptive's value.
sensitivity = 1 uint32 256 … 260
scaler.film_set.sensitivity

Sensitivity for Film (Auto): 256 Min, 257 Low, 258 Normal, 259 High, 260 Max, as Scaler.ma_sensitivity. Used only while source_noise is 3 (Custom).

interpolation = 2 uint32 0 … 2
scaler.film_set.interpolation

Interpolator for Film (Auto): 0 Lower Field, 1 Upper Field, 2 Average, as Scaler.ma_interpolation.

detector = 3 uint32 0 … 1
scaler.film_set.detector

Latency for Film (Auto): 0 Zero-Lag, 1 +1 Field, as Scaler.ma_detector.

noise_threshold = 4 uint32 0 … 63
scaler.film_set.noise_threshold

Noise Threshold for Film (Auto), as Scaler.ma_noise_threshold. Used only while source_noise is 3 (Custom).

ela = 5 bool
scaler.film_set.ela

Edge Smoothing on for Film (Auto), at ela_level, as Scaler.deint_ela.

ela_level = 6 uint32 0 … 2
scaler.film_set.ela_level

Edge Smoothing level for Film (Auto): 0 Low, 1 Medium, 2 High, as Scaler.deint_ela_level.

motion_detail = 7 uint32 0 … 1
scaler.film_set.motion_detail

Motion Detail for Film (Auto): 0 Clean, 1 Sharp, as Scaler.motion_detail.

source_noise = 8 uint32 0 … 3
scaler.film_set.source_noise

Source Noise for Film (Auto): 0 Auto, 1 Clean, 2 Noisy, 3 Custom, as Scaler.source_noise.

message Polyphase

path polyphase

Scanline shape of the Normal (and older Adaptive) scanlines per axis, the scaler's mask flip, anode sag and coefficient file, and the Dynamic and Adaptive scanlines' own values (fields from 100 on).

  • OSD: Video › Retro FX › CRT Simulation › Scanlines: with Scanlines Normal, its Beam Brightness, Depth and Thickness are the vert_* fields (the horiz_* ones on the Tate Mode engine with the picture turned).
  • Each axis is one scaler table: vert_* shapes the usual scanlines, the gaps between the source's lines; horiz_* gaps between its columns. On the Tate Mode engine with the picture turned, the source's lines run up the screen, so its scanlines are the horizontal axis'.
  • The scanline mode of each axis is in ScalerPolyphase; scanlines show only while Retro FX and CRT Simulation are on.
  • A change rebuilds the scaler tables (about 100 ms).
vert_scanline_saturation = 5 double 0 … 199
polyphase.vert_scanline_saturation

Beam Brightness (%): how bright the scanlines are drawn. 100 (the default) is as designed; more brightens the picture, less darkens it.

The vertical axis, Normal scanlines (and the older Adaptive). The older OSD calls it Saturation.

vert_scanline_strength = 6 double 0 … 100
polyphase.vert_scanline_strength

Depth, stored as 100 - Depth: how dark the gaps between the lines get. Here 100 fills them in (the OSD's Depth 0) and 0 makes them black (Depth 100); the default 50 is Depth 50.

The vertical axis, Normal scanlines (and the older Adaptive). The older OSD shows the same number (100 - this) as Strength.

vert_scanline_thickness = 7 double -10 … 0
polyphase.vert_scanline_thickness

Thickness: how thick each line is drawn, vertical axis, Normal scanlines.

  • In the scaler's own units: negative, more negative is thicker. The OSD's Thickness 0 to 100 is -1.98 to -8.86 here; the default -3.6 shows as 45.
  • A value of 0 or more is replaced by -3.6 when the settings load.
polyphase.dynamic_scanlines

The Dynamic scanlines' beam (ScalerPolyphase mode 5): see DynamicScanlines.

polyphase.adaptive2

The Adaptive scanlines' values (Classic v2, ScalerPolyphase mode 6): see Adaptive2.

message DynamicScanlines

path polyphase.dynamic_scanlines · preset section [dynamic-scanlines]

Dynamic Scanlines: the beam of the Scanlines page's Dynamic mode. The lines widen with brightness and keep the picture's light, as on a tube.

OSD: Video › Retro FX › CRT Simulation › Scanlines (Scanlines Dynamic).

  • Used while ScalerPolyphase.vert_scanline_mode is 5 (Dynamic), CRT Simulation and Retro FX are on (RetroFx.crt_off and RetroFx.off false); not while the Tate engine turns the picture. width_each_color also serves Adaptive (Adaptive2).
  • Needs an engine with dynamic scanlines (every Morph 4K engine has them).
  • Widths are in source lines: the beam's full width at half its height.
  • A change recomputes the scanline table in the background; the picture changes once it is written (the OSD's title shows "calculating" meanwhile).
  • The defaults are the "gaussian" profile's, with knee Off and width_each_color false.
pw = 1 double 1 … 8 preset [dynamic-scanlines] beam_edge
polyphase.dynamic_scanlines.pw

Beam Edge: the shape of the beam's edge. 2.0 is a soft Gaussian; higher values give crisp edges.

fd = 2 double 0 … 1 preset [dynamic-scanlines] width_dark
polyphase.dynamic_scanlines.fd

Width on Dark (source lines): how wide the beam is on dark lines. Small values give thin lines with deep gaps.

fb = 3 double 0 … 4 preset [dynamic-scanlines] width_bright
polyphase.dynamic_scanlines.fb

Width on Bright (source lines): how wide the beam is on white. Above about 1.2 neighboring bright lines merge.

cons = 5 double 0 … 100 preset [dynamic-scanlines] energy_conserving
polyphase.dynamic_scanlines.cons

Energy Conserving (%): 100% keeps the picture as bright as without scanlines; 0% is the old, darker construction.

law = 6 sint32 0 … 1 preset [dynamic-scanlines] width_growth: even, natural; other values as even
polyphase.dynamic_scanlines.law

Width Growth: how the width follows brightness.

ValueMeaning
0Even: widens steadily with brightness
1Natural: keeps dark and mid lines thin, widening near white as a tube does (space charge)
halo = 7 double 0 … 1 preset [dynamic-scanlines] halo
polyphase.dynamic_scanlines.halo

Halo: a faint wide skirt around bright lines, as the beam spreads at high current: its share of the light at white (0.10 = 10%, as the OSD shows it). 0 = Off.

hw = 8 double 0 … 3 preset [dynamic-scanlines] halo_width
polyphase.dynamic_scanlines.hw

Halo Width (source lines): how far the halo reaches. It cannot reach past the neighboring line. It matters only while halo is above 0.

sat = 9 double 0 … 1 preset [dynamic-scanlines] phosphor_saturation
polyphase.dynamic_scanlines.sat

Phosphor Saturation: bright lines flatten at the top as the phosphor runs out of light, so they look wider. 0 = none.

knee = 11 double 0 … 85 preset [dynamic-scanlines] highlight_knee
polyphase.dynamic_scanlines.knee

Highlight Knee (% of input): light is conserved up to this level; above it highlights roll off, so bright lines keep their gaps. 0 = Off (the default); the OSD offers Off and 50% to 85% in steps of 5.

A knee the profile cannot reach with 10% to spare moves down to where it can. The OSD's Beam Profile choice keeps it.

width_each_color = 12 bool preset [dynamic-scanlines] width_follows: brightest, each_color
polyphase.dynamic_scanlines.width_each_color

Width Follows: whose brightness widens a line, in the Dynamic and Adaptive modes.

ValueMeaning
falseBrightest (the default): the brightest color widens the line for all three
trueEach Color: each color's line widens by its own brightness

With Energy Conserving, Each Color can shift the hue of saturated colors between lines and gaps. Needs an engine with it (the OSD hides the line otherwise). The OSD's Beam Profile choice keeps it.

profile = 13 string preset [dynamic-scanlines] profile
polyphase.dynamic_scanlines.profile

Beam Profile: the profile the values were started from. The OSD shows its name, with a * once a value differs.

It is a label: setting it changes no other field. To apply a profile, send its values with it (each has cons 100):

ValueMeaning: pw, fd, fb, law, halo, hw, sat
"gaussian"Gaussian (the default): 2.0, 0.32, 1.00, 0, 0, 2.0, 0
"soft"Soft: 1.5, 0.42, 1.10, 0, 0, 2.0, 0
"sharp"Sharp: 3.5, 0.30, 0.95, 0, 0, 2.0, 0
"flat"Flat: 7.0, 0.36, 1.00, 0, 0, 2.0, 0
"thin"Thin: 2.2, 0.16, 0.80, 0, 0, 2.0, 0
"space"Natural: 2.0, 0.20, 1.20, 1, 0, 2.0, 0
"dynamic"Full Range: 2.2, 0.16, 1.45, 1, 0, 2.0, 0
"pvm"PVM: 2.4, 0.24, 0.70, 1, 0.04, 1.6, 0.3
"consumer"Consumer TV: 1.8, 0.40, 1.15, 1, 0.18, 2.4, 0.8
"arcade"Arcade: 2.2, 0.30, 1.00, 1, 0.10, 2.0, 0.5
""Custom: none (any other text too)

message Adaptive2

path polyphase.adaptive2

Adaptive scanlines (Adaptive-v2): the Scanlines page's Adaptive mode. Bright lines widen, and the gaps between dark lines can be deeper than between bright ones.

OSD: Video › Retro FX › CRT Simulation › Scanlines (Scanlines Adaptive).

look = 1 string
polyphase.adaptive2.look

Look: the look the values were started from. The OSD shows its name, with a * once a value differs (ramp aside).

It is a label: setting it changes no other field. The looks' values (brightness 100 in each):

ValueMeaning: depth_dark, depth_bright, width_dark, width_bright, ramp
"match"Classic (the default): 65, 65, 28, 72, 0. Even gaps at every brightness; lines widen as they brighten
"floor"Dark Detail: 85, 50, 28, 72, 0. Deep gaps in dark scenes, shallow ones in highlights
"deep"Deep: 90, 70, 28, 72, 0. Deeper gaps everywhere
"current"Classic with ramp 1, from older settings (the OSD shows Classic)
"floor-current"Dark Detail with ramp 1, from older settings (the OSD shows Dark Detail)
""Custom: none (any other text too)
depth_dark = 2 double 0 … 100
polyphase.adaptive2.depth_dark

Depth on Dark: how dark the gaps are between dark lines. 100 is black; 0 fills them in.

The OSD's Depth line moves depth_dark and depth_bright together.

depth_bright = 3 double 0 … 100
polyphase.adaptive2.depth_bright

Depth on Bright: how dark the gaps are between bright lines. 100 is black; 0 fills them in.

width_dark = 4 double 0 … 200
polyphase.adaptive2.width_dark

Width on Dark (hundredths of a source line: 28 is the OSD's 0.28 lines): how wide the beam is on dark lines, its full width at half height. Small values give thin lines with deep gaps.

width_bright = 5 double 0 … 300
polyphase.adaptive2.width_bright

Width on Bright (hundredths of a source line, as width_dark): how wide the beam is on white. Above about 100 (1.0 lines) neighboring bright lines merge.

ramp = 6 sint32 0 … 1
polyphase.adaptive2.ramp

Width Growth: how the width follows brightness.

ValueMeaning
0Even (the default): widens steadily with brightness
1Natural: keeps dark and mid lines thin, widening near white as a tube does (the beam current)
brightness = 7 double 0 … 100
polyphase.adaptive2.brightness

Beam Brightness (%): dims the lines. 100% is as designed (the default); it never brightens, so colors hold.

message Interpolation

path interpolation

Interpolation: the scaler's kernel per axis and Disable Interpolation at integer scale factors.

  • OSD: Video › Scaler.
  • A change rewrites the scaler tables.
horiz_kernel = 1 uint32 0 … 39
interpolation.horiz_kernel

Horizontal Interp.: how the picture is smoothed across when it is scaled.

ValueMeaning
4Off: every pixel repeated exactly, no smoothing. The crispest, but uneven at some sizes
35Sharper Bilinear: very crisp pixel edges with just enough smoothing to keep pixels even
0Sharp Bilinear (default): crisp pixels with smooth, even edges. Best for 2D games
1Bilinear: soft and even; smooths pixel edges completely
37Mitchell: smooth and natural, with fewer jagged edges. Good for 3D games
38Catmull-Rom: sharp and detailed. Good for 3D games
39Lanczos: the sharpest detail. Best for 3D games and video
36Sharper Bil. Alt (developer mode): a variant of Sharper Bilinear
32, 33, 34off-centered, off-special, off-leftalign (developer mode): Off variants
5the old softer; the OSD shows it as Bilinear
2, 3cubic, sinc: not offered by the OSD
  • Mitchell, Catmull-Rom and Lanczos need the 4-tap scaler (Universal Adaptive); elsewhere Mitchell draws as Bilinear, Catmull-Rom and Lanczos as Sharp Bilinear.
  • Not in effect at an integer scale factor that nn_auto turns off.
  • On the Tate Mode engine with the picture turned, Normal scanlines are drawn on top of it.
  • Other numbers are no kernel.
vert_kernel = 2 uint32 0 … 39
interpolation.vert_kernel

Vertical Interp.: how the picture is smoothed down when it is scaled. Values as horiz_kernel.

With the vertical scanlines (ScalerPolyphase.vert_scanline_mode) on, while Retro FX and CRT Simulation are on:

  • Dynamic (5) shapes the picture down instead; this kernel applies when they are off.
  • Adaptive sets the beam; this kernel only sets how lines blend (Bilinear softer, Off hardest, others sharp).
  • Normal is drawn on top of this kernel.

On the Tate Mode engine with the picture turned, the vertical axis is this kernel alone.

nn_auto = 3 uint32 0 … 3
interpolation.nn_auto

Disable Interpolation: turns interpolation off (as kernel Off) at integer scale factors, for exactly even pixels.

ValueMeaning
0off: interpolation stays on at every scale factor
1H/V int scale (default): off when both scale factors are integers
2H int only: off across when the horizontal scale factor is an integer
3V int only: off down when the vertical scale factor is an integer

message ScalerPolyphase

path scaler_polyphase

Scanlines mode per axis, and how the scaler rounds its phase steps.

vert_scanline_mode = 2 uint32 0 … 6
scaler_polyphase.vert_scanline_mode

Scanlines of the vertical axis: the usual scanlines, gaps between the source's lines.

ValueMeaning
0Off (default)
1Normal: even lines
2on (alt) (older OSD): Normal with the older line shape; the Morph 4K's OSD shows Normal
3, 4the older Adaptive modes; on bitstreams with Dynamic Scanlines drawn as 6
5Dynamic: lines widen and keep the light, as a tube does (bitstreams with Dynamic Scanlines)
6Adaptive: bright lines widen (Classic v2; bitstreams with Dynamic Scanlines)
  • The OSD offers Off, Normal, Adaptive (where the product's tier has it) and Dynamic.
  • Where the tier has no Adaptive scanlines, a load turns 3, 4 and 6 into Normal, and the API rejects them (NOT_IN_THIS_TIER).

message Mask

path mask

Mask draws the tube's phosphor mask or aperture grille over the picture: a pattern of up to 16 x 16 cells, one output pixel each, repeated across the screen, that sets each color's gain.

OSD: Video › Retro FX › CRT Simulation › Mask.

  • Drawn while mode is not 0 and CRT Simulation and Retro FX are on (RetroFx.crt_off and RetroFx.off false). Best at 4K.
  • Needs an engine with the mask (the OSD hides the page otherwise). On a unit whose tier has no slot masks, mode loads as 0, and the API rejects another mode (NOT_IN_THIS_TIER), also in the pattern's mode bytes.
  • The cells come from the pattern (the OSD's Type line loads one of the SD card's mask files) or, with TubeMask.mode 1 (Physical), from a tube the unit models (tube).
  • A change applies at once.
mode = 2 uint32 0 … 2
mask.mode

Mask On / Off.

ValueMeaning
0Off (the default)
1On
2Boost: drawn as On (the OSD sets only Off and On)

It is the pattern's own mode, so a client can switch the mask without sending the pattern.

intensity = 3 double 0 … 1
mask.intensity

Intensity: how strong the mask is; lower values let more of the picture through. 1.0 is the full mask (the default); the OSD shows it in percent.

It lifts the darkening cells toward 128 (no change): a cell byte below 128 becomes min(byte + 128 x (1 - intensity), 128); cells that brighten stay. Also with TubeMask.mode 1.

conversion = 4 uint32 0 … 8
mask.conversion

Transform: turns or mirrors the pattern, for a rotated screen or a tate game.

ValueMeaning
0None (the default)
1Rotate 90: a quarter turn clockwise
2Rotate 180: a half turn
3Rotate 270: a quarter turn counterclockwise
4Mirror Horiz.: upside down (the rows in reverse order)
5Mirror Vert.: left and right swapped
6Flip NW/SE: on the diagonal from top left to bottom right
7Flip NE/SW: on the diagonal from top right to bottom left
8Multiply by 2: each cell doubled to 2 x 2 (at most 16 x 16 cells)

Pattern only: with TubeMask.mode 1 it is not used (TubeMask.rotated turns a tube).

mask.tube

The tube mask: the page's Mode and the tube it models.

message TubeMask

path mask.tube

Tube mask (the Mask page's Mode Physical): the unit builds the mask from a real tube's phosphor layout, screen size and pitch, scaled to the picture, instead of using the pattern.

OSD: Video › Retro FX › CRT Simulation › Mask (the Mode, Tube, Layout, Screen Size, Pitch, Pitch Fit, Size Mode and Orientation lines).

  • Used while mode is 1 and the mask is on (Mask.mode); Mask.intensity applies as with a pattern.
  • The OSD's Tube line sets tube, layout, size and pitch together; the API stores each field as sent.
  • A tube finer than the output can draw (less than 3 output pixels for one red, green and blue) is drawn coarser; the OSD's help text says so.
  • A stored value outside its list loads as the default. A change applies at once.
mode = 1 uint32 0 … 1 preset [?] mask_mode: pattern, physical
mask.tube.mode

Mode: where the mask's cells come from.

ValueMeaning
0Pattern (the default): a pixel pattern from the mask files on the SD card
1Physical: built from a real tube's phosphor layout, screen size and pitch (the fields below)
tube = 2 uint32 0 … 7 preset [?] tube_preset
mask.tube.tube

Tube: the tube layout, size and pitch were started from. The OSD shows its name, with a

  • once one of them differs.

It is a label: setting it changes no other field. The tubes:

ValueMeaning: layout, size, pitch
020" Consumer TV (the default): Slot Mask, 20, Standard
127" Consumer TV: Slot Mask, 27, Coarse
220" Grille TV: Aperture Grille, 20, Coarse
314" Studio Monitor: Aperture Grille, 14, Very Fine
420" Studio Monitor: Aperture Grille, 20, Fine
519" Arcade Monitor: Delta Dots, 19, Fine
625" Arcade Monitor: Delta Dots, 25, Coarse
736" Consumer TV: Slot Mask, 36, Coarse
layout = 3 uint32 0 … 2 preset [?] tube_layout: slot, grille, delta
mask.tube.layout

Layout: how the tube's phosphors are arranged.

ValueMeaning
0Slot Mask: stripes cut into slots
1Aperture Grille: unbroken stripes
2Delta Dots: round dots in triangles
size = 4 uint32 9 … 36 preset [?] tube_size
mask.tube.size

Screen Size (inches): the screen's diagonal, corner to corner, as tubes were sold. Bigger screens show a finer mask.

The OSD's sizes: 9, 13, 14, 17, 19, 20, 21, 25, 27, 29, 32, 34, 36. Another size is drawn as sent, but the next load of the stored settings turns it into 20, the default.

pitch = 5 uint32 0 … 3 preset [?] tube_pitch: very_fine, fine, standard, coarse
mask.tube.pitch

Pitch: how far one triad is from the next.

ValueMeaning: mm for Slot Mask, Aperture Grille, Delta Dots
0Very Fine: 0.45, 0.25, 0.40
1Fine: 0.60, 0.30, 0.60
2Standard: 0.75, 0.50, 0.75
3Coarse: 0.85, 0.75, 0.85
fixed = 6 uint32 0 … 1 preset [?] tube_size_mode: follow, fixed
mask.tube.fixed

Size Mode: whether the mask follows the zoom.

ValueMeaning
0Follow Zoom (the default): the mask grows with the picture, as on a bigger tube; with a bezel shown it fits the bezel's glass
1Fixed: the mask keeps its size in pixels (fixed_px) when the zoom changes
rotated = 7 uint32 0 … 1 preset [?] tube_orientation: normal, rotated
mask.tube.rotated

Orientation: the tube upright or on its side.

ValueMeaning
0Normal (the default)
1Rotated: the tube on its side, for a vertical game shown upright

The Tate engine's rotation turns the mask by itself.

exact = 8 uint32 0 … 1 preset [?] tube_pitch_fit: even, exact
mask.tube.exact

Pitch Fit: how the tube's pitch meets the output's pixels.

ValueMeaning
0Even (the default): every stripe lands on whole pixels, so the mask is even; the pitch is rounded to fit
1Exact: the tube's own pitch; where it falls between pixels, some stripes look brighter than others
fixed_px = 9 double 0 … 16384 preset [?] tube_fixed_px
mask.tube.fixed_px

The tube's width in output pixels for fixed 1 (no OSD line). 0 takes the width the mask has at the next mask write and stores it here; the OSD's Size Mode line sets 0, so Fixed keeps the size the mask had when it was chosen. Not used with Follow Zoom.

message RetroFx

path input.retro_fx · preset section [retro-fx]

Retro FX master switches: Retro FX, CRT Simulation and Bezel & Glass, each On or Off. An effect runs only while its own switch, its group's switch and Retro FX are all On.

OSD: the Retro FX row of the Video menu (left / right: Off / On), and the CRT Simulation and Bezel & Glass rows of Video › Retro FX.

  • Each field is an Off flag: true switches off, false (the default) is On.
  • A switch never changes the effects' own switches or settings, so On brings back exactly what was there.
  • Analog Path Simulation sits under Retro FX alone; its own switch is AnalogPath.enable.
  • Morph 4K.
off = 1 bool preset [retro-fx] retro_fx; inverted: on is false
input.retro_fx.off

Retro FX: true switches every Retro FX effect off at once: Analog Path Simulation and everything under CRT Simulation and Bezel & Glass. Off keeps their settings; On (false) brings them back as they were.

crt_off = 2 bool preset [retro-fx] crt_simulation; inverted: on is false
input.retro_fx.crt_off

CRT Simulation: true switches the tube's effects off: Amplifier Blur, Scanlines, Convergence, Mask with Damper Wires, Phosphor Glow with Edge Dimming, Gamut & White Point, Curvature, Tube Sag and Beam Scan. Their own switches and settings stay.

bezel_off = 3 bool preset [retro-fx] bezel_and_glass; inverted: on is false
input.retro_fx.bezel_off

Bezel & Glass: true switches off the bezel art with its Bezel Reflection, and Room Light (PhosphorGlow.room_light). The bezel stays loaded, so On (false) shows it again without a reload.

fx-framework schema options (fx.v1)

fx/v1/options.proto

Custom options on the messages and fields of the fx-framework schemas (vp_control.v1): a field's range (min, max), the text formats of string fields (fraction, matrix, as_written), product limits (only_if) and its line in a preset INI file (ini_section, ini_key and the other ini_* options, inverted: the names a preset file uses for the same setting).

enum IniFormat

How a value is written to and read from a preset INI file (key = value lines in a [section]).

INI_INT = 0

A decimal integer (%d). Read with strtol (base 0: 0x10 is hex, 010 octal, unless ini_decimal); stored without clamping.

INI_ON_OFF = 1

on / off. Read: on or 1 is true, anything else false. With inverted, on stands for the field's value false.

INI_ID = 2

A short identifier, written as is. An empty value is written as ini_empty (default none); ini_empty or none read back as empty.

INI_NAMES = 3

The name at the value's index in ini_names. Read: the index of the name; a word not in the list reads 0 (or keeps the value, with ini_keep_unknown).

INI_NAMES_OR_NUMBER = 4

The name at the value's index in ini_names, or the number when the value is out of the list (ini_other: a text instead). Read: the index of the name, else the number (strtol).

INI_DOUBLE = 5

A real number: %1.15g, or %1.17g when that does not read back as the same double. Read with strtod.

INI_MATRIX = 6

A matrix field's text: its numbers row by row, joined by |. Read loosely: the identity matrix's numbers where numbers are missing, empty parts skipped, a word reads 0.

Options

(fx.v1.min) = 50002 sint32 on FieldOptions

Range: the lowest value the field takes. The API rejects values below it. For a matrix field: each number. Values from -32768 to 32767.

(fx.v1.max) = 50003 sint32 on FieldOptions

Range: the highest value the field takes (see min).

(fx.v1.ini_key) = 50005 string on FieldOptions

The field's key in the preset INI section of its message (ini_section); none: presets do not carry the field in that section.

(fx.v1.ini_format) = 50006 IniFormat on FieldOptions

How the value is written in the preset INI (default INI_INT).

(fx.v1.ini_names) = 50007 string on FieldOptions

INI_NAMES / INI_NAMES_OR_NUMBER: the names of the values 0, 1, 2, ..., comma-separated.

(fx.v1.ini_empty) = 50008 string on FieldOptions

INI_ID: how an empty value is written (default none).

(fx.v1.ini_negative) = 50009 string on FieldOptions

INI_INT: the word written for a negative value; it reads back as -1.

(fx.v1.ini_other) = 50018 string on FieldOptions

INI_NAMES / INI_NAMES_OR_NUMBER: the word written for a value outside the list (instead of the last name / the number).

(fx.v1.ini_inherit) = 50019 bool on FieldOptions

inherit is written for the field's unset value (-1 for a number, a matrix of zeros; a name list writes ini_other) and reads as the live value of the field (the color tables).

(fx.v1.ini_nocase) = 50020 bool on FieldOptions

INI_NAMES / INI_NAMES_OR_NUMBER: names are read ignoring case.

(fx.v1.ini_keep_unknown) = 50021 bool on FieldOptions

INI_NAMES: a word not in ini_names leaves the value as it is (otherwise it reads 0).

(fx.v1.ini_decimal) = 50022 bool on FieldOptions

INI_INT: read as a decimal number (otherwise strtol base 0: 0x.. hex, 0.. octal).

(fx.v1.fraction) = 50013 bool on FieldOptions

A string field holding a fraction: the text "num/den", reduced, the denominator positive (unless as_written).

(fx.v1.only_if) = 50014 string on FieldOptions

The field exists only on some products: the name of a firmware feature. Where the firmware lacks it, the API reports the field as NOT_ON_THIS_PRODUCT.

(fx.v1.as_written) = 50015 bool on FieldOptions

A fraction kept as written: "4/4" stays "4/4" and is not "1/1" (the manual prescale: n of n samples); never reduced on the way.

(fx.v1.matrix) = 50016 bool on FieldOptions

A string field holding a square matrix of doubles: its numbers row by row, joined by | ("1|0|0|0|1|0|0|0|1" for a 3 x 3 identity). min / max limit each number.

(fx.v1.inverted) = 50017 bool on FieldOptions

A bool written to the preset INI as its opposite: the field is named for "off", the preset line for "on" (Retro FX's switches: retro_fx = on is RetroFx.off false). The API carries the field's value, as it is named.

(fx.v1.ini_section) = 50102 string on MessageOptions

The message's section in a preset INI file, without brackets (analog-path for [analog-path]).