Documentation
¶
Overview ¶
Package text normalizes written text into a form better suited to text-to-speech: it strips Markdown, expands numbers, currency, percentages, dates, units and acronyms into spoken words, spaces out phone-number digits, and spells email addresses. The transforms are plain string functions; a VoiceFormatter bundles a configurable ordered pipeline of them behind the Filter interface, which the TTS base applies to each sentence before synthesis.
The expansions target English (the num2words "en" conventions): most TTS providers already normalize other languages server-side.
Index ¶
- func EmailToSpeech(text string) string
- func ExpandCurrency(text string) string
- func ExpandPercentages(text string) string
- func ExpandPhoneNumbers(text string) string
- func ExpandUnits(text string) string
- func NormalizeAcronyms(text string) string
- func NormalizeDates(text string) string
- func StripMarkdown(text string) string
- type Filter
- type FormatterOptions
- type Transform
- type VoiceFormatter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EmailToSpeech ¶
EmailToSpeech rewrites email addresses into a spoken form, e.g. "user@example.com" → "user at example dot com".
func ExpandCurrency ¶
ExpandCurrency expands currency amounts into spoken form, e.g. "$42.50" → "forty-two dollars and fifty cents".
func ExpandPercentages ¶
ExpandPercentages expands percentage expressions into spoken form, e.g. "50%" → "fifty percent".
func ExpandPhoneNumbers ¶
ExpandPhoneNumbers spaces out phone-number digits so a synthesizer reads them one by one, e.g. "123-456-7890" → "1 2 3 4 5 6 7 8 9 0". A run bordered by another digit is left alone, so digits inside a longer number are not split.
func ExpandUnits ¶
ExpandUnits expands unit abbreviations after a number into their spoken form, e.g. "5km" → "5 kilometers", "100kph" → "100 kilometers per hour".
func NormalizeAcronyms ¶
NormalizeAcronyms spaces out the letters of an all-caps acronym so each is pronounced individually, e.g. "API" → "A P I".
func NormalizeDates ¶
NormalizeDates expands ISO (YYYY-MM-DD) and US (MM/DD/YYYY or MM-DD-YYYY) dates into spoken form, e.g. "2023-05-10" → "May 10th, two thousand and twenty-three". A string that parses to no valid calendar date is left unchanged.
func StripMarkdown ¶
StripMarkdown removes Markdown formatting symbols that have no spoken equivalent: fenced and inline code, bold/italic markers, ATX headers, blockquote markers and horizontal rules. Link and image syntax is left intact, since the label text is meaningful.
Types ¶
type Filter ¶
Filter transforms text before it is handed to a speech synthesizer. The TTS base calls Filter on each complete sentence just before synthesizing it.
type FormatterOptions ¶
type FormatterOptions struct {
// StripMarkdown removes Markdown formatting symbols.
StripMarkdown bool
// EmailToSpeech spells email addresses ("a@b.com" → "a at b dot com").
EmailToSpeech bool
// ExpandPhoneNumbers spaces out phone-number digits.
ExpandPhoneNumbers bool
// NormalizeDates expands ISO and US dates into spoken form.
NormalizeDates bool
// ExpandCurrency expands currency amounts ("$5" → "five dollars").
ExpandCurrency bool
// ExpandPercentages expands percentages ("50%" → "fifty percent").
ExpandPercentages bool
// ExpandUnits expands unit abbreviations ("5km" → "5 kilometers").
ExpandUnits bool
// NormalizeAcronyms letter-spaces all-caps acronyms ("API" → "A P I").
NormalizeAcronyms bool
// ExpandNumbers spells numeric digits as words. Off by default, since many
// numbers (versions, codes, IDs) read better as digits.
ExpandNumbers bool
// NumberDigitCutoff is passed to ExpandNumbers when it is enabled: numbers
// above it are read digit-by-digit. Zero or less spells every number.
NumberDigitCutoff int
// CustomReplacements are {pattern, replacement} regex rules applied last.
CustomReplacements [][2]string
}
FormatterOptions configures which transforms a VoiceFormatter applies. The zero value enables nothing; use DefaultFormatterOptions for the recommended set and toggle individual fields from there.
func DefaultFormatterOptions ¶
func DefaultFormatterOptions() FormatterOptions
DefaultFormatterOptions returns the recommended set: every transform except ExpandNumbers (which can mangle numbers better left as digits).
type Transform ¶
Transform is a single text-normalization step. All the package's transforms have this shape, so they compose directly and a VoiceFormatter is just an ordered list of them.
func ExpandNumbers ¶
ExpandNumbers returns a transform that expands numbers into spoken form. A number whose whole part exceeds digitCutoff is read digit-by-digit ("2026" → "2 0 2 6"); at or below the cutoff it is spelled as a quantity ("42" → "forty-two"). A digitCutoff of zero or less disables the cutoff, so every number is spelled as a quantity.
func ReplaceText ¶
ReplaceText returns a transform that applies a list of {pattern, replacement} rules in order. Patterns are regular expressions compiled up front, so an invalid pattern returns an error here rather than failing during synthesis.
type VoiceFormatter ¶
type VoiceFormatter struct {
// contains filtered or unexported fields
}
VoiceFormatter applies an ordered pipeline of text transforms, implementing Filter. Build one with NewVoiceFormatter.
func NewVoiceFormatter ¶
func NewVoiceFormatter(opts FormatterOptions) (*VoiceFormatter, error)
NewVoiceFormatter builds a VoiceFormatter from opts. The transforms run in a deliberate order — structural cleanup, then language expansions, then user replacements — chosen so earlier steps do not hide patterns later ones match (email before phone and acronyms; units before acronyms). It returns an error only if a CustomReplacements pattern fails to compile.
func (*VoiceFormatter) Filter ¶
func (f *VoiceFormatter) Filter(text string) string
Filter applies every configured transform to text in order.
Source Files