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, and each carries the tiered codec. The TypeScript and Rust libraries also split words into syllables.

All three are verified against the same fixture: they agree on the talk spelling, machine codes and normalization of every one of Phoible's 3,422 phonemes.

The machine column is the machine encoding: talk.machine(...) gives one integer per sound, base plus all its modifiers, so a whole word becomes a compact array with one entry per sound rather than per character.

Here are the modifiers on consonants, vowels, and symbols (like punctuation), and how they look in ASCII.

There are a few affixes on consonants and vowels. There are 5 tone affixes (extra low, low, neutral, high, and extra high), which can be combined in standard ways.

Two conventions are worth calling out.

~ FORMS A SUPERSCRIPT on a consonant. n~ is ⁿ, l~ is ˡ, y~ is ʲ. On a vowel the same mark is nasality, a~ being ã. Dental moved to $ to free it.

@ IS SYLLABICITY read against the base's default. A vowel is syllabic unless marked and a consonant is not, so @ means non-syllabic on i@ and syllabic on n@.

This is the full set of IPA consonants we map, in tone and machine form. Every consonant, however modified, is a single machine code.

Note: GitHub markdown doesn't really render the diacritics that nicely, some are misaligned. We will have a font to remedy this for websites.

This is the full set of IPA vowels we map. Every vowel, with any tone, length, stress, or nasalization, is a single machine code.

The IPA defines a set of diacritics that modify a base symbol, grouped by type below. The state column says whether Talk maps the diacritic to a phonetic feature, or ignores it, and talk is the resulting Talk affix when it is mapped.

Talk also splits a word into syllables, each a sequence of onset, nucleus, and coda clusters. IPA and X-SAMPA give you symbols and stop there, so this comes built in, which the TTS, speech-recognition, and language-learning use cases all need.

Some rarer sounds are not yet handled by the syllable system. The current gaps are listed in base/syllable/unsupported.csv (dentals, retroflex plosives, implosives, ejectives, and clicks).

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' }) // [49710672, 0]
machine({ text: 'th~a', type: 'tone', system: 'band' }) // [1778, 683]

byteWidth({ type: 'ipa', system: 'mesh' }) // 4
machineBytes({ text: 'th~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.