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:
| Code | HTTP | When |
|---|
invalid_argument | 400 | The 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_precondition | 400 | if_settings_epoch is no longer the unit's settings epoch: read the settings again. |
not_found | 404 | RunAction names an entry its list does not have. |
aborted | 409 | The settings were replaced (mode change, console or game context, preset) before a save or action ran. |
resource_exhausted | 429 | The request body is larger than the method accepts. |
internal | 500 | The firmware's tables and messages disagree (a firmware bug). |
unimplemented | 501 | No such method, or not on this product / not yet (a layer, a list). |
unavailable | 503 | Out 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
GetInfo: product, schema id, settings_epoch.GetSettings: the live settings; show them.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).- 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.
POST /vp_control.v1.SettingsService/GetInfo
The unit, its firmware, and the state of its settings (epoch, applied updates, save layer).
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.
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 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.
The firmware version, e.g. 4.0.87.
The firmware's product: morph4k for the Morph 4K.
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).
Where the live settings come from: engine, console, video standard, output resolution, then the console or game context. For display; the format may change.
The name of the preset loaded last, if any.
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.
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.
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.
The layer saves of these settings go into (Morph 4K: LAYER_VIDEO_MODE). Settings of the global layer are saved there whatever this says.
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).
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.
Whether bezel art is on screen now. Absent on a product without bezel art.
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.
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.
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.
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.
System › Preset Auto-Load for the running engine as stored (a change takes effect after a restart); absent where the unit has none.
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.
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.
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
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.
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.
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.
Why the last one did not save, in a few words (e.g. "no capture in this engine", "canceled"); empty when it saved.
The last screenshot was saved, but the picture kept changing while it was read: some lines may come from other frames.
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
The live settings (default), the defaults, or one stored layer (sparse).
message FieldPath
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.
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).
When to save the change (default: as the OSD does).
Where to save: absent or Info.save_layer (no other layer yet: unimplemented).
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).
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.
enum FieldIssue.Kind
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
Whether the update was taken: false if there is any issue, and then nothing changed.
One entry per field that cannot be taken.
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.
The settings epoch the update belongs to.
message SaveSettingsRequest
Saves the live settings into a layer (a "Save" button), after any update still pending.
Act only if the unit's settings epoch is still this one (else failed_precondition).
message SaveSettingsReply
The layer the settings were saved into.
message ListChoicesRequest
message Choice
An entry of a choice list.
The entry's name as the OSD shows it.
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).
BEZELS: the variant within the folder.
BEZELS: why the running engine cannot show this bezel; empty if it can. It can still be picked, as on the OSD.
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.
PRESETS: one of Pixel FX's (under System/): it can be loaded, not saved over or deleted.
ENGINES: the OSD's description of the engine.
message ListChoicesReply
The entries of a choice list.
The entries in the OSD's order, Off first.
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).
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 entry's name (case-insensitive).
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).
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.
The folder under /sdcard/presets; absent: New, where the OSD puts a new preset.
The preset's name: also its file name, without .ini.
Replace an existing preset of the user's.
message PresetRef
The folder under /sdcard/presets ("" at the top).
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.
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.
message AutoRotation
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").
The profile's id in the folder's bezel.json (e.g. flat, flat_integer); "" or absent: the current one.
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.
Capture after the OSDs: what the HDMI output carries, menus and notices included. Default: before them, the picture only.
Only the line CRCs (.crc), no PNG: to compare two pictures line by line.
Read each part once, without the check read: faster, but a picture that changes during the capture goes unnoticed.
Do not freeze the picture: the capture then needs a still picture.
With line_count: the first line to capture (0 is the top).
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).
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 output picture as a PNG (screenshot).
Stop the running screenshot.
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 action's sequence number; it is applied when the reply comes.
The settings epoch the action ran in.
save_preset, save_game_preset: the file saved, under /sdcard/presets.
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 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: the active picture the unit samples, per line (the Scaler page's per-input size).
The active lines of that picture.
The source's frame rate: 50 or 60 (Hz), 0 when there is no signal or another rate.
Whether the source is interlaced.
The running engine's name.
Scaler › Zoom: the horizontal scale factor as the OSD shows it (screen horizontal; a rotated Tate picture's factors swapped, as there).
The vertical scale factor (see scale_h).
Decimator › Detected: the factor Auto found across.
The factor Auto found down.
The samples per line the unit captures before decimation: Custom's starting point and largest Out Width.
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.
Analog Path Simulation › APS Status › Status: "Off", "Starting", "Paused", "Running x2".
APS Status › Reason: why it is paused; empty when it is not.
Beam Scan › Game: "60 Hz", "50 Hz" or "No Signal".
Beam Scan › Output: the output and what it needs, e.g. "4K60 (need 1080p120)".
Beam Scan › Buffering: "MagicLock2", "Triple Buffer" or "Frame Lock".
Beam Scan › Status: "Off", "Active", "Retro FX Off" or "Waiting for Setup".
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 & White Point: on, but Color Correction › HDR is Disabled (Needs Setup).
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 Reflection: the shown bezel's own Tracking (what Bezel.tracking -1 uses); -1 none.
The shown bezel's own Edge Gloss (what Bezel.edge_gloss -1, Auto, uses); -1 none.
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
FEATURE_APS_CHROMA_DELAY = 3
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
FEATURE_APS_IF_RESPONSE = 7
APS IF Response (RF Reception).
FEATURE_APS_HUE_JITTER = 8
APS Hue Jitter (RF Reception).
FEATURE_APS_OUTPUT_CLIPPING = 10
APS Output Clipping (Console Output).
FEATURE_BEZEL = 12
Bezel & Glass: bezel art (Bezel).
FEATURE_BEZEL_REFLECTION = 13
FEATURE_PHOSPHOR_GLOW = 14
FEATURE_EDGE_DIMMING = 16
Edge Dimming and Dimming Shape.
FEATURE_AMPLIFIER_BLUR = 18
FEATURE_AMPLIFIER_BLUR_APS = 19
FEATURE_SCANLINES = 20
Scanlines (the Retro FX page with Normal and Dynamic).
FEATURE_SCANLINES_ADAPTIVE = 21
FEATURE_WIDTH_FOLLOWS = 22
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_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_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_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
FEATURE_FREE_SCALING = 42
A Zoom set by hand (Zoom Mode Manual and the custom size).
FEATURE_COLOR_CORRECTION = 46
FEATURE_DEINTERLACER = 47
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
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.
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.
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.
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.
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.
| Value | Meaning |
|---|
| 0 | Genesis |
| 1 | SNES |
| 2 | NES |
| 3 | PlayStation |
| 4 | PC Engine |
| 5 | Nintendo 64 |
| 6 | Master System |
| 7 | Atari 8-bit |
| 8 | Commodore 64 |
| 9 | Apple II |
| 10 | Amiga |
| 11 | Generic NTSC |
| 12 | Generic PAL |
| 13 | Amiga (PAL) |
| 14 | C64 (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.
| Value | Meaning |
|---|
| 0 | Composite |
| 1 | S-Video (yc_crosstalk_pct leaks some of the composite look into it) |
| 2 | RF (Antenna): the RF Reception fields apply |
| 3 | Blend Only: keeps dither blending and color smear without rainbows |
The Cable fields apply to every connection but RF.
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.
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.
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.
| Value | Meaning |
|---|
| 0 | Simple (PAL-S): shows phase errors as Hanover bars |
| 1 | Delay Line (PAL-D): hides phase errors |
input.analog_path.dot_crawl_locked
Dot Crawl: whether the dots move.
| Value | Meaning |
|---|
| 0 | Natural: the dots move like the console's own timing |
| 1 | Locked: 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.
| Value | Meaning |
|---|
| 0 | 0 IRE (Japan) |
| 75 | 7.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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | Low |
| 2 | Medium |
| 3 | High |
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.
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.
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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | Slow |
| 2 | Fast |
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.
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.
| Value | Meaning |
|---|
| 0 | Short |
| 1 | Medium |
| 2 | Long |
| 3 | Very 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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | Light |
| 2 | Heavy |
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.
input.analog_path.console_setup_dire
Console Setup (tenths of IRE): the console's black pedestal. US consoles may add 7.5 IRE.
| Value | Meaning |
|---|
| 0 | 0 IRE |
| 75 | 7.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.
| Value | Meaning |
|---|
| 0 | Auto: the console's own (Square for NES and Atari 8-bit, else Sine) |
| 1 | Sine |
| 2 | Square |
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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | 130 IRE |
| 2 | 120 IRE |
| 3 | 110 IRE |
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.
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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | 0.25% |
| 2 | 0.5% |
| 3 | 1% |
| 4 | 2% |
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.
| Value | Meaning |
|---|
| 0 | Round: dims every edge alike |
| 1 | Wide: 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.
| Value | Meaning |
|---|
| 0 | Off |
| 1 | Night |
| 2 | Dim Room |
| 3 | Lamp-Lit |
| 4 | Daylight |
| 5 | Arcade |
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.
| Value | Meaning |
|---|
| 0 | 15% |
| 1 | 25% |
| 2 | 40% |
| 3 | 60% |
| 4 | 100% |
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.
| Value | Meaning |
|---|
| 0 | Power |
| 1 | Linear |
| 2 | Near: a near light |
| 3 | Exp |
| 4 | Lip Band: a rounded lip highlight |
| 5 | Rim: a rim at the glass, then even |
| 6 | Fade: even, with a soft fade at the outer edge |
| 7 | Cosine: 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.
| Value | Depth |
|---|
| 0 | 0.5 |
| 1 | 1 |
| 2 | 1.25 |
| 3 | 1.5 |
| 4 | 2 |
| 5 | 2.5 |
| 6 | 3 |
| 7 | 4 |
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
The scaler's processing: Deinterlacer (with the Motion Adaptive and Film settings), Smoothing, black frame insertion, anti-ringing and related settings.
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 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.
The output: Resolution, Buffer Mode, Triple Buffer, True VRR (stored for the whole unit).
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.
The Mask: the pattern, its intensity and conversion, and the tube mask.
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:
| Value | Meaning: 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.
| Value | Meaning |
|---|
| 0 | Fitted to Art (the default): follows the bezel's opening with a smooth curve, so its edge shows no stairs |
| 1 | Rounded 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.
| Value | Meaning |
|---|
| 0 | Fast |
| 1 | Normal (the default) |
| 2 | Slow |
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:
| Value | Meaning: 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.
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.
| Value | Meaning |
|---|
"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.
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; %):
| Value | Meaning |
|---|
"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 |
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.
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.
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.
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.
| Value | Meaning |
|---|
| -1 | Auto (no step): where the power curve first reaches the standard curve |
| 0-255 | that input level (the default is 50) |
| 256 | Off: 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.
| Value | Meaning |
|---|
| 0 | Gamma: the power curve gamma alone |
| 1 | sRGB (the default) |
| 2 | SMPTE-240M |
| 3 | Rec.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.
| Value | Meaning |
|---|
| 0 | Off (the default) |
| 1 | On |
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.
| Value | Meaning |
|---|
| 0 | Clip: the matrix as given; colors clip at the display's limit |
| 1 | Attenuate (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 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.
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).
output.buffer_mode
Frame/Sync Lock: how the output is timed against the source.
| Value | Meaning |
|---|
| 0 | Frame Lock (minimal): the lowest possible lag, worked out for each scale factor; a settings change may need a resync |
| 1 | Triple Buffer (the Morph 4K's default): the output runs from its own clock at a standard rate; works with every TV, frames may repeat |
| 2 | Frame Lock (normal): low lag with more margin, so settings changes need a resync less often |
| 4 | Magiclock 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.
output.triple_buffer_mode
Triple Buffer: the output rate in Triple Buffer and Magiclock 2: from the source, or forced.
| Value | Meaning |
|---|
| 0 | Auto (50/60Hz) (the default) |
| 1 | Force 60Hz |
| 2 | Force 50Hz |
A change sets the output up again.
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.
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.
hdmi.quantization_range
Color Space: the HDMI RGB range.
| Value | Meaning |
|---|
| 0 | Auto (the default): from the TV |
| 1 | Limited (16-235) |
| 2 | Full (0-255) |
hdmi.hdr_mode
HDR: how the picture is sent to the TV, and whether the color pipeline (Color Correction) runs.
| Value | Meaning |
|---|
| 0 | Off (with CSC): standard (SDR) output with every Color Correction setting applied |
| 1 | HLG: Hybrid Log-Gamma HDR signalling, for TVs that handle HLG better than HDR10 |
| 2 | HDR10: HDR with PQ, the TV's full brightness range; GammaOutputTable.nits sets the white |
| 3 | Disabled: 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.
hdmi.vrr_mode
Inject VFR-EMP: variable refresh signalling to the TV (HDMI VRR packets).
| Value | Meaning |
|---|
| 0 | disabled (the default): no VRR packets |
| 1 | off: packets that tell the TV VRR is off |
| 2 | auto: VESA if the TV supports it, else FreeSync, else off |
| 3 | vesa |
| 4 | freesync |
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.
gamut.enable
Gamut & White Point: On, or Off (6500K) (the default), which shows colors as sent.
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).
It changes no other field: send phosphors, white and decoder 5 (Auto) with it. With decoder Auto it picks the TV Decoder's region.
gamut.white
White Point: the tube's white.
| Value | Meaning |
|---|
| 0 | 6500K (the default): the broadcast white |
| 1 | 9300K Monitor: bluer, as studio monitors |
| 2 | 9300K 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).
gamut.phosphors
Phosphors: the tube's red, green and blue primaries.
| Value | Meaning |
|---|
| 0 | Modern (the default): BT.709, as the display |
| 1 | SMPTE-C |
| 2 | EBU |
| 3 | Japan: the ARIB spec |
| 4 | Trinitron: Sony's |
| 5 | NTSC 1953: the 1953 broadcast target, a very saturated green |
| 6 | Color 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).
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.
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.
| Value | Meaning |
|---|
| 0 | Standard (the default): no change |
| 1 | US TV |
| 2 | Japanese TV |
| 3 | US Monitor |
| 4 | Japanese Monitor |
| 5 | Auto: 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.
scaler.deinterlacer
Method (Deinterlacer): how 480i and 576i become progressive frames.
| Value | Meaning |
|---|
| 0 | Bob: each field alone, line-doubled. No combing and no extra delay; fine detail flickers |
| 1 | Blend: mixes each pair of fields. Steady and comb-free; motion leaves a soft double image |
| 2 | Weave: joins each pair of fields into one frame. Full detail on stills; moving objects comb |
| 3 | Motion Adaptive (default): full detail where the picture is still, motion rebuilt pixel by pixel |
| 4 | Simulate CRT: each field in its own scanline position, as a CRT: interlaced motion and flicker |
| 5 | Film (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).
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.
| Value | Meaning |
|---|
| 0 | Off (default) |
| 1 | On; XBR on engines with the older smoothing stage |
| 5 | HQX (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).
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.
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_enable | antiring_strong | Meaning (4-tap scaler) |
|---|
| false | any | Off: Lanczos and Catmull-Rom may draw thin light or dark halos around hard edges |
| true | false | Light: trims the strongest halos and keeps the most sharpness |
| true | true | Strong (default): no halos around hard edges |
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.
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.
scaler.ma_sensitivity
Sensitivity (Motion Adaptive): how small a change counts as motion. Lower keeps more detail but can comb, most on noisy sources.
| Value | Meaning |
|---|
| 256 | Min |
| 257 | Low |
| 258 | Normal (default) |
| 259 | High |
| 260 | Max |
OSD: Video › Deinterlacer › Advanced. Used only while source_noise is 3 (Custom); Clean runs Low, Noisy runs Normal.
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.
scaler.ma_interpolation
Interpolator (Motion Adaptive): how moving areas are filled in. Average is smoothest; a field copy keeps one field's lines exactly.
| Value | Meaning |
|---|
| 0 | Lower Field |
| 1 | Upper Field |
| 2 | Average (default) |
OSD: Video › Deinterlacer › Advanced. Edge Smoothing (deint_ela) works with Average only.
scaler.ma_detector
Latency (Motion Adaptive): Zero-Lag adds no field of delay; +1 Field gives cleaner motion and seamless film switching.
| Value | Meaning |
|---|
| 0 | Zero-Lag (default) |
| 1 | +1 Field (the symmetric detector) |
OSD: Video › Deinterlacer. Film (Auto) always waits one field.
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.
scaler.deint_ela_level
Edge Smoothing level (Motion Adaptive): higher catches shallower edges, with small errors in fine texture.
| Value | Meaning |
|---|
| 0 | Low (default) |
| 1 | Medium |
| 2 | High |
In effect while deint_ela is true. Bitstreams that offer only Low run every level as Low.
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.
| Value | Meaning |
|---|
| 0 | Clean (default) |
| 1 | Sharp |
OSD: Video › Deinterlacer, on bitstreams with the motion upgrades.
scaler.source_noise
Source Noise (Motion Adaptive): picks ma_sensitivity and ma_noise_threshold for the source.
| Value | Meaning |
|---|
| 0 | Auto (default): Clean for HDMI and RGB, Noisy for composite and S-Video |
| 1 | Clean: for clean sources such as HDMI and RGB; sharper, steadier detail in moving areas |
| 2 | Noisy: for composite, S-Video, VHS and RF; keeps their noise from causing combing |
| 3 | Custom: 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.
scaler.film_cadence
Film Cadence (Film (Auto)): the cadence Film holds.
| Value | Meaning |
|---|
| 0 | Auto (default): finds the cadence; falls back to Motion Adaptive whenever the source looks like video |
| 1 | 2:2: for 30 fps sources, such as many PS2 games; holds film through slow and vertical motion |
| 2 | 3: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.
scaler.smoothing_filter
Filter (Smoothing), on the Spatial Super Resolution engine.
| Value | Meaning |
|---|
| 0 | super-xBR (default): smooth curves and diagonals with soft, natural edges |
| 1 | xBRZ: crisp outlines and clean corners; pixel art keeps its shapes with smooth diagonals |
| 2 | Super Eagle: a softer, classic look; neighboring colors blend along the edges |
OSD: Video › Smoothing. In effect while smoothing is on.
scaler.beam_scan_mode
Beam Scan method, used while bfi_enable is true on bitstreams with Beam Scan.
| Value | Meaning |
|---|
| 0 | BFI (default): black frames between picture frames: sharper motion, half the brightness |
| 1 | Rolling Scan: a lit band sweeps down the screen like a CRT's beam; bright parts stay lit longer |
| 2 | Bright 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).
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.
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 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.
scaler.film_set.sensitivity
scaler.film_set.interpolation
scaler.film_set.noise_threshold
scaler.film_set.ela_level
scaler.film_set.motion_detail
scaler.film_set.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).
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.
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.
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
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.
| Value | Meaning |
|---|
| 0 | Even: widens steadily with brightness |
| 1 | Natural: 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.
| Value | Meaning |
|---|
| false | Brightest (the default): the brightest color widens the line for all three |
| true | Each 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):
| Value | Meaning: 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).
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):
| Value | Meaning: 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) |
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.
polyphase.adaptive2.depth_bright
Depth on Bright: how dark the gaps are between bright lines. 100 is black; 0 fills them in.
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.
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.
polyphase.adaptive2.ramp
Width Growth: how the width follows brightness.
| Value | Meaning |
|---|
| 0 | Even (the default): widens steadily with brightness |
| 1 | Natural: keeps dark and mid lines thin, widening near white as a tube does (the beam current) |
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.
interpolation.horiz_kernel
Horizontal Interp.: how the picture is smoothed across when it is scaled.
| Value | Meaning |
|---|
| 4 | Off: every pixel repeated exactly, no smoothing. The crispest, but uneven at some sizes |
| 35 | Sharper Bilinear: very crisp pixel edges with just enough smoothing to keep pixels even |
| 0 | Sharp Bilinear (default): crisp pixels with smooth, even edges. Best for 2D games |
| 1 | Bilinear: soft and even; smooths pixel edges completely |
| 37 | Mitchell: smooth and natural, with fewer jagged edges. Good for 3D games |
| 38 | Catmull-Rom: sharp and detailed. Good for 3D games |
| 39 | Lanczos: the sharpest detail. Best for 3D games and video |
| 36 | Sharper Bil. Alt (developer mode): a variant of Sharper Bilinear |
| 32, 33, 34 | off-centered, off-special, off-leftalign (developer mode): Off variants |
| 5 | the old softer; the OSD shows it as Bilinear |
| 2, 3 | cubic, 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.
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.
interpolation.nn_auto
Disable Interpolation: turns interpolation off (as kernel Off) at integer scale factors, for exactly even pixels.
| Value | Meaning |
|---|
| 0 | off: interpolation stays on at every scale factor |
| 1 | H/V int scale (default): off when both scale factors are integers |
| 2 | H int only: off across when the horizontal scale factor is an integer |
| 3 | V 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.
scaler_polyphase.vert_scanline_mode
Scanlines of the vertical axis: the usual scanlines, gaps between the source's lines.
| Value | Meaning |
|---|
| 0 | Off (default) |
| 1 | Normal: even lines |
| 2 | on (alt) (older OSD): Normal with the older line shape; the Morph 4K's OSD shows Normal |
| 3, 4 | the older Adaptive modes; on bitstreams with Dynamic Scanlines drawn as 6 |
| 5 | Dynamic: lines widen and keep the light, as a tube does (bitstreams with Dynamic Scanlines) |
| 6 | Adaptive: 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.
mask.mode
Mask On / Off.
| Value | Meaning |
|---|
| 0 | Off (the default) |
| 1 | On |
| 2 | Boost: 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.
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.
mask.conversion
Transform: turns or mirrors the pattern, for a rotated screen or a tate game.
| Value | Meaning |
|---|
| 0 | None (the default) |
| 1 | Rotate 90: a quarter turn clockwise |
| 2 | Rotate 180: a half turn |
| 3 | Rotate 270: a quarter turn counterclockwise |
| 4 | Mirror Horiz.: upside down (the rows in reverse order) |
| 5 | Mirror Vert.: left and right swapped |
| 6 | Flip NW/SE: on the diagonal from top left to bottom right |
| 7 | Flip NE/SW: on the diagonal from top right to bottom left |
| 8 | Multiply 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.
| Value | Meaning |
|---|
| 0 | Pattern (the default): a pixel pattern from the mask files on the SD card |
| 1 | Physical: 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:
| Value | Meaning: layout, size, pitch |
|---|
| 0 | 20" Consumer TV (the default): Slot Mask, 20, Standard |
| 1 | 27" Consumer TV: Slot Mask, 27, Coarse |
| 2 | 20" Grille TV: Aperture Grille, 20, Coarse |
| 3 | 14" Studio Monitor: Aperture Grille, 14, Very Fine |
| 4 | 20" Studio Monitor: Aperture Grille, 20, Fine |
| 5 | 19" Arcade Monitor: Delta Dots, 19, Fine |
| 6 | 25" Arcade Monitor: Delta Dots, 25, Coarse |
| 7 | 36" 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.
| Value | Meaning |
|---|
| 0 | Slot Mask: stripes cut into slots |
| 1 | Aperture Grille: unbroken stripes |
| 2 | Delta 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.
| Value | Meaning: mm for Slot Mask, Aperture Grille, Delta Dots |
|---|
| 0 | Very Fine: 0.45, 0.25, 0.40 |
| 1 | Fine: 0.60, 0.30, 0.60 |
| 2 | Standard: 0.75, 0.50, 0.75 |
| 3 | Coarse: 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.
| Value | Meaning |
|---|
| 0 | Follow Zoom (the default): the mask grows with the picture, as on a bigger tube; with a bezel shown it fits the bezel's glass |
| 1 | Fixed: 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.
| Value | Meaning |
|---|
| 0 | Normal (the default) |
| 1 | Rotated: 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.
| Value | Meaning |
|---|
| 0 | Even (the default): every stripe lands on whole pixels, so the mask is even; the pitch is rounded to fit |
| 1 | Exact: 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.
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_names) = 50007 string on FieldOptions
(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
(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
(fx.v1.ini_keep_unknown) = 50021 bool on FieldOptions
(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]).