The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { SpeechCustomWords } from "@t3tools/contracts"; |
| 2 | |
| 3 | // These scripts are written without spaces, so a neighbor in one of them still ends a word. |
| 4 | const UNSPACED_SCRIPTS = "\\p{scx=Han}\\p{scx=Hiragana}\\p{scx=Katakana}"; |
| 5 | const LETTER = `[[\\p{L}\\p{M}\\p{N}]--[${UNSPACED_SCRIPTS}]]`; |
| 6 | const WORD_CHARACTER = `[[\\p{L}\\p{M}\\p{N}\\p{Pc}]--[${UNSPACED_SCRIPTS}]]`; |
| 7 | const TOKEN = new RegExp(`${LETTER}(?:[^\\s${UNSPACED_SCRIPTS}]*${LETTER})?`, "gv"); |
| 8 | |
| 9 | /** Fuzzy-matches preferred terms and rewrites aliases to their preferred spelling. */ |
| 10 | export function makeSpeechTextCorrector( |
| 11 | words: readonly string[], |
| 12 | dictionary: SpeechCustomWords = [], |
| 13 | ) { |
| 14 | const MATCH_THRESHOLD = 0.18; |
| 15 | |
| 16 | const matchKey = (value: string) => |
| 17 | [...value] |
| 18 | .filter((character) => /[\p{L}\p{N}]/u.test(character)) |
| 19 | .join("") |
| 20 | .toLocaleLowerCase(); |
| 21 | |
| 22 | const isAsciiKey = (value: string) => /^[a-z0-9]+$/i.test(value); |
| 23 | |
| 24 | const soundex = (value: string) => { |
| 25 | const upper = value.toUpperCase(); |
| 26 | const first = upper[0] ?? ""; |
| 27 | const code = (character: string) => { |
| 28 | if ("BFPV".includes(character)) return "1"; |
| 29 | if ("CGJKQSXZ".includes(character)) return "2"; |
| 30 | if ("DT".includes(character)) return "3"; |
| 31 | if (character === "L") return "4"; |
| 32 | if ("MN".includes(character)) return "5"; |
| 33 | if (character === "R") return "6"; |
| 34 | return "0"; |
| 35 | }; |
| 36 | let previous = code(first); |
| 37 | let result = first; |
| 38 | for (const character of upper.slice(1)) { |
| 39 | const next = code(character); |
| 40 | if (next !== "0" && next !== previous) result += next; |
| 41 | previous = next; |
| 42 | } |
| 43 | return `${result}000`.slice(0, 4); |
| 44 | }; |
| 45 | |
| 46 | const editDistance = (left: string, right: string) => { |
| 47 | let previous = Array.from({ length: right.length + 1 }, (_, index) => index); |
| 48 | for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) { |
| 49 | const current = [leftIndex + 1]; |
| 50 | for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) { |
| 51 | current.push( |
| 52 | Math.min( |
| 53 | current[rightIndex]! + 1, |
| 54 | previous[rightIndex + 1]! + 1, |
| 55 | previous[rightIndex]! + (left[leftIndex] === right[rightIndex] ? 0 : 1), |
| 56 | ), |
| 57 | ); |
| 58 | } |
| 59 | previous = current; |
| 60 | } |
| 61 | return previous[right.length]!; |
| 62 | }; |
| 63 | |
| 64 | const preserveCase = (original: string, replacement: string) => { |
| 65 | const letters = [...original].filter((character) => /\p{L}/u.test(character)); |
| 66 | if (letters.length > 0 && letters.every((character) => character === character.toUpperCase())) |
| 67 | return replacement.toUpperCase(); |
| 68 | const firstLetter = [...original].find((character) => /\p{L}/u.test(character)); |
| 69 | if (firstLetter && firstLetter === firstLetter.toUpperCase()) { |
| 70 | const [first = "", ...rest] = [...replacement]; |
| 71 | return first.toUpperCase() + rest.join(""); |
| 72 | } |
| 73 | return replacement; |
| 74 | }; |
| 75 | |
| 76 | type CustomWordKey = { readonly word: string; readonly key: string }; |
| 77 | |
| 78 | const customWordKeys = (words: readonly string[]): CustomWordKey[] => |
| 79 | words.flatMap((word) => { |
| 80 | const sources = [word]; |
| 81 | if (word.includes("&")) sources.push(word.replaceAll("&", " and ")); |
| 82 | const keys = sources.flatMap((source) => { |
| 83 | const key = matchKey(source); |
| 84 | // A term that loses its symbols to one letter (C# -> c) would claim every standalone letter. |
| 85 | const lostSymbols = key !== source.replace(/\s+/gu, "").toLocaleLowerCase(); |
| 86 | return key.length < 2 && lostSymbols ? [] : [key]; |
| 87 | }); |
| 88 | return [...new Set(keys)].filter(isAsciiKey).map((key) => ({ word, key })); |
| 89 | }); |
| 90 | |
| 91 | const possessive = /['’]s$/iu; |
| 92 | const innerPossessives = (value: string) => value.match(/['’]s(?=\s)/giu)?.length ?? 0; |
| 93 | type Match = { readonly word: string; readonly score: number; readonly suffix: string }; |
| 94 | const bestMatch = (phrase: string, keys: readonly CustomWordKey[]) => { |
| 95 | const key = matchKey(phrase); |
| 96 | const suffix = phrase.match(possessive)?.[0] ?? ""; |
| 97 | const stem = suffix ? key.slice(0, -1) : key; |
| 98 | if (!isAsciiKey(stem) || stem.length > 50) return undefined; |
| 99 | const inner = innerPossessives(phrase); |
| 100 | let best: Match | undefined; |
| 101 | for (const custom of keys) { |
| 102 | if (inner > 0 && inner > innerPossessives(custom.word)) continue; |
| 103 | const keepSuffix = suffix !== "" && !possessive.test(custom.word); |
| 104 | const candidate = keepSuffix ? stem : key; |
| 105 | if (Math.min(candidate.length, custom.key.length) < 4 && candidate !== custom.key) continue; |
| 106 | const longest = Math.max(candidate.length, custom.key.length); |
| 107 | if (Math.abs(candidate.length - custom.key.length) > Math.max(longest * 0.25, 2)) continue; |
| 108 | const distance = editDistance(candidate, custom.key) / longest; |
| 109 | const phonetic = /^[a-z]+$/i.test(candidate) && /^[a-z]+$/i.test(custom.key); |
| 110 | const score = |
| 111 | phonetic && soundex(candidate) === soundex(custom.key) ? distance * 0.3 : distance; |
| 112 | if (score < MATCH_THRESHOLD && (!best || score < best.score)) |
| 113 | best = { word: custom.word, score, suffix: keepSuffix ? suffix : "" }; |
| 114 | } |
| 115 | return best; |
| 116 | }; |
| 117 | |
| 118 | const apply = (text: string): string => { |
| 119 | if (keys.length === 0) return text; |
| 120 | // Leave surrounding punctuation in the source; only horizontal whitespace can join words. |
| 121 | const tokens = [...text.matchAll(TOKEN)] |
| 122 | .filter(([word]) => /^[\p{L}\p{M}\p{N}'’-]+$/u.test(word)) |
| 123 | .map((match) => ({ |
| 124 | value: match[0], |
| 125 | start: match.index, |
| 126 | end: match.index + match[0].length, |
| 127 | })); |
| 128 | const output: string[] = []; |
| 129 | let cursor = 0; |
| 130 | for (let index = 0; index < tokens.length;) { |
| 131 | let best: (Match & { readonly count: number }) | undefined; |
| 132 | for (let count = Math.min(4, tokens.length - index); count >= 1; count -= 1) { |
| 133 | const slice = tokens.slice(index, index + count); |
| 134 | if ( |
| 135 | slice |
| 136 | .slice(0, -1) |
| 137 | .some( |
| 138 | (token, offset) => |
| 139 | !/^[\t\p{Zs}]+$/u.test(text.slice(token.end, slice[offset + 1]!.start)), |
| 140 | ) |
| 141 | ) |
| 142 | continue; |
| 143 | const match = bestMatch(text.slice(slice[0]!.start, slice[count - 1]!.end), keys); |
| 144 | if ( |
| 145 | match && |
| 146 | (!best || match.score < best.score || (match.score === best.score && count < best.count)) |
| 147 | ) |
| 148 | best = { count, ...match }; |
| 149 | } |
| 150 | if (!best) { |
| 151 | index += 1; |
| 152 | continue; |
| 153 | } |
| 154 | const first = tokens[index]!; |
| 155 | output.push( |
| 156 | text.slice(cursor, first.start), |
| 157 | preserveCase(first.value, best.word), |
| 158 | best.suffix, |
| 159 | ); |
| 160 | cursor = tokens[index + best.count - 1]!.end; |
| 161 | index += best.count; |
| 162 | } |
| 163 | output.push(text.slice(cursor)); |
| 164 | return output.join(""); |
| 165 | }; |
| 166 | |
| 167 | const keys = customWordKeys(words); |
| 168 | const escapePattern = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); |
| 169 | |
| 170 | const spellings = dictionary |
| 171 | .flatMap(({ term, aliases }) => [term, ...aliases].map((spelling) => ({ spelling, term }))) |
| 172 | .sort((left, right) => right.spelling.length - left.spelling.length); |
| 173 | if (spellings.length === 0) return apply; |
| 174 | const lookup = new Map( |
| 175 | spellings.map(({ spelling, term }) => [spelling.toLocaleLowerCase(), term]), |
| 176 | ); |
| 177 | const pattern = new RegExp( |
| 178 | `(?<!${WORD_CHARACTER})(?:${spellings.map(({ spelling }) => escapePattern(spelling)).join("|")})(?!${WORD_CHARACTER})`, |
| 179 | "giv", |
| 180 | ); |
| 181 | return (text: string) => { |
| 182 | let output = ""; |
| 183 | let cursor = 0; |
| 184 | for (const match of text.matchAll(pattern)) { |
| 185 | output += apply(text.slice(cursor, match.index)); |
| 186 | output += lookup.get(match[0].toLocaleLowerCase()) ?? match[0]; |
| 187 | cursor = match.index + match[0].length; |
| 188 | } |
| 189 | return output + apply(text.slice(cursor)); |
| 190 | }; |
| 191 | } |
| 192 | |
| 193 | export function applySpeechAliases(text: string, words: SpeechCustomWords): string { |
| 194 | return makeSpeechTextCorrector([], words)(text); |
| 195 | } |
| 196 | |
| 197 | /** Hints first, so they survive the 100-term cap that cloud providers such as xAI enforce. */ |
| 198 | export const speechRecognitionWords = ( |
| 199 | hints: readonly string[] | undefined, |
| 200 | terms: readonly string[], |
| 201 | ): string[] => [...(hints ?? []), ...terms].slice(0, 100); |
| 202 | |
| 203 | const normalizeWord = (word: string) => word.replace(/\s+/g, " ").trim(); |
| 204 | |
| 205 | export function normalizeSpeechCustomWords(words: SpeechCustomWords): SpeechCustomWords { |
| 206 | const seen = new Set<string>(); |
| 207 | return words |
| 208 | .flatMap(({ term, aliases }) => { |
| 209 | const preferred = normalizeWord(term); |
| 210 | const key = preferred.toLocaleLowerCase(); |
| 211 | if (!preferred || preferred.length > 50 || seen.has(key)) return []; |
| 212 | seen.add(key); |
| 213 | const normalizedAliases = aliases.flatMap((alias) => { |
| 214 | const value = normalizeWord(alias); |
| 215 | const aliasKey = value.toLocaleLowerCase(); |
| 216 | if (!value || value.length > 50 || seen.has(aliasKey)) return []; |
| 217 | seen.add(aliasKey); |
| 218 | return [value]; |
| 219 | }); |
| 220 | return [{ term: preferred, aliases: normalizedAliases.slice(0, 8) }]; |
| 221 | }) |
| 222 | .slice(0, 100); |
| 223 | } |