text

type Aggregation ¶ added in v0.1.0

type Aggregation struct {
	// Text is the aggregated text.
	Text string
	// Type is how it was aggregated.
	Type frames.AggregationType
	// RawText is the text this unit was cut from, delimiters and all, set when
	// the unit came from a matched pattern such as a code block. Empty for an
	// ordinary aggregation, where Text is already the written form.
	RawText string
}

Aggregation is a run of text an aggregator has completed, and how it was aggregated.

func (a Aggregation) Original() string

type Aggregator ¶ added in v0.1.0

type Aggregator interface {
	// Type is how this aggregator groups text. A caller reads it to know what to
	// expect before any text has been aggregated: grouping by token, say, means
	// no unit ever completes a sentence.
	Type() frames.AggregationType
	// Aggregate folds text into the buffer and returns every unit it completed.
	Aggregate(text string) []Aggregation
	// Flush returns whatever is left in the buffer, for the end of a response.
	Flush() (Aggregation, bool)
	// Reset clears the buffer.
	Reset()
}

Aggregator groups streamed text into the units a synthesizer is given.

type Filter ¶

type Filter interface {
	Filter(text string) string
}

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() FormatterOptions

type InterruptibleFilter ¶ added in v0.1.0

type InterruptibleFilter interface {
	Filter
	HandleInterruption()
	ResetInterruption()
}

InterruptibleFilter is a Filter that carries state between calls and needs to be told when speech is cut off. Markdown structures such as code blocks and tables arrive split across several sentences, so a filter tracking one has to abandon it when the text that would have closed it never arrives. The TTS base calls HandleInterruption on an interruption, and ResetInterruption before filtering resumes.

type MarkdownFilter ¶ added in v0.1.0

type MarkdownFilter struct {
	// contains filtered or unexported fields
}

MarkdownFilter converts Markdown to plain text for speech, preserving the structure around it: leading and trailing spaces survive, so text streamed word by word still joins up, and numbered list markers are spoken.

It is stateful. Code blocks and tables arrive split across several calls, so the filter remembers that it is inside one; an interruption abandons whatever was half-read. Build one with NewMarkdownFilter.

func NewMarkdownFilter(opts MarkdownFilterOptions) *MarkdownFilter

func (f *MarkdownFilter) Filter(text string) string

func (f *MarkdownFilter) HandleInterruption()

func (f *MarkdownFilter) ResetInterruption()

type MarkdownFilterOptions ¶ added in v0.1.0

type MarkdownFilterOptions struct {
	// Enabled turns the filter on. When false, Filter returns its input as
	// written, which is the switch to reach for to see what the model actually
	// produced.
	Enabled bool
	// FilterCode drops fenced code blocks instead of speaking their contents.
	// Code blocks span several chunks of streamed text, so the filter tracks
	// whether it is inside one across calls.
	FilterCode bool
	// FilterTables drops table contents. It also turns on table parsing, without
	// which a table is only ever a run of pipes and dashes.
	//
	// Pair it with FilterRepeatedSequences off. That rule runs first and flattens
	// a delimiter row of five or more dashes ("|--------|") to bare pipes, and a
	// table is not recognized without a well-formed delimiter row. A short row
	// ("|---|") is under the threshold and comes through either way.
	FilterTables bool
	// FilterRepeatedSequences drops a run of five or more of the same character,
	// the shape of an ASCII rule or a keyboard smash rather than of speech.
	FilterRepeatedSequences bool
}

MarkdownFilterOptions configures a MarkdownFilter. The zero value filters nothing at all (Enabled is false); use DefaultMarkdownFilterOptions for the recommended set and toggle individual fields from there.

func DefaultMarkdownFilterOptions() MarkdownFilterOptions

type MatchAction ¶ added in v0.1.0

type MatchAction string

MatchAction is what an aggregator does with a pattern once both its delimiters have arrived.

const (
	// MatchRemove drops the match and its delimiters from the text. Aggregation
	// carries on as though the run had never been there, which is what a model
	// asked to mark up its own reasoning wants: the markup is read by the
	// handler and never spoken.
	MatchRemove MatchAction = "remove"
	// MatchKeep drops the delimiters and keeps what was between them, which then
	// aggregates as ordinary text. A handler still sees the match, so this is
	// how to be told about a run without changing what is spoken.
	MatchKeep MatchAction = "keep"
	// MatchAggregate drops the delimiters and returns what was between them as a
	// unit of its own, whole rather than cut into sentences. Any text before the
	// opening delimiter is returned first, complete sentence or not.
	MatchAggregate MatchAction = "aggregate"
)

type Part ¶ added in v0.1.0

type Part struct {
	// Text is the piece itself.
	Text string
	// IncludesInterPartSpaces reports whether the spacing that separates this
	// piece from the ones around it is already part of Text. A model streaming a
	// sentence sends " world" with the space; a stream of spoken words sends
	// "world" without one, and the join has to supply it.
	IncludesInterPartSpaces bool
}

Part is one piece of text waiting to be joined into a whole by Concatenate.

type PatternHandler ¶ added in v0.1.0

type PatternHandler func(match Aggregation)

PatternHandler is called with each completed match of the pattern it was registered for.

type PatternPairAggregator ¶ added in v0.1.0

type PatternPairAggregator struct {
	*SimpleAggregator
	// contains filtered or unexported fields
}

PatternPairAggregator groups text into sentences the way SimpleAggregator does, and additionally recognizes runs delimited by a registered pair.

It is for a model whose output carries structure the speech should not: a reasoning block to be dropped, a code block to be spoken as one unit rather than cut at every period, a speaker tag that should switch voices. A handler registered for a pattern is called as each match completes, and the action the pattern was registered with decides whether what matched is dropped, kept as ordinary text, or returned as a unit of its own.

A pattern split across several pieces of arriving text is still recognized.

func NewPatternPairAggregator(
	aggregateBy frames.AggregationType, tokenizer SentenceTokenizer,
) *PatternPairAggregator

func (a *PatternPairAggregator) AddPattern(
	typ frames.AggregationType, start, end string, action MatchAction,
) error

func (a *PatternPairAggregator) Aggregate(text string) []Aggregation

func (a *PatternPairAggregator) Flush() (Aggregation, bool)

func (a *PatternPairAggregator) OnPatternMatch(typ frames.AggregationType, h PatternHandler)

func (a *PatternPairAggregator) Reset()

func (a *PatternPairAggregator) Text() Aggregation

type PunktTokenizer ¶ added in v0.1.0

type PunktTokenizer struct {
	// contains filtered or unexported fields
}

PunktTokenizer finds sentence boundaries with the Punkt algorithm, an unsupervised model trained per language. Punkt is what tells a sentence ending from an abbreviation: it keeps "Dr. Smith is here." and "M. Dupont est la." whole rather than breaking after the title.

func NewPunkt(training []byte) (*PunktTokenizer, error)

func NewPunktEnglish() (*PunktTokenizer, error)

func (p *PunktTokenizer) MatchEndOfSentence(text string) int

type SentenceTokenizer ¶ added in v0.1.0

type SentenceTokenizer interface {
	// MatchEndOfSentence returns the byte offset just past the end of the first
	// complete sentence in text, or 0 when text does not yet hold one.
	MatchEndOfSentence(text string) int
}

SentenceTokenizer finds sentence boundaries in a stream of text.

This interface has no counterpart upstream, where the boundary function is called directly. It exists so a caller can supply a different segmenter, or avoid carrying a trained model, without the rest of the pipeline changing. The default is Punkt, which is what the behavior is defined against.

type SimpleAggregator ¶ added in v0.1.0

type SimpleAggregator struct {
	// contains filtered or unexported fields
}

SimpleAggregator groups text into sentences, or passes each token straight through when aggregating by token.

A sentence boundary is confirmed by lookahead: the mark that could end a sentence is not acted on until the first non-whitespace character after it has arrived. That is what tells "$29." apart from "$29. Next", since only the character following the period says whether the text ended there. Whitespace alone says nothing, because it appears in both.

func NewSimpleAggregator(aggregateBy frames.AggregationType, tokenizer SentenceTokenizer) *SimpleAggregator

func NewTokenAggregator() *SimpleAggregator

func (a *SimpleAggregator) Aggregate(text string) []Aggregation

func (a *SimpleAggregator) Buffer() string

func (a *SimpleAggregator) Flush() (Aggregation, bool)

func (a *SimpleAggregator) Reset()

func (a *SimpleAggregator) Text() Aggregation

func (a *SimpleAggregator) Type() frames.AggregationType

type SkipTagsAggregator ¶ added in v0.1.0

type SkipTagsAggregator struct {
	*SimpleAggregator
	// contains filtered or unexported fields
}

SkipTagsAggregator groups text into sentences the way SimpleAggregator does, except between a pair of tags, where it never looks for a sentence boundary.

It is for text carrying delimited runs that must reach the synthesizer whole. A pronunciation tag such as <spell>A.B.C.</spell> is full of periods that end no sentence, and splitting it would hand the synthesizer half a tag. Once a start tag is seen the aggregator keeps accumulating unconditionally until the matching end tag arrives, whatever punctuation it passes on the way.

The tags themselves are pass-through markers. They are not removed, because the synthesizer is what interprets them.

func NewSkipTagsAggregator(
	aggregateBy frames.AggregationType, tokenizer SentenceTokenizer, tags []StartEndTags,
) *SkipTagsAggregator

func (a *SkipTagsAggregator) Aggregate(text string) []Aggregation

func (a *SkipTagsAggregator) Flush() (Aggregation, bool)

func (a *SkipTagsAggregator) Reset()

func (a *SkipTagsAggregator) Text() Aggregation

type StartEndTags ¶ added in v0.1.0

type StartEndTags struct {
	// Start opens the run.
	Start string
	// End closes it.
	End string
}

StartEndTags is a pair of delimiters marking a run of text: an opening tag and the closing tag that ends it.

func ParseStartEndTags(
	text string, tags []StartEndTags, current *StartEndTags, index int,
) (*StartEndTags, int)

type Transform ¶

type Transform func(text string) string

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(digitCutoff int) Transform

func ReplaceText(rules [][2]string) (Transform, error)

func (t Transform) Filter(text string) string

type VoiceFormatter ¶

type VoiceFormatter struct {
	// contains filtered or unexported fields
}

VoiceFormatter applies an ordered pipeline of text transforms. Build one with NewVoiceFormatter and register it with the TTS base's SetTextTransformers, against frames.AnyAggregation to reshape every unit or against one aggregation type to reshape only those.

It belongs among the transforms rather than the text filters because what it does is for the provider alone: an acronym letter-spaced so it is spelled out, an amount written in words. The conversation should record what the model wrote, not the shape the synthesizer needed it in.

func NewVoiceFormatter(opts FormatterOptions) (*VoiceFormatter, error)

func (f *VoiceFormatter) Transform(
	_ context.Context, text string, _ frames.AggregationType,
) (string, error)