speaker_helper.speech_text module
What the voice says where the page shows notation.
A page and a narration are not the same text, and three things on a page have no spoken form of their own:
Mathematics.
\(R = T_{BA} \circ T_{AB}\)is a sentence a reader sees at a glance and a speech engine spells out as “backslash, open parenthesis, R equals T underscore…”. Read aloud it has to become English, or French, or whatever the page is written in.Footnote markers. Handled by whoever walks the page, not here: telling a reference superscript from an exponent needs the markup, and this module is given a string. The rule that works is by content — a
<sup>whose entire content is a number (bare,[1],(1)) is a reference and goes unsaid. Its documented limit is thatx<sup>2</sup>is taken for one.Pronunciation overrides, which belong to whoever assembles the segments.
The page’s own text is never changed. This produces a second string, the
one handed to the engine, while the cue keeps the page’s words — so a
read-along still highlights what the page shows, and the narration still
says something a person would say. That pair is
Segment’s text and say, and this
module is how the second is usually derived from the first.
Why it lives in the voice package rather than beside a site generator: “what does a voice say where the page shows notation” is a question about speech, not about documents. It was written for a blog and is not specific to one — it needs no model, no network and no optional extra, only the language the text is written in.
Scope, stated plainly. This is not a LaTeX parser and does not try to be. It covers the notation that appears in prose: relations, the common operators and functions, Greek, subscripts, powers, roots and fractions. Anything it does not know loses its backslash and is spoken as a word, which is wrong far less often than spelling the command out.
- speaker_helper.speech_text.NARRATE_ABOVE: int = 6
Above this, a formula is narrated rather than transliterated — when a narrator is available. Six, because five is R = T_{BA} circ T_{AB} — one relation, one operator, two indices — and its mechanical reading (“R equals T B A composed with T A B”) is exactly what a person would say. A nested fraction of sums scores nine, and there the mechanical reading is sound with no meaning in it.
- exception speaker_helper.speech_text.SpeechMismatch[source]
Bases:
ValueErrorRaised when a language has no vocabulary rather than serving English.
- speaker_helper.speech_text.complexity(latex)[source]
How much structure a formula carries.
A rough count of the things that make a formula hard to follow by ear: commands, relations, nesting, sub- and superscripts.
Rscores zero and needs no help; a nested fraction of sums scores high and a symbol-by-symbol reading of it is sound without meaning.
- speaker_helper.speech_text.speak_math(latex, lang='en')[source]
One formula, as a person would read it out.
R = T_{BA} \circ T_{AB}becomes “R equals T B A composed with T A B”.Subscripts are read as their own letters rather than announced: “T A B” is how somebody says that at a blackboard, and “T subscript A B” is how nobody does. Powers keep their announcement, because “x 2” and “x squared” are different claims.
- speaker_helper.speech_text.speakable(text, lang='en', *, narrator=None)[source]
The sentence as the voice should say it.
Only the notation changes; every other word is the page’s.
narratoris an optional(latex, lang) -> str | None. It is asked about formulas whosecomplexity()is aboveNARRATE_ABOVE, and its answer is used when it gives one. This is the difference between spelling a formula and reading it: “the sum over i of x i, all over n” is a transliteration, “the average of the x values” is a sentence, and only the second survives being heard once with no page in front of you.It stays an injected callable rather than an import so this module needs no model, no network and no optional extra to be used or tested. Without one, every formula gets the deterministic reading — which is the baseline, not a degraded mode.