Backend
prism.Backend
A backend instance.
Syntax
class Backend(raw_ptr: ffi.CData)
Parameters
raw_ptr
A PrismBackend * returned by a registry function.
Exceptions
If raw_ptr is NULL.
If a component the backend requires is missing or not running.
If initialization fails for another reason.
Remarks
Backends are obtained from Context, and are initialized before they
are returned. This class SHOULD NOT be instantiated directly.
The backend is released when the object is destroyed. A backend obtained
through Context.create or Context.create_best is an
independent instance. A backend obtained through Context.acquire,
Context.acquire_best, or Context.get shares one instance
with every object obtained in that way for the same backend: settings
changed through one object are visible through the others, and the instance
is released with the last of them. Releasing a backend MAY discard speech
that is queued or playing, so a reference MUST be kept for as long as speech
is expected to continue.
A backend is not thread-safe. It MUST NOT be used from more than one thread at a time, and this applies to all objects sharing an instance. Distinct instances MAY be used from different threads.
An operation the backend does not support raises
prism.common.PrismNotImplementedError; features reports
which operations are supported. Other failures raise the subclass of
prism.PrismError for the error Prism reports. Each method lists the
exceptions specific to it.
Text arguments MUST be non-empty, MUST NOT contain a NUL character, and MUST be encodable as UTF-8.
Used by Context. This constructor wraps
prism_backend_initialize, and takes ownership of raw_ptr. A backend
that is already initialized is not initialized again.
Backend.name
The name of the backend, such as "NVDA".
Syntax
name: str # read-only
Remarks
Wraps prism_backend_name. The name is the one Context.name_of
returns for the backend’s identifier.
Backend.speak
Speaks text.
Syntax
def speak(text: str, interrupt: bool = False) -> None
Parameters
text
The text to speak.
interrupt
If True, speech in progress is stopped and queued speech
is discarded before the text is spoken. If False, the text is
queued after speech in progress on most backends; some mix the two,
and screen readers MAY apply their own setting.
Exceptions
If text is empty or contains a NUL
character.
If text cannot be encoded as UTF-8.
If the backend does not support speech.
If synthesis fails.
Remarks
This method wraps prism_backend_speak. The text is spoken with the
current voice, rate, pitch, and volume. Depending on the backend, the method
returns when speech starts or when it ends; speaking reports
whether speech is still in progress, where supported.
A screen reader backend passes the text to the screen reader, which speaks it according to the user’s settings. Some backends limit the length of text; long text SHOULD be divided into shorter segments.
Backend.speak_to_memory
Synthesizes text and passes the audio to a function.
Syntax
def speak_to_memory(text: str, on_audio_data: AudioCallback) -> None
Parameters
text
The text to synthesize.
on_audio_data
The function that receives the audio.
Exceptions
If text is empty or contains a NUL
character.
If text cannot be encoded as UTF-8.
If the backend does not support synthesis to memory. No screen reader backend supports it.
If the backend produces audio Prism cannot convert.
If synthesis fails.
Remarks
This method wraps prism_backend_speak_to_memory. It returns when
synthesis is complete and all audio has been passed to on_audio_data,
on every backend.
on_audio_data is called one or more times, each time with the next
portion of the audio, as described under AudioCallback. It MAY be
called on a thread other than the calling thread, and MUST NOT use this
backend. If it raises an exception, it is not called again for this
synthesis, and the exception is re-raised by this method when synthesis
ends.
The format of the audio is reported in advance by channels and
sample_rate. Calling stop during synthesis has undefined
behavior.
Backend.braille
Shows text on a braille display.
Syntax
def braille(text: str) -> None
Parameters
text
The text to show.
Exceptions
If text is empty or contains a NUL
character.
If text cannot be encoded as UTF-8.
If the backend does not support braille. No speech engine backend supports it.
Remarks
This method wraps prism_backend_braille. The text is shown according to
the screen reader’s braille settings. Braille output is independent of
speech. Some backends succeed when no display is connected and others raise
an exception, so the outcome does not indicate whether a display is present.
Backend.output
Presents text through speech and braille.
Syntax
def output(text: str, interrupt: bool = False) -> None
Parameters
text
The text to present.
interrupt
As for speak.
Exceptions
If text is empty or contains a NUL
character.
If text cannot be encoded as UTF-8.
If the backend does not support output.
If output fails.
Remarks
This method wraps prism_backend_output. A screen reader backend speaks
the text and shows it on the braille display; a speech engine backend
speaks it, as speak does. Messages meant for the user SHOULD be
presented with this method, since a screen reader user may rely on braille
alone. The method MAY succeed when one of the two fails.
Backend.stop
Stops speech and discards queued speech.
Syntax
def stop() -> None
Exceptions
If the backend does not support stopping.
If no speech is in progress, on some backends. Most backends succeed in that case.
Remarks
This method wraps prism_backend_stop. After it returns,
speaking is False. A screen reader backend stops only speech it
produced, not speech the screen reader produces on its own.
Calling this method during speak_to_memory has undefined behavior.
Backend.pause
Pauses speech.
Syntax
def pause() -> None
Exceptions
If the backend does not support pausing.
If no speech is in progress.
If speech is already paused.
Remarks
This method wraps prism_backend_pause. Queued speech is kept, and
resume continues from the paused position. While paused,
speaking is False. Speaking with interrupt=True discards the
paused speech; speaking with interrupt=False queues after it.
Backend.resume
Resumes speech paused by pause.
Syntax
def resume() -> None
Exceptions
If the backend does not support resuming.
If speech is not paused, including after
stop.
Remarks
This method wraps prism_backend_resume.
Backend.speaking
Whether speech is in progress.
Syntax
speaking: bool # read-only
Remarks
Wraps prism_backend_is_speaking. Paused speech is not in progress. The
value MAY remain True briefly after the last audio is heard. Most screen
reader backends do not support this property and raise
PrismNotImplementedError.
Backend.volume
The speech volume, from 0.0 (silent) to 1.0 (loudest).
Syntax
volume: float
Remarks
Wraps prism_backend_get_volume and prism_backend_set_volume. The
volume is relative to the backend and independent of the system volume. 0.5
is the backend’s default level. A new value applies to subsequent speech.
Screen reader backends do not support this property and raise
PrismNotImplementedError. Setting a value outside [0.0, 1.0], NaN,
or infinity raises PrismRangeError.
Backend.rate
The speech rate, from 0.0 (slowest) to 1.0 (fastest).
Syntax
rate: float
Remarks
Wraps prism_backend_get_rate and prism_backend_set_rate. 0.5 is
always the backend’s default rate. The rate changes tempo but not pitch. A
new value applies to subsequent speech.
Screen reader backends do not support this property and raise
PrismNotImplementedError. Setting a value outside [0.0, 1.0] raises
PrismRangeError.
Backend.pitch
The speech pitch, from 0.0 (lowest) to 1.0 (highest).
Syntax
pitch: float
Remarks
Wraps prism_backend_get_pitch and prism_backend_set_pitch. 0.5 is
the backend’s default pitch. A new value applies to subsequent speech.
Screen reader backends, and speech engines whose voices have a fixed pitch,
do not support this property and raise PrismNotImplementedError.
Setting a value outside [0.0, 1.0] raises PrismRangeError.
Backend.refresh_voices
Reloads the list of voices from the system.
Syntax
def refresh_voices() -> None
Exceptions
If the backend does not support voices. No screen reader backend supports them.
Remarks
This method wraps prism_backend_refresh_voices. Voices installed after
the backend was initialized appear only after a refresh. A refresh MAY change
voice indices, so a stored choice of voice SHOULD be identified by name.
Backends that read their voices only during initialization succeed without
changing the list.
Backend.voices_count
The number of voices.
Syntax
voices_count: int # read-only
Remarks
Wraps prism_backend_count_voices. Voice indices run from 0 to one less
than this value. The value changes only after refresh_voices.
Backends without voice support raise PrismNotImplementedError.
Backend.get_voice_name
Returns the name of a voice.
Syntax
def get_voice_name(idx: int) -> str
Parameters
idx
The index of the voice.
Return Value
The name of the voice, such as "Microsoft David".
Exceptions
If idx is out of range.
If the backend does not support voices.
Remarks
This method wraps prism_backend_get_voice_name. Names come from the
speech engine and are often localized.
Backend.get_voice_language
Returns the language of a voice.
Syntax
def get_voice_language(idx: int) -> str
Parameters
idx
The index of the voice.
Return Value
The language of the voice, usually a BCP 47 tag such as "en-US".
Exceptions
If idx is out of range.
If the backend does not support voices.
Remarks
This method wraps prism_backend_get_voice_language.
Backend.voice
The index of the voice used for speech.
Syntax
voice: int
Remarks
Wraps prism_backend_get_voice and prism_backend_set_voice. Until a
voice is set, the value is the index of the backend’s default voice. A new
voice applies to subsequent speech, and MAY change channels,
sample_rate, and bit_depth. After refresh_voices,
the value is the voice’s new index; if the voice no longer exists, the
behavior is undefined.
Setting an index not less than voices_count raises
PrismRangeError or PrismVoiceNotFoundError. If setting the
voice leaves the backend unusable, the setter raises
PrismBackendEnteredUndefinedStateError. Backends without voice
support raise PrismNotImplementedError.
Backend.channels
The number of channels in the audio of speak_to_memory.
Syntax
channels: int # read-only
Remarks
Wraps prism_backend_get_channels. Usually 1. The value depends on the
voice. Backends without synthesis to memory raise
PrismNotImplementedError.
Backend.sample_rate
The sample rate, in hertz, of the audio of speak_to_memory.
Syntax
sample_rate: int # read-only
Remarks
Wraps prism_backend_get_sample_rate. Common values are 16000, 22050,
44100, and 48000. The value depends on the voice. Backends without synthesis
to memory raise PrismNotImplementedError.
Backend.bit_depth
The bit depth of the speech engine’s native audio.
Syntax
bit_depth: int # read-only
Remarks
Wraps prism_backend_get_bit_depth. Common values are 8 and 16. Audio
from speak_to_memory is always delivered as float samples, so the
value is informational. Backends without synthesis to memory raise
PrismNotImplementedError.
Backend.features
Feature information for the backend.
Syntax
features: BackendFeatures # read-only
Remarks
Wraps prism_backend_get_features. The backend is queried on each access,
so BackendFeatures.is_supported_at_runtime is current. Determining
it MAY require probing for a running process or service, so the result
SHOULD be kept rather than read repeatedly when only the other fields are
needed.
prism.BackendFeatures
Feature information for a backend.
Syntax
class BackendFeatures(
is_supported_at_runtime: bool = _bit(0),
supports_speak: bool = _bit(2),
supports_speak_to_memory: bool = _bit(3),
supports_braille: bool = _bit(4),
supports_output: bool = _bit(5),
supports_is_speaking: bool = _bit(6),
supports_stop: bool = _bit(7),
supports_pause: bool = _bit(8),
supports_resume: bool = _bit(9),
supports_set_volume: bool = _bit(10),
supports_get_volume: bool = _bit(11),
supports_set_rate: bool = _bit(12),
supports_get_rate: bool = _bit(13),
supports_set_pitch: bool = _bit(14),
supports_get_pitch: bool = _bit(15),
supports_refresh_voices: bool = _bit(16),
supports_count_voices: bool = _bit(17),
supports_get_voice_name: bool = _bit(18),
supports_get_voice_language: bool = _bit(19),
supports_get_voice: bool = _bit(20),
supports_set_voice: bool = _bit(21),
supports_get_channels: bool = _bit(22),
supports_get_sample_rate: bool = _bit(23),
supports_get_bit_depth: bool = _bit(24),
performs_silence_trimming_on_speak: bool = _bit(25),
performs_silence_trimming_on_speak_to_memory: bool = _bit(26),
supports_speak_ssml: bool = _bit(27),
supports_speak_to_memory_ssml: bool = _bit(28),
is_screen_reader: bool = _bit(56),
is_speech_engine: bool = _bit(57),
)
Remarks
Represents the mask returned by prism_backend_get_features, with one
bool field for each defined bit. A field is named after its
PrismBackendFeature constant without the PRISM_BACKEND_ prefix, in
lower case: supports_speak is PRISM_BACKEND_SUPPORTS_SPEAK.
is_supported_at_runtime is True when the backend’s screen reader or
speech engine is available. It is advisory; obtaining the backend MAY still
fail.
A field beginning with supports_ is True when the backend implements
the operation it names, using the operation’s C name:
supports_count_voices concerns prism.Backend.voices_count, and
supports_is_speaking concerns prism.Backend.speaking. An
operation whose field is False raises PrismNotImplementedError.
supports_speak_ssml and supports_speak_to_memory_ssml are reserved.
performs_silence_trimming_on_speak and
performs_silence_trimming_on_speak_to_memory are True when the
backend removes leading and trailing silence from spoken output, or from
audio delivered by prism.Backend.speak_to_memory.
is_screen_reader is True for a backend that sends messages to a
screen reader, and is_speech_engine for one that synthesizes speech
itself. At most one is True. Every built-in backend sets exactly one; a
custom backend MAY set neither.
Instances are immutable and compare equal when all fields are equal.
BackendFeatures.from_bits
Creates feature information from a feature mask.
Syntax
@classmethod
def from_bits(bits: int) -> BackendFeatures
Parameters
bits
A mask of PrismBackendFeature bits. Undefined bits are
ignored.
Return Value
Feature information whose fields are True for the bits set in
bits.
BackendFeatures.to_bits
Returns the feature mask represented by this object.
Syntax
def to_bits() -> int
Return Value
A mask with the bit of each True field set.
Remarks
BackendFeatures.from_bits(features.to_bits()) is equal to features.
prism.BackendId
A backend identifier.
Syntax
class BackendId(IntEnum)
Remarks
The members correspond to the PRISM_BACKEND_* constants of the C API.
Each member is named after its constant without the PRISM_BACKEND_
prefix and has the constant’s value: BackendId.SPEECH_DISPATCHER is
PRISM_BACKEND_SPEECH_DISPATCHER. BackendId.INVALID is 0, which
never identifies a backend.
The identifier of a backend is a hash of its name. It does not change
between releases or platforms, and MAY be stored. Membership of a backend in
a particular registry is reported by prism.Context.exists.
Custom backends and backends loaded from shared libraries have identifiers
that are not members. BackendId(value) accepts any positive integer and,
for such a value, returns a pseudo-member named CUSTOM_ followed by the
value in hexadecimal; the same value always returns the same pseudo-member.
A negative integer, a bool, or a non-integer raises ValueError.
prism.AudioCallback
The type of a function that receives audio from Backend.speak_to_memory.
Syntax
AudioCallback = Callable[[list[float], int, int], None]
Remarks
The function is called with a list of samples, the number of channels,
and the sample rate in hertz. Samples are float values from -1.0 to 1.0,
whatever the backend’s native format. Channels are interleaved. The list MAY
be empty.
The emit function of prism.CustomBackend.speak_to_memory has the
same type.