A phonetic sequence encoding Θ

Talk is a phonetic front end and tokenization layer for speech and language models. Its machine encoding turns text or IPA into one integer per sound, so a model gets a finite, normalized phone vocabulary instead of raw IPA or byte-pair fragments that split a pronunciation across several tokens. If you build TTS, ASR, G2P, or any multilingual pipeline that has to reason about how words sound, this gives you one clean token per phone that converts losslessly to and from IPA, plus syllabification for free.

It is also a readable, keyboard-typable romanization. The notation is called tone, and it uses the Latin script with diacritics to encode most of Earth's natural language features, enough that you can write every language in the same Latin-oriented system and land close to a realistic pronunciation, including nasalized vowels, tense consonants, clicks, and tones. It reads like the pronunciation guides people already know, so a non-linguist can get the gist without special training.

There are two NOTATIONS and one machine form:

• tone: the ASCII notation, for writing in a text editor without fancy symbols. Deliberately coarser than IPA.
• ipa: read and written losslessly, for anything that has to give back exactly what a source said.
• machine: one integer per sound, for compact tokenization. Useful for AI models, indexes and lookups.

A note on names: the LIBRARY is talk, the NOTATION it defines is tone. Older docs use "talk" for both.

Talk is not trying to compete with or replace IPA. It is for writing pronunciations in plain ASCII and tokenizing them in a standard way for tools like NLP, AI, and databases. It aims for about 95% accuracy, which is plenty for a tokenizer or a learner, and it speaks IPA fluently for the cases where you need the last 5%.

Implementations of Talk, one per language. Each converts between IPA, tone, and the machine (token) encoding, carries the tiered codec, and splits words into syllables.

All three are verified against ONE fixture, deck/rust/test/fixture/parity.json, which is the TypeScript build's own output over every enumerated sound. The ports read it directly, so agreement is checked against a shared answer rather than against hand-written cases each port could get wrong in the same way.

Real words, with their IPA from the ClueSurf export, the talk spelling, and the syllable split. They are chosen for how much of the phonetic space they use: the vowelless words of Bella Coola, the ejectives of Georgian and Archi, the clicks of Hadza, the tone contours of Burmese and Vietnamese, the stød of Danish.

A sound is a BASE plus, when it has any, one bracketed run of MODIFIERS. kʷʰ is k<wh>: one pair of brackets however many marks the run holds, and the marks in the order of the modifier table below, so a set of modifiers has exactly one spelling.

Reading is looser than writing. The parser takes the marks in any order inside the brackets, the same way it takes n̪̥ and n̥̪ for one sound, and gives back the canonical form.

Two rules keep the notation usable elsewhere. Every spelling is ASCII and survives a URL unencoded, so a sound can be a path segment. And (, ), [, ], { and } never appear, which leaves them free for the regular expressions a search surface needs.

A mark listed before base is a different sound from the same mark after it: ʰk is pre-aspirated and kʰ post-aspirated, so they never share a spelling.

The IPA consonant chart, in chart order: by place across and manner down, the order the chart itself uses. Generated by pnpm exec tsx code/make/readme-tables.ts from base/phones.json and base/chart/consonant-symbols.csv, so it cannot drift from the data.

A dash in the X-SAMPA column means the symbol has none. X-SAMPA is an ASCII scheme from the 1990s and eight of these were added to the IPA afterwards, so no ASCII spelling was ever assigned.

Vowels are built from ten base letters, each with a $ and a ~ variant. The letter says roughly where the vowel sits and the marker picks among its neighbours, so the whole inventory is ten rows rather than a chart to memorise.

u has no $ variant: the sound that would fill it is ~u (ʉ).

A modifier goes inside angle brackets after the base it belongs to, and all of a sound's modifiers share ONE pair: kʷʰ is k<wh>, not k<w><h>. The binder shares that pair too, so an aspirated affricate is tx<hB>.

A modifier written BEFORE the base modifies what follows, in its own brackets, so ʰk is <h>k and kʰ is k<h>. Those are different sounds.

Order is canonical on the way out and free on the way in. combine sorts by slot, so one set of modifiers has exactly one spelling, while k<hw> and k<wh> both parse.

Where the sound is made, and what the lips do.

How the air gets out.

What the larynx does.

How long it is held, and whether it carries a syllable.

Pitch and prominence.

Talk splits a word into syllables, each a run of onset, nucleus and coda clusters. IPA and X-SAMPA hand you symbols and stop there, so this comes built in, which is what the text-to-speech, speech-recognition and language-learning cases all need.

Syllabification is not a matter of counting vowels. The same consonant run breaks differently depending on what surrounds it, languages disagree about which onsets are legal, and plenty of words have no vowel at all.

Talk does it in three steps. It reads the word as SOUNDS rather than characters, so $n is one velar nasal and not a $ beside an n. It matches those sounds against per-position cluster whitelists in base/clusters/ — which runs may open a syllable, which may close one, which may stand alone — taking the longest match. Then it assembles the clusters, with a colon in a cluster spelling marking where a break is allowed rather than forced.

Two rules are deliberate and easy to mistake for bugs. A word boundary is NOT a syllable boundary: spoken French runs a coda onto the next word, so ʃu də bʁy.sɛl gives xu.dUb.$G$i.sEl, the b of Bruxelles closing the syllable that starts in de. That is enchaînement. And a tie is never cut, so an affricate stays whole even where a break would otherwise fall.

It is checked against every valid-IPA pronunciation in the ClueSurf export: 2,916,542 of 2,916,548 split without losing a sound, the six exceptions being strings like ˦˧ that hold no phones at all, where no syllables is the right answer. All three libraries are held to the same fixture, so they agree case for case.

Losslessness is not correctness. That 2.9 million figure says no sound was dropped; it says nothing about whether every boundary landed in the right place, and the two are easy to confuse.

• Vowelless words. Nuxalk and Bella Coola build whole words out of consonants, spʰs and qʷʰtʰ among them. They survive the split, but the cluster tables were not written with them in mind and the breaks inside them are not yet trusted.
• A correctness pass over the corpus. Roughly 42,000 pronunciations produce a syllable with no vowel in it. Most match patterns that are right — a vowelless word, a word-final coda, a word-initial onset — but the medial cases have no precedent either way and want a linguist's eye rather than a test.
• Onset maximization. at͡sa currently gives ats<B> | a where a | ts<B>a is the expected reading. The affricate is intact, the boundary is arguable.

There are two NOTATIONS and three TIERS, so six encodings in all. Which one you want follows from two questions: does it need to give the sound back exactly, and how much detail does it need to carry.

ipa is lossless. It reads and writes the source strings, so what goes in comes back out. Use it when something downstream will be compared to, displayed as, or exported as the original: a dictionary field, a conlang's stored inventory, a join against Phoible or Wiktionary.

tone is talk's own ASCII notation, the one this readme spends most of its length on. It is deliberately COARSER than IPA: O covers six IPA vowels, i$ covers ɨ, y and ʏ, H$ and x share a base. That coarseness is the point, because it makes the space small enough to be a model's vocabulary, but it means tone does not round-trip every distinction IPA can write.

The LIBRARY is called talk; the NOTATION it defines is called tone.

seed splits a sound into its parts, so pʰ becomes two units. Small enough to read, and the right shape for a factored model vocabulary.

band keeps aspiration, dentality, voicelessness and secondary articulation, and drops duration, stress, tone and syllabicity. Note that vowel length is phonemic in Finnish, Japanese and Arabic, so this tier is narrower than it sounds.

mesh keeps everything the notation encodes. This is the default.

import {
  machine,
  machineText,
  machineBytes,
  byteWidth,
} from '@cluesurf/talk'

// The flat code: one integer per sound, tone at full detail.
machine({ text: 'takw~a', type: 'tone', system: 'mesh' })
// [20504, 7592, 12424, 7592]
machineText({ text: 'takw~a', type: 'tone', system: 'mesh' })
// fixed-width characters, for a text index

// A tier, chosen.
machine({ text: 'tʰa', type: 'ipa', system: 'seed' }) // [18, 104, 0]
machine({ text: 'tʰa', type: 'ipa', system: 'mesh' })
machine({ text: 't<h>a', type: 'tone', system: 'band' })

byteWidth({ type: 'ipa', system: 'mesh' }) // 4
machineBytes({ text: 't<h>a', type: 'tone', system: 'mesh' }) // 4 bytes

Every code is COMPUTED, not looked up. A table for ipa mesh would be over a gigabyte, so each code is a mixed-radix index instead: the base picks an offset and each axis contributes a digit whose radix is how many marks that axis offers that base. The only tables are the bases, the axes and a per-base offset, a few thousand integers, so this runs in a browser as happily as on a server and the package ships no code registry at all.

The number that decides it is not vocabulary size but how often a tier MERGES two sounds some language contrasts. Measured across Phoible's 3,020 doculects:

Read the last column first: it is the share of documented languages for which the encoding destroys a distinction the language depends on. Even tone mesh costs 29%, because talk's base inventory is deliberately coarse and no tier setting recovers that. If a merged contrast would be a bug, use ipa.

A note on scale: tone mesh holds 25,426 producible sounds and only 2,161 are attested anywhere. The other 91% are pronounceable and simply nobody's, which is the space a constructed language draws from.

normalizeIpa folds the many ways IPA gets written into the one form the parser reads. parseIpa applies it, so this is only needed directly when normalizing without parsing.

import { normalizeIpa } from '@cluesurf/talk'

normalizeIpa('ʆ') // 'ʃʲ'      withdrawn 1989, palatal hook
normalizeIpa('ma³³') // 'ma˧˧'    superscript digits are tone
normalizeIpa('ɡ̊') // 'ɡ̥'      ring above and below are one feature
normalizeIpa('g') // 'ɡ'       ASCII lookalikes
normalizeIpa('t͡ʃ') // 'tʃ'      tie bars carry no content

It also DROPS fine phonetic detail this encoding does not carry: breathy, creaky, retracted, advanced, apical, laminal, raised, lowered, and the rest. That is lossy on purpose, so a source carrying the mark still yields its base sound rather than failing. Pass keepDetail to leave them in place and see what a source carries that talk drops.

normalizeIpa('b̤') // 'b'
normalizeIpa('b̤', { keepDetail: true }) // 'b̤'

MIT

Made by ClueSurf, meditating on the universe ¤. Follow the work on YouTube, X, Instagram, Substack, Facebook, and LinkedIn, and browse more of our open-source work here on GitHub.