Prism Manual

GodotPrismContext

Inherits: Object

Provides access to the user’s screen reader and to speech engines.

Description

The extension registers one instance of this class as the singleton Prism, created when the extension is loaded and freed when it is unloaded. Further instances should not be created.

The singleton holds a registry of backends. Each backend is a screen reader or a speech engine, and is obtained as a GodotPrismBackend. The registry contains the backends compiled into the extension for the current platform, and those loaded with load_backend_library(). Backends are ordered by priority, and screen readers have higher priority than speech engines, so create_best() returns the user’s screen reader if one is running, and a speech engine otherwise.

extends Node

var backend: GodotPrismBackend

func _ready() -> void:
    backend = Prism.create_best()
    if backend == null:
        push_error("No speech backend is available.")
        return
    var err := backend.output("Hello from Prism.")
    if err != GodotPrismBackend.PRISM_OK:
        push_error("Output failed: %s" % Prism.get_error_string(err))

Backend identifiers are [int] values: the PrismBackendId constants for built-in backends, and a hash of the name for others. An identifier whose highest bit is set is negative, so identifiers should be compared and stored, not used in arithmetic.

Availability changes and log messages are delivered through signals emitted on the main thread. See start_availability_monitoring() and set_log_signal_enabled().

Backends cannot be implemented in GDScript, because Prism calls backend implementations on other threads. Custom backends must be built as shared libraries and loaded with load_backend_library().

Tutorials

• Prism manual

Properties

Methods

Signals

availability_baseline_established()

Emitted once each time availability monitoring starts, after every backend has been sampled once and before any backend_availability_changed.

A change between a check made with is_backend_available() and the first sample of the same backend is part of the baseline and is not reported. If such a check was made before this signal and its result kept, the check should be repeated when this signal is emitted. A later backend_availability_changed may then report a change the repeated check already observed.

backend_availability_changed(id: int, name: String, available: bool)

Emitted when the backend id, named name, becomes available (available is true) or unavailable (available is false), while availability monitoring is active. Backends already obtained are not affected.

Emitted on the main thread during idle processing, which may be slightly after the change.

log_message_received(level: int, source: String, message: String)

Emitted for each log message while set_log_signal_enabled() is on. level is a PrismLogLevel value, and source is the component that wrote the message.

Emitted on the main thread during idle processing. Messages written faster than they are delivered are dropped, and a warning reports how many.

enum PrismBackendId

INVALID = 0

Never identifies a backend. Returned by methods that find no backend.

SAPI = 2120622734136241766

Microsoft Speech API (SAPI), on Windows.

AV_SPEECH = 2946271790952897572

AVSpeechSynthesizer, on Apple platforms.

VOICE_OVER = -3798619614742230069

The VoiceOver screen reader, on Apple platforms.

SPEECH_DISPATCHER = -2029161259604513794

Speech Dispatcher, on Linux and BSD.

NVDA = -8517404458065585578

The NVDA screen reader, on Windows.

JAWS = -6035561368583359170

The JAWS screen reader, on Windows.

ONE_CORE = 7464667106434960564

Windows OneCore speech synthesis, on Windows 10 and later.

ORCA = 1200807161653361004

The Orca screen reader, on Linux and BSD.

ANDROID_TTS = -4893345499418663476

The Android text-to-speech engine.

ANDROID_SCREEN_READER = -3343428537155827381

The active Android screen reader, such as TalkBack.

WEB_SPEECH = 3851232497565452943

The Web Speech API, on the web.

UIA = 7077670808258580366

UI Automation notifications, announced by any running Windows screen reader.

ZDSR = 4437107128196344366

The Zhengdu screen reader (ZDSR), on Windows.

ZOOM_TEXT = -5889690839739067271

ZoomText, on Windows.

BOY_PC_READER = 2907841139227963407

The Boy PC Reader screen reader, on Windows.

PC_TALKER = 3768269449491363893

The PC-Talker screen reader, on Windows.

SENSE_READER = -1349003421657218318

The Sense Reader screen reader, on Windows.

SYSTEM_ACCESS = -8970903673761939786

The System Access screen reader, on Windows. Available only in builds that enable legacy backends.

WINDOW_EYES = -7989147587171558381

The Window-Eyes screen reader, on Windows. Available only in builds that enable legacy backends.

SPIEL = 5155290001588869276

Spiel, on Linux.

GDK_SPEECH = -3198251574740554991

Speech synthesis of the Microsoft Game Development Kit, on Windows and Xbox.

enum PrismLogLevel

PRISM_LOG_LEVEL_TRACE = 0

Trace messages, the least severe level.

PRISM_LOG_LEVEL_DEBUG = 1

Debug messages.

PRISM_LOG_LEVEL_INFO = 2

Informational messages.

PRISM_LOG_LEVEL_WARN = 3

Warnings.

PRISM_LOG_LEVEL_ERROR = 4

Errors, the most severe level.

PRISM_LOG_LEVEL_NONE = 5

Above every severity. As the level passed to set_log_level(), delivers nothing.

Property Descriptions

int backends_count

Getter get_backends_count()

The number of backends in the registry, including backends that cannot currently be used. It changes only when load_backend_library() succeeds.

Method Descriptions

GodotPrismBackend acquire(id: int)

Returns the shared instance of the backend id, creating and initializing it if necessary, or null if the registry does not contain the backend or it cannot be created. All objects returned by acquire(), acquire_best(), and get_backend() for the same backend share one instance, including its settings. Use create() unless sharing is intended.

If initialization fails, the error is printed and the backend is still returned; its methods then return GodotPrismBackend.PRISM_ERROR_NOT_INITIALIZED.

GodotPrismBackend acquire_best()

Returns the shared instance of the highest-priority backend that can be initialized, or null if none can. Existing shared instances are used where they exist. Use create_best() unless sharing is intended.

GodotPrismBackend create(id: int)

Creates and initializes a new instance of the backend id. Returns null if the registry does not contain the backend or it cannot be created. Initialization may take noticeable time.

If initialization fails, for example because the backend’s screen reader is not running, the error is printed and the backend is still returned; its methods then return GodotPrismBackend.PRISM_ERROR_NOT_INITIALIZED. Create the backend again to retry. create_best() skips backends that cannot be initialized.

GodotPrismBackend create_best()

Creates and initializes the highest-priority backend that can be initialized, or returns null if none can. The result is the user’s screen reader if one is running, and a speech engine otherwise. null is a normal result on a system without a speech engine, and must be handled.

The choice is not revisited if a screen reader starts or stops later. See start_availability_monitoring().

void flush_log() static

Waits until every log message written so far has been passed to the log handler. Returns immediately if no handler is installed. log_message_received is emitted for these messages during the next idle frame, after this method returns.

Dictionary[] get_available_backends() const

Returns a Dictionary for each backend in the registry, in priority order, with the keys "id", "name", and "priority". The result includes backends that cannot currently be used; see is_backend_available().

GodotPrismBackend get_backend(id: int)

Returns the shared instance of the backend id, or null if there is none. Unlike acquire(), this method never creates an instance.

String get_error_string(error: PrismError) static

Returns an English description of error, or "Unknown error" if it is not a GodotPrismBackend.PrismError value.

int get_version() static

Returns the version of the Prism library, encoded as (major << 16) | (minor << 8) | patch. Version 1.4.7 is 0x010407. Encoded versions compare in version order.

String get_version_string() static

Returns the version of the Prism library as a string, such as "1.4.7".

bool has(id: int) const

Returns true if the registry contains the backend id. This does not mean the backend can be used; see is_backend_available().

int id_at(index: int) const

Returns the identifier of the backend at index in the registry, or INVALID if index is out of range. Index 0 is the highest-priority backend.

int id_of(name: String) const

Returns the identifier of the backend named name, or INVALID if name is empty or no backend has that name. The comparison is case-sensitive.

bool is_auto_power_management_supported() static

Returns true if the auto_power_manage argument of start_availability_monitoring() has an effect on this platform. Otherwise, monitoring continues while the system is suspended unless pause_availability_monitoring() is called.

bool is_availability_monitoring() const

Returns true if availability monitoring is active, including while it is paused.

bool is_backend_available(id: int)

Returns true if the backend id can currently be used. A temporary instance is created and queried, without being initialized. The result is advisory: initialization may still fail. Returns false if the registry does not contain the backend.

bool is_log_signal_enabled() const

Returns true if log messages are delivered through log_message_received.

PrismError load_backend_library(path: String, priority_override: int = -1)

Loads the backends of the shared library plugin at path. path may be absolute or begin with res:// or user://, and may refer to a file in the project’s PCK. If priority_override is not negative, it replaces the priority of every backend in the plugin.

Returns GodotPrismBackend.PRISM_OK on success. Returns GodotPrismBackend.PRISM_ERROR_INVALID_PARAM if path is empty or priority_override is too large, GodotPrismBackend.PRISM_ERROR_NOT_IMPLEMENTED if the platform does not support shared library backends, GodotPrismBackend.PRISM_ERROR_LIBRARY_LOAD_FAILED if the library cannot be opened, GodotPrismBackend.PRISM_ERROR_LIBRARY_INVALID if it is not a Prism plugin, GodotPrismBackend.PRISM_ERROR_INCOMPATIBLE_ABI if it is incompatible with this version of Prism, and GodotPrismBackend.PRISM_ERROR_INVALID_OPERATION if one of its backends has the name of a backend already in the registry.

A successful call replaces the singleton’s registry with one that also contains the new backends. Backends obtained earlier remain valid. Active availability monitoring is restarted, and availability_baseline_established is emitted again. If the call fails, nothing changes, except that if the library loads but monitoring cannot be restarted, the new registry is kept, monitoring is stopped, and GodotPrismBackend.PRISM_ERROR_INTERNAL is returned.

A library inside the PCK is first copied to user://prism/backends/, into a directory named after the SHA-256 hash of its contents, and loaded from there. The copy is reused by later calls. Libraries the plugin depends on are not copied, and must be found through the platform’s library search path. On macOS, the library must be signed before it is packed, by the project’s team if library validation is enforced. The directory may be deleted while no copy is loaded.

Loading a library runs its code with the project’s privileges. Only load trusted libraries.

String name_of(id: int) const

Returns the name of the backend id, such as "NVDA", or an empty String if the registry does not contain it.

void pause_availability_monitoring()

Pauses availability monitoring. While paused, monitoring uses no processor time. Does nothing if monitoring is not active.

int priority_of(id: int) const

Returns the priority of the backend id, or -1 if the registry does not contain it. Higher priorities are tried first by create_best(). The priorities of built-in backends may change between releases.

void resume_availability_monitoring()

Resumes paused availability monitoring. Every backend is sampled immediately, and backend_availability_changed is emitted for each whose availability differs from what was last reported. A change that occurred and reverted while paused is not reported. Does nothing if monitoring is not active.

PrismLogLevel set_log_level(level: PrismLogLevel) static

Sets the least severe level of log message delivered, and returns the previous level. The initial level is PRISM_LOG_LEVEL_NONE, which delivers nothing. The level applies to the whole process.

void set_log_signal_enabled(enabled: bool)

If enabled is true, log messages are delivered through log_message_received, replacing the log handler in effect, including the one installed for the PRISM_LOG environment variable. If false, the previous handler is restored.

No messages are delivered until set_log_level() lowers the level.

func _ready() -> void:
    Prism.log_message_received.connect(_on_log_message)
    Prism.set_log_signal_enabled(true)
    Prism.set_log_level(GodotPrismContext.PRISM_LOG_LEVEL_INFO)

func _on_log_message(level: int, source: String, message: String) -> void:
    print("%s: %s" % [source, message])

PrismError start_availability_monitoring(poll_interval_ms: int = 0, debounce_samples: int = 0, backoff_max_ms: int = 0, auto_power_manage: bool = true)

Starts sampling the availability of every backend on a background thread. backend_availability_changed is emitted when a backend becomes available or unavailable.

poll_interval_ms is the base interval between samples in milliseconds; 0 selects 1000. debounce_samples is the number of consecutive samples that must agree before a change is reported; 0 selects 2, and 1 reports changes immediately. backoff_max_ms is the longest interval, to which the interval doubles while nothing changes; 0, or a value not greater than poll_interval_ms, keeps the interval constant. If auto_power_manage is true, sampling stops while the system is suspended, where is_auto_power_management_supported() returns true.

The first sample of each backend sets a baseline and is not reported. availability_baseline_established is emitted once the baseline is set.

Returns GodotPrismBackend.PRISM_OK on success, GodotPrismBackend.PRISM_ERROR_RANGE_OUT_OF_BOUNDS if an integer argument is negative or greater than 4294967295, GodotPrismBackend.PRISM_ERROR_INVALID_OPERATION if monitoring is already active, and GodotPrismBackend.PRISM_ERROR_INTERNAL if monitoring cannot be started.

func _ready() -> void:
    Prism.backend_availability_changed.connect(_on_availability_changed)
    var err := Prism.start_availability_monitoring()
    if err != GodotPrismBackend.PRISM_OK:
        push_error("Monitoring failed: %s" % Prism.get_error_string(err))

func _on_availability_changed(id: int, backend_name: String, available: bool) -> void:
    print("%s: %s" % [backend_name, available])

void stop_availability_monitoring()

Stops availability monitoring. Does nothing if monitoring is not active.

PrismError write_log(level: PrismLogLevel, source: String, message: String) static

Writes message to Prism’s log, from the component source, at level. The message is queued and delivered with Prism’s own messages; it is dropped if the queue is full. level must not be PRISM_LOG_LEVEL_NONE.

Returns GodotPrismBackend.PRISM_OK, or GodotPrismBackend.PRISM_ERROR_INVALID_PARAM if source or message is empty.