speechXml module

Utilities for converting NVDA speech sequences to XML and vice versa. Several synthesizers accept XML, either SSML or their own schemas. L{SpeechXmlConverter} is the base class for conversion to XML. You can subclass this to support specific XML schemas. L{SsmlConverter} is an implementation for conversion to SSML.

speechXml._buildInvalidXmlRegexp()
speechXml.toXmlLang(nvdaLang: str) str

Convert an NVDA language to an XML language.

speechXml.toNvdaLang(xmlLang: str) str

Convert an XML language to an NVDA language.

class speechXml.EncloseAllCommand(tag, attrs)

Bases: tuple

An XMLBalancer command to enclose the entire output in a tag. This must be the first command.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('tag', 'attrs')
classmethod _make(iterable)

Make a new EncloseAllCommand object from a sequence or iterable

_replace(**kwds)

Return a new EncloseAllCommand object replacing specified fields with new values

attrs

Alias for field number 1

tag

Alias for field number 0

class speechXml.SetAttrCommand(tag, attr, val)

Bases: tuple

An XMLBalancer command to set a tag attribute to a given value for subsequent output. This attribute will be output with this value until a L{DelAttrCommand}.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('tag', 'attr', 'val')
classmethod _make(iterable)

Make a new SetAttrCommand object from a sequence or iterable

_replace(**kwds)

Return a new SetAttrCommand object replacing specified fields with new values

attr

Alias for field number 1

tag

Alias for field number 0

val

Alias for field number 2

class speechXml.DelAttrCommand(tag, attr)

Bases: tuple

An XmlBalancer command to remove a tag attribute for subsequent output. If the tag has no remaining attributes, it will not be produced henceforth.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('tag', 'attr')
classmethod _make(iterable)

Make a new DelAttrCommand object from a sequence or iterable

_replace(**kwds)

Return a new DelAttrCommand object replacing specified fields with new values

attr

Alias for field number 1

tag

Alias for field number 0

class speechXml.EncloseTextCommand(tag, attrs)

Bases: tuple

An XmlBalancer command to directly enclose all text henceforth in a tag. That is, the tag must always be the inner most tag. This will occur until a L{StopEnclosingTextCommand}.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('tag', 'attrs')
classmethod _make(iterable)

Make a new EncloseTextCommand object from a sequence or iterable

_replace(**kwds)

Return a new EncloseTextCommand object replacing specified fields with new values

attrs

Alias for field number 1

tag

Alias for field number 0

class speechXml.StopEnclosingTextCommand

Bases: tuple

An XMLBalancer command to stop directly enclosing text henceforth in a tag.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ()
classmethod _make(iterable)

Make a new StopEnclosingTextCommand object from a sequence or iterable

_replace(**kwds)

Return a new StopEnclosingTextCommand object replacing specified fields with new values

class speechXml.StandAloneTagCommand(tag, attrs, content)

Bases: tuple

An XmlBalancer command to output a stand-alone tag. That is, it will not enclose subsequent output.

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('tag', 'attrs', 'content')
classmethod _make(iterable)

Make a new StandAloneTagCommand object from a sequence or iterable

_replace(**kwds)

Return a new StandAloneTagCommand object replacing specified fields with new values

attrs

Alias for field number 1

content

Alias for field number 2

tag

Alias for field number 0

speechXml._escapeXml(text)
class speechXml.XmlBalancer

Bases: object

Generates balanced XML given a set of commands. NVDA speech sequences are linear, but XML is hierarchical, which makes conversion challenging. For example, a speech sequence might change the pitch, then change the volume, then reset the pitch to default. In XML, resetting to default generally requires closing the tag, but that also requires closing the outer tag. This class transparently handles these issues, balancing the XML as appropriate. To use, create an instance and call the L{generateXml} method.

_out

The converted output as it is built.

_enclosingAllTags

A stack of open tags which enclose the entire output.

_tagsChanged

Whether any tags have changed since last time they were output.

_openTags

A stack of currently open tags (excluding tags which enclose the entire output).

_tags

Current tags and their attributes.

_tagEnclosingText

A tag (and its attributes) which should directly enclose all text henceforth.

_text(text)
_openTag(tag, attrs, empty=False)
_closeTag(tag)
_setAttr(tag, attr, val)
_delAttr(tag, attr)
_outputTags()
generateXml(commands) str

Generate XML from a sequence of balancer commands and text.

class speechXml.SpeechXmlConverter

Bases: object

Base class for conversion of NVDA speech sequences to XML. This class converts an NVDA speech sequence into XmlBalancer commands which can then be passed to L{XmlBalancer} to produce correct XML.

The L{generateBalancerCommands} method takes a speech sequence and produces corresponding XmlBalancer commands. For convenience, callers can call L{convertToXml} with a speech sequence to generate XML using L{XmlBalancer}.

Subclasses implement specific XML schemas by implementing methods which convert each speech command. The method for a speech command should be named with the prefix “convert” followed by the command’s class name. For example, the handler for C{IndexCommand} should be named C{convertIndexCommand}. These methods receive the L{SpeechCommand} instance as their only argument. They should return an appropriate XmlBalancer command. Subclasses may wish to extend L{generateBalancerCommands} to produce additional XmlBalancer commands at the start or end; e.g. to add an L{EncloseAllCommand} at the start.

generateBalancerCommands(speechSequence)

Generate appropriate XmlBalancer commands for a given speech sequence. @rtype: generator

convertToXml(speechSequence)

Convenience method to convert a speech sequence to XML using L{XmlBalancer}.

class speechXml.SsmlConverter(defaultLanguage: str)

Bases: SpeechXmlConverter

Converts an NVDA speech sequence to SSML.

generateBalancerCommands(speechSequence)

Generate appropriate XmlBalancer commands for a given speech sequence. @rtype: generator

convertIndexCommand(command)
convertCharacterModeCommand(command)
convertLangChangeCommand(command: LangChangeCommand) SetAttrCommand
convertBreakCommand(command)
_convertProsody(command, attr)
convertPitchCommand(command)
convertRateCommand(command)
convertVolumeCommand(command)
convertPhonemeCommand(command)
class speechXml.SpeechXmlParser

Bases: object

Base class for parsing of NVDA speech sequences from XML. This class converts XML to an NVDA speech sequence.

Callers can call L{convertFromXml} with XML to generate a speech sequence.

Subclasses implement specific XML schemas by implementing generators which convert each XML tag supported. The method for a tag should be named with the prefix “parse” followed by the tag. For example, the handler for <volume /> should be named C{parseVolume}. These generators receive an optional dictionary containing the attributes and values. When the attributes value is None, it is a closing tag. They should yield one or more appropriate SPeechCommand instances.

_speechSequence: list[SpeechCommand | str]
_elementHandler(tagName: str, attrs: dict | None = None)
convertFromXml(xml: str) list[SpeechCommand | str]

Convert XML to a speech sequence.

class speechXml.SsmlParser(markCallback: Callable[[str], None] | None = None)

Bases: SpeechXmlParser

Parses SSML into an NVDA speech sequence.

Constructor.

Parameters:

markCallback – An optional callback called for every mark command in the SSML. The mark command in the SSML will be translated to a CallbackCommand instance.

parseSayAs(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
parseVoice(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
parseBreak(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
_cachedProsodyAttrs: list[dict]
parseProsody(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
parseSpeak(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
parseMark(attrs: dict[str, str] | None) Generator[SpeechCommand, None, None]
convertFromXml(xml: str) list[SpeechCommand | str]

Convert XML to a speech sequence.