Prism Manual

GodotPrismBackend

Inherits: RefCounted

A screen reader or speech engine.

Description

A backend presents text through the user’s screen reader or through a speech engine. Backends are obtained from the Prism singleton, a GodotPrismContext, and are initialized before they are returned. An instance created with new() refers to no backend, and is_valid() returns false for it.

The backend is released with its last reference. Speech in progress is stopped first, if the backend supports stop(). Keep a reference for as long as speech should continue, for example in a member variable.

Backends support different operations; features reports which. An unsupported operation returns PRISM_ERROR_NOT_IMPLEMENTED. Methods that can fail return a PrismError value, described by GodotPrismContext.get_error_string(). Property setters and getters print errors instead, and getters then return the value documented for the property.

A backend must not be used from more than one thread at a time. Backends returned by GodotPrismContext.acquire() share an instance, and this applies to all of them.

Use output() for messages to the user; it reaches both speech and braille. The rate, pitch, and volume of screen reader backends cannot be changed.

Tutorials

• Prism manual

Properties

Methods

enum PrismError

PRISM_OK = 0

The operation succeeded.

PRISM_ERROR_NOT_INITIALIZED = 1

The backend failed to initialize when it was obtained.

PRISM_ERROR_INVALID_PARAM = 2

An argument is invalid.

PRISM_ERROR_NOT_IMPLEMENTED = 3

The backend does not support the operation.

PRISM_ERROR_NO_VOICES = 4

The backend has no voices.

PRISM_ERROR_VOICE_NOT_FOUND = 5

The voice does not exist.

PRISM_ERROR_SPEAK_FAILURE = 6

Speech synthesis failed.

PRISM_ERROR_MEMORY_FAILURE = 7

Memory allocation failed.

PRISM_ERROR_RANGE_OUT_OF_BOUNDS = 8

An argument is outside its valid range.

PRISM_ERROR_INTERNAL = 9

An internal error occurred.

PRISM_ERROR_NOT_SPEAKING = 10

No speech is in progress.

PRISM_ERROR_NOT_PAUSED = 11

Speech is not paused.

PRISM_ERROR_ALREADY_PAUSED = 12

Speech is already paused.

PRISM_ERROR_INVALID_UTF8 = 13

A string is not valid UTF-8.

PRISM_ERROR_INVALID_OPERATION = 14

The operation is invalid in the current state.

PRISM_ERROR_ALREADY_INITIALIZED = 15

The backend is already initialized. Not returned by this extension’s methods.

PRISM_ERROR_BACKEND_NOT_AVAILABLE = 16

The backend’s screen reader or speech engine is not installed or not running.

PRISM_ERROR_UNKNOWN = 17

An unclassified error occurred.

PRISM_ERROR_INVALID_AUDIO_FORMAT = 18

The backend’s audio format is not one Prism can convert.

PRISM_ERROR_INTERNAL_BACKEND_LIMIT_EXCEEDED = 19

The backend allows only a fixed number of instances, and another would exceed it.

PRISM_ERROR_BACKEND_ENTERED_UNDEFINED_STATE = 20

The backend is in an undefined state and must not be used further.

PRISM_ERROR_LIBRARY_LOAD_FAILED = 21

A shared library could not be opened.

PRISM_ERROR_LIBRARY_INVALID = 22

A shared library is not a Prism plugin.

PRISM_ERROR_INCOMPATIBLE_ABI = 23

A plugin is incompatible with this version of Prism.

flags PrismBackendFeature

PRISM_BACKEND_IS_SUPPORTED_AT_RUNTIME = 1

The backend’s screen reader or speech engine is available. Advisory; initialization may still fail.

PRISM_BACKEND_SUPPORTS_SPEAK = 4

speak() is supported.

PRISM_BACKEND_SUPPORTS_SPEAK_TO_MEMORY = 8

speak_to_memory() and speak_to_stream() are supported.

PRISM_BACKEND_SUPPORTS_BRAILLE = 16

braille() is supported.

PRISM_BACKEND_SUPPORTS_OUTPUT = 32

output() is supported.

PRISM_BACKEND_SUPPORTS_IS_SPEAKING = 64

speaking reports the backend’s state.

PRISM_BACKEND_SUPPORTS_STOP = 128

stop() is supported.

PRISM_BACKEND_SUPPORTS_PAUSE = 256

pause() is supported.

PRISM_BACKEND_SUPPORTS_RESUME = 512

resume() is supported.

PRISM_BACKEND_SUPPORTS_SET_VOLUME = 1024

volume can be set.

PRISM_BACKEND_SUPPORTS_GET_VOLUME = 2048

volume can be read.

PRISM_BACKEND_SUPPORTS_SET_RATE = 4096

rate can be set.

PRISM_BACKEND_SUPPORTS_GET_RATE = 8192

rate can be read.

PRISM_BACKEND_SUPPORTS_SET_PITCH = 16384

pitch can be set.

PRISM_BACKEND_SUPPORTS_GET_PITCH = 32768

pitch can be read.

PRISM_BACKEND_SUPPORTS_REFRESH_VOICES = 65536

refresh_voices() is supported.

PRISM_BACKEND_SUPPORTS_COUNT_VOICES = 131072

voices_count reports the number of voices.

PRISM_BACKEND_SUPPORTS_GET_VOICE_NAME = 262144

get_voice_name() is supported.

PRISM_BACKEND_SUPPORTS_GET_VOICE_LANGUAGE = 524288

get_voice_language() is supported.

PRISM_BACKEND_SUPPORTS_GET_VOICE = 1048576

voice can be read.

PRISM_BACKEND_SUPPORTS_SET_VOICE = 2097152

voice can be set.

PRISM_BACKEND_SUPPORTS_GET_CHANNELS = 4194304

channels can be read.

PRISM_BACKEND_SUPPORTS_GET_SAMPLE_RATE = 8388608

sample_rate can be read.

PRISM_BACKEND_SUPPORTS_GET_BIT_DEPTH = 16777216

bit_depth can be read.

PRISM_BACKEND_PERFORMS_SILENCE_TRIMMING_ON_SPEAK = 33554432

The backend removes leading and trailing silence from speech.

PRISM_BACKEND_PERFORMS_SILENCE_TRIMMING_ON_SPEAK_TO_MEMORY = 67108864

The backend removes leading and trailing silence from synthesized audio.

PRISM_BACKEND_SUPPORTS_SPEAK_SSML = 134217728

Reserved.

PRISM_BACKEND_SUPPORTS_SPEAK_TO_MEMORY_SSML = 268435456

Reserved.

PRISM_BACKEND_IS_SCREEN_READER = 72057594037927936

The backend sends messages to a screen reader. Every built-in backend has exactly one of this flag and PRISM_BACKEND_IS_SPEECH_ENGINE.

PRISM_BACKEND_IS_SPEECH_ENGINE = 144115188075855872

The backend synthesizes speech without a screen reader.

Property Descriptions

int bit_depth

Getter get_bit_depth()

The bit depth of the speech engine’s native audio, commonly 8 or 16. speak_to_memory() always delivers floating-point samples. -1 if the backend does not support synthesis to memory or the query fails.

int channels

Getter get_channels()

The number of channels in synthesized audio, usually 1. It depends on the voice. -1 if the backend does not support synthesis to memory or the query fails.

PrismBackendFeature features

Getter get_features()

The backend’s PrismBackendFeature flags. The backend is queried each time the property is read.

String name

Getter get_name()

The name of the backend, such as "NVDA".

float pitch

Setter set_pitch(value), getter get_pitch()

The pitch of speech, from 0.0 (lowest) to 1.0 (highest). 0.5 is the backend’s default. A new value applies to subsequent speech. Not supported by screen readers, or by speech engines whose voices have a fixed pitch.

Reads 0.5 if unsupported and NAN if the query fails. Setting a value outside the range, or setting it on a backend that does not support it, prints an error.

float rate

Setter set_rate(value), getter get_rate()

The rate of speech, from 0.0 (slowest) to 1.0 (fastest). 0.5 is always the backend’s default. A new value applies to subsequent speech. Not supported by screen readers.

Reads 0.5 if unsupported and NAN if the query fails. Setting a value outside the range, or setting it on a backend that does not support it, prints an error.

int sample_rate

Getter get_sample_rate()

The sample rate of synthesized audio, in hertz. It depends on the voice. -1 if the backend does not support synthesis to memory or the query fails.

bool speaking

Getter get_speaking()

true while speech is in progress. Paused speech is not in progress. Reads false if the backend cannot report its state, as most screen readers cannot, or if the query fails; check PRISM_BACKEND_SUPPORTS_IS_SPEAKING before relying on false.

int voice

Setter set_voice(value), getter get_voice()

The index of the voice used for speech, from 0 to voices_count minus one. Initially the backend’s default voice. A new voice applies to subsequent speech, and may change channels, sample_rate, and bit_depth.

Reads -1 if the backend does not support voices or the query fails. Setting an index out of range, or setting it on a backend that does not support voices, prints an error.

int voices_count

Getter get_voices_count()

The number of voices, as of the last refresh_voices(). 0 if no voices are installed, the backend does not support voices, or the query fails.

float volume

Setter set_volume(value), getter get_volume()

The volume of speech, from 0.0 (silent) to 1.0 (loudest), independent of the system volume. 0.5 is the backend’s default. A new value applies to subsequent speech. Not supported by screen readers.

Reads 0.5 if unsupported and NAN if the query fails. Setting a value outside the range, or setting it on a backend that does not support it, prints an error.

Method Descriptions

PrismError braille(text: String)

Shows text on the user’s braille display, according to the screen reader’s braille settings. Braille output does not affect speech.

Returns PRISM_ERROR_INVALID_PARAM if text is empty, and PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support braille, as no speech engine does. Some backends succeed when no display is connected and others fail, so the result does not indicate whether a display is present.

int find_voice(pattern: String) const

Returns the index of the first voice whose name contains pattern, ignoring case, or -1 if pattern is empty or no voice matches.

int find_voice_by_language(prefix: String) const

Returns the index of the first voice whose language begins with prefix, ignoring case, or -1 if prefix is empty or no voice matches. "en" matches "en-US" and "en-GB".

String get_voice_language(index: int) const

Returns the language of the voice at index, usually a BCP 47 tag such as "en-US". Returns an empty String if the backend does not support voices, index is out of range, or the query fails.

String get_voice_name(index: int) const

Returns the name of the voice at index, such as "Microsoft David". Returns an empty String if the backend does not support voices, index is out of range, or the query fails.

Dictionary[] get_voices() const

Returns a Dictionary for each voice, in index order, with the keys "index", "name", and "language". Returns an empty array if the backend does not support voices.

bool has_feature(flag: PrismBackendFeature) const

Returns true if the backend has every feature in flag. The backend is queried on each call.

if backend.has_feature(GodotPrismBackend.PRISM_BACKEND_SUPPORTS_IS_SPEAKING):
    print(backend.speaking)

bool is_valid() const

Returns true if the object refers to a backend. A backend that failed to initialize is valid; its methods return PRISM_ERROR_NOT_INITIALIZED.

PrismError output(text: String, interrupt: bool = false)

Presents text through speech and braille. A screen reader backend speaks the text and shows it on the braille display; a speech engine speaks it. interrupt has the same meaning as for speak().

Returns PRISM_ERROR_INVALID_PARAM if text is empty. May return PRISM_OK when one of speech and braille fails.

PrismError pause()

Pauses speech. Queued speech is kept, and resume() continues from the same position. While paused, speaking is false.

Returns PRISM_ERROR_NOT_SPEAKING if no speech is in progress, PRISM_ERROR_ALREADY_PAUSED if speech is already paused, and PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support pausing.

PrismError refresh_voices()

Reloads the list of voices from the system. Voices installed while the project runs appear only after a refresh. Voice indices may change, so a stored choice of voice should be identified by name, for example with find_voice().

Returns PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support voices, as no screen reader does.

PrismError resume()

Resumes speech paused by pause(). Returns PRISM_ERROR_NOT_PAUSED if speech is not paused, including after stop(), and PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support resuming.

PrismError speak(text: String, interrupt: bool = false)

Speaks text with the current voice, rate, pitch, and volume. Depending on the backend, returns when speech starts or when it ends.

If interrupt is true, speech in progress is stopped and queued speech is discarded first. If false, most backends queue the text; some mix it with speech in progress, and screen readers may apply their own setting.

Returns PRISM_ERROR_INVALID_PARAM if text is empty, PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support speech, and PRISM_ERROR_SPEAK_FAILURE if synthesis fails. Some backends limit the length of text, so long text should be divided.

var err := backend.speak("Hello from Prism.", true)
if err != GodotPrismBackend.PRISM_OK:
    push_error("Speech failed: %s" % Prism.get_error_string(err))

PrismError speak_to_memory(text: String, callback: Callable)

Synthesizes text and calls callback once with the audio: a PackedFloat32Array of interleaved samples from -1.0 to 1.0, the number of channels, and the sample rate in hertz. callback is called on the calling thread before the method returns, and is not called if synthesis fails. The method may take noticeable time for long text.

Returns PRISM_ERROR_INVALID_PARAM if text is empty or callback is invalid, and PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support synthesis to memory, as no screen reader does. See also speak_to_stream().

AudioStreamWAV speak_to_stream(text: String)

Synthesizes text and returns the audio as a 16-bit AudioStreamWAV, which can be played through an AudioStreamPlayer or a positional player.

Returns null if text is empty, the backend does not support synthesis to memory, synthesis fails, or no audio is produced. Failures other than empty text and empty audio are printed. The stream is stereo if the backend produces more than one channel; more than two channels are not represented correctly.

var stream := backend.speak_to_stream("Behind you.")
if stream != null:
    $AudioStreamPlayer3D.stream = stream
    $AudioStreamPlayer3D.play()

PrismError stop()

Stops speech and discards queued speech. A screen reader backend stops only speech it produced.

Returns PRISM_ERROR_NOT_IMPLEMENTED if the backend does not support stopping. Some backends return PRISM_ERROR_NOT_SPEAKING if no speech is in progress; most return PRISM_OK.