# TTS normalization patterns Text-to-speech models often need their input normalized before tokenization: numbers, currencies, dates and symbols spelled out, punctuation mapped, spacing fixed. The exact rules are model-specific (they must match what the model was trained on), so they live in the model's `tts` task template rather than in C++. Jinja has no regex support, and exposing `std::regex` / Python `re` would not help: the two differ in many details (`\d`, `\w`, `\b`, lookbehind, case folding, backtracking limits), so a template could give different results in llama.cpp and in Python. Instead, task templates get two functions with a small matching language whose semantics are defined here: - `tts_norm_scan(text, rules)`: split text into matched and unmatched segments - `tts_norm_sub(text, pattern, repl)`: replace every match A third function, `tts_dict(name, key)`, gives the template access to dictionaries stored in the model (e.g. a pronunciation lexicon). A fourth one, `tts_g2p(word)`, gives the pronunciation of a word by the letter-to-sound model of the mmproj, when the caller provides one (see below). Implementations: - C++: [common/chat-tts-norm.cpp](../common/chat-tts-norm.cpp), injected into task templates by `common_chat_template_render()` in [common/chat.cpp](../common/chat.cpp). They are not available to chat templates. - Python reference: [scripts/chat_tts_norm.py](../scripts/chat_tts_norm.py), for use with `jinja2` (`env.globals["tts_norm_scan"] = chat_tts_norm.tts_norm_scan`) - Both are checked against each other by `tests/test-jinja.cpp` (`test-jinja -py "tts norm patterns.*"`) ## Example ```jinja {%- for s in tts_norm_scan(text, [ ['money', '%$(%d+)(?:%.(%d%d))?'], ['percent', '(%d+)%%'], ['time', '(%d%d?):(%d%d)(?!%d)'], ['neg', '(?.keys`, sorted by the UTF-8 bytes of the key, and `tokenizer.tts_dict..values`. A value is a JSON document (string, number, list, object, ...) and is returned decoded. `GGUFWriter.add_tts_dicts(dicts)` writes all of this. ### `tts_g2p(word)` Pronunciation of `word` by a letter-to-sound model, as phonemes separated by spaces, in the notation of the model (e.g. CMUdict with stress digits for tiny-voca), or `none`. The template converts it to the symbols of the model. It is `none` when the model has no letter-to-sound model, or when the caller gives none: `common_chat_get_tts_prompt()` takes it as an optional callback, `llama-tts` and `llama-server` pass `mtmd_gen_audio_g2p()`. A template must keep working without it, e.g. by spelling the word. ```jinja {%- set g = tts_g2p(word) -%} {%- if g is none -%}{{ spell(word) }}{%- else -%}{{ from_cmudict(word, g.split(' ')) }}{%- endif -%} ``` There is no Python reference for it: a test passes its own function (`env.globals["tts_g2p"]`). ## Pattern syntax Patterns operate on Unicode codepoints. Invalid UTF-8 bytes (C++ only) are seen as U+FFFD, one per byte, and preserved in the output. | syntax | meaning | |---|---| | `x` | the literal codepoint `x` | | `%x` | escape: `%` followed by any non-alphanumeric codepoint is that literal codepoint (`%.`, `%$`, `%%`, `%(`, ...) | | `.` | any codepoint, including newlines | | `%d` `%s` `%p` `%a` `%w` `%u` `%l` `%h` `%c` | character classes, see below; the uppercase form (`%D`, ...) is the negation | | `[...]` | set: literal codepoints, ranges `a-z`, classes `%d`; `[^...]` is the negation | | `(...)` | capture group | | `(?:...)` | group without capture | | `a\|b` | ordered alternation | | `?` `*` `+` `{m}` `{m,}` `{m,n}` | quantifiers, greedy and possessive; `m`, `n` up to 1000 | | `^` `$` | start / end of the whole text | | `%b` | boundary: between a `%w` codepoint and a non-`%w` codepoint (the edges of the text count as non-`%w`) | | `(?=...)` `(?!...)` | lookahead, positive / negative | | `(?<=c)` `(?