Scripting Interface

This document defines how scripted control is supposed to interact with the system. It is more formal than the commands-and-functions index and should be read by anyone implementing automation, a CLI, or batch processes.

Execution Model

COMMANDS → NORMALIZED STATE → CANONICAL COMPOSITION → RENDER → OUTPUT

Scripted operations must terminate in the same canonical composition model used by the UI. Scripting is not a side door around rendering rules.

Determinism Rules

• Same input state should produce the same output state and same render decisions.
• Export must wait for required dependencies such as QR readiness and text layout readiness.
• No hidden UI-only behavior may be required for script success.
• Script interfaces must be versioned when argument meaning changes.

Recommended Function Categories

• playlist and item loading
• thumbnail / URL-art / QR configuration
• layout and fit-mode control
• render invocation
• export invocation
• localization key selection
• inspection/status retrieval for automation

Script-Specific Failure Conditions

• A scripted export that omits QR while QR is enabled and visible is a failure.
• A scripted export that resolves to viewport-size output instead of selected export size is a failure.
• Any scripting feature that exists in code but is not documented here or in commands-and-functions is incomplete.