speechtext

README

go-speechtext

Deterministic Markdown and HTML cleanup for text-to-speech in Go. It removes formatting markers while keeping visible words, headings, list items, link labels, and HTML text. Fenced, indented, and HTML preformatted code blocks are omitted by default. It makes no network or model calls.

spoken := speechtext.Clean("## Summary\n**Ready** to ship.")
// "Summary: Ready to ship."

Use a hook when an application can describe special content more usefully:

formatter := speechtext.New(speechtext.Options{
    Parallelism: 3,
    Hooks: map[speechtext.Kind]speechtext.Hook{
        speechtext.KindCode: func(ctx context.Context, block speechtext.Block) (string, error) {
            // block.Language and block.Content are the original code block.
            return describeCode(ctx, block.Language, block.Content)
        },
    },
})
spoken, err := formatter.Format(ctx, markdown)

Hooks for separate blocks may run in parallel; their results are assembled in source order. Hooks must be concurrency-safe. A hook may return an empty string to omit its block. KindHTML can override the built-in visible-text extraction for HTML blocks. Hook errors return no partial transcript. This is a text cleanup tool, not a semantic summarizer: it does not invent descriptions for code, formulas, or structured data.

MIT licensed.

Documentation

Overview

Package speechtext turns Markdown and HTML into plain, spoken text. Formatting is deterministic. Callers may provide hooks for content that needs an application-specific description, such as a fenced code block.

Index

• func Clean(input string) string
• type Block
• type Formatter
  • func New(options Options) *Formatter
  • func (f *Formatter) Format(ctx context.Context, input string) (string, error)
• type Hook
• type Kind
• type Options

Functions

func Clean

func Clean(input string) string

Clean performs deterministic formatting with no hooks or external calls. It is suitable for a latency-sensitive text-to-speech path.

Types

type Block

type Block struct {
	Kind     Kind
	Content  string
	Language string
}

Block is the original content passed to a hook. Language is set for fenced code blocks when the fence has an info string.

type Formatter

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

Formatter is safe for concurrent Format calls. Configure its hooks before constructing it; New copies the hooks map.

func New

func New(options Options) *Formatter

New constructs a formatter with optional block hooks.

func (*Formatter) Format

func (f *Formatter) Format(ctx context.Context, input string) (string, error)

Format removes presentation syntax, runs optional hooks on independent blocks, and assembles the results in source order. If a hook fails, no partial output is returned. The error names the first failing block in source order, regardless of hook completion order.

type Hook

type Hook func(context.Context, Block) (string, error)

Hook replaces one block with spoken text. An empty result omits the block. Hooks may run concurrently and must be safe for concurrent calls. The returned text is treated as plain text, never parsed as Markdown or HTML.

type Kind

type Kind string

Kind identifies a self-contained block that can be handled by a hook.

const (
	KindCode Kind = "code" // Fenced and indented code blocks.
	KindHTML Kind = "html" // Block-level HTML.
)

type Options

type Options struct {
	Hooks       map[Kind]Hook
	Parallelism int
}

Options configures optional hooks. Without a code hook, code blocks are omitted. Without an HTML hook, HTML blocks are converted to visible text. Parallelism limits simultaneous hook calls; zero uses four workers.