mavttsd: a pronunciation dictionary, so she says the names right (V-458)

piper reads a Russian sentence with a Russian voice, and a Latin service id
inside it comes out spelled, mangled or read as if it were a Russian word:
"Vikunja", "SearXNG", "homesrv". The lever available is the text, so the
dictionary maps a name to how it should be spelled for the voice to say it,
and mavttsd applies it at the last edge before piper — every caller's text
passes through that one point, and nothing upstream has to know how a name
sounds.

Data, not code. deploy/tts-lexicon.json ships 29 names; adding one needs a
restart of mavttsd and no rebuild of the daemon that produced the text. Off
unless -lexicon is set, like every other optional capability, and a path that
is set and unreadable stops startup — saying names wrong in silence is the
failure it exists to remove.

Two details worth keeping: the alternation is sorted longest-first, or "Home
Assistant" reads as "Хоум Assistant"; and the boundaries are written out
rather than left to \b, which is ASCII-only and never fires next to a
Cyrillic letter.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

cmd/mavttsd/main.go

@@ -23,6 +23,7 @@ import (
 	"syscall"
 
 	"github.com/kami/maven/internal/audio"
+	"github.com/kami/maven/internal/tts"
 	"github.com/kami/maven/internal/worker"
 )
 
@@ -39,15 +40,27 @@ func run(args []string) error {
 	model := flag.String("model", "", "path to piper onnx model file")
 	espeakData := flag.String("espeak_data", "", "path to espeak-ng data directory")
 	tashkeelModel := flag.String("tashkeel_model", "", "path to libtashkeel onnx model")
+	lexiconPath := flag.String("lexicon", "", "path to the pronunciation dictionary (json, name to spelling)")
 
 	flag.CommandLine.Parse(args)
 
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP)
 	defer stop()
 
+	// Read before the handler is built: a dictionary he asked for and that
+	// cannot be read is a startup failure, not a warning. Saying names wrong
+	// in silence is the thing it exists to stop.
+	lex, err := tts.LoadLexicon(*lexiconPath)
+	if err != nil {
+		return err
+	}
+	if lex.Size() > 0 {
+		log.Printf("mavttsd: pronunciation dictionary: %d names from %s", lex.Size(), *lexiconPath)
+	}
+
 	var s worker.Synthesizer
 	if *piperBin != "" && *model != "" {
-		s = newPiperHandler(*piperBin, *model, *espeakData, *tashkeelModel)
+		s = newPiperHandler(*piperBin, *model, *espeakData, *tashkeelModel, lex)
 		log.Printf("mavttsd: using piper tts (%s, model=%s)", *piperBin, *model)
 	} else {
 		log.Printf("mavttsd: no piper/model specified, using stub handler")

cmd/mavttsd/main_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/kami/maven/internal/audio"
+	"github.com/kami/maven/internal/tts"
 	"github.com/kami/maven/internal/worker"
 )
 
@@ -117,3 +118,18 @@ func abs(n int) int {
 	}
 	return n
 }
+
+// The dictionary that ships in deploy/ must parse and must be non-empty. It is
+// data, so nothing else would catch a trailing comma before the voice did.
+func TestShippedLexiconLoads(t *testing.T) {
+	lex, err := tts.LoadLexicon(filepath.Join("..", "..", "deploy", "tts-lexicon.json"))
+	if err != nil {
+		t.Fatalf("deploy/tts-lexicon.json: %v", err)
+	}
+	if lex.Size() < 10 {
+		t.Errorf("shipped dictionary holds %d names, want the full list", lex.Size())
+	}
+	if got := lex.Apply("задача в Vikunja"); got == "задача в Vikunja" {
+		t.Error("the shipped dictionary did not rewrite a name it lists")
+	}
+}

cmd/mavttsd/piper_handler.go

@@ -9,6 +9,7 @@ import (
 	"os/exec"
 
 	"github.com/kami/maven/internal/audio"
+	"github.com/kami/maven/internal/tts"
 	"github.com/kami/maven/internal/worker"
 )
 
@@ -18,15 +19,20 @@ type piperHandler struct {
 	configPath    string
 	espeakData    string
 	tashkeelModel string
+	// lexicon rewrites service ids and Latin names into the spelling the
+	// Russian voice reads correctly (Vikunja #458). Nil-safe: an unconfigured
+	// dictionary rewrites nothing.
+	lexicon *tts.Lexicon
 }
 
-func newPiperHandler(piperPath, modelPath, espeakData, tashkeelModel string) *piperHandler {
+func newPiperHandler(piperPath, modelPath, espeakData, tashkeelModel string, lexicon *tts.Lexicon) *piperHandler {
 	return &piperHandler{
 		piperPath:     piperPath,
 		modelPath:     modelPath,
 		configPath:    modelPath + ".json",
 		espeakData:    espeakData,
 		tashkeelModel: tashkeelModel,
+		lexicon:       lexicon,
 	}
 }
 
@@ -66,7 +72,14 @@ func (h *piperHandler) Synthesize(ctx context.Context, req worker.SynthesizeReq)
 		return worker.SynthesizeResp{}, fmt.Errorf("piper: start: %w", err)
 	}
 
-	if _, err := io.WriteString(stdin, req.Text); err != nil {
+	// The dictionary is applied here, at the last edge before the voice: every
+	// caller's text passes through this one point, and nothing upstream has to
+	// know how a name is spelled out loud.
+	text := req.Text
+	if h.lexicon != nil {
+		text = h.lexicon.Apply(text)
+	}
+	if _, err := io.WriteString(stdin, text); err != nil {
 		stdin.Close()
 		stdout.Close()
 		_ = cmd.Wait()