phonemize
Version:
Fast phonemizer with rule-based G2P prediction. Pure JavaScript implementation.
144 lines (143 loc) • 5.82 kB
TypeScript
/**
* Phonemize Library - Main API
*
* A comprehensive text-to-phoneme conversion library supporting:
* - IPA (International Phonetic Alphabet) output
* - ARPABET phonetic notation
* - Number and abbreviation expansion
*
* The default exports (`phonemize`, `useProcessor`, `addPronunciation`, ...)
* read and write a single global LanguageRegistry, which is what
* `phonemize/index` and `phonemize/all` populate. To run an isolated set
* of processors — e.g. force English-only output, or stack two unrelated
* language configurations in the same process — use `createPhonemizer()`
* instead.
*/
import { Tokenizer, TokenizerOptions, PhonemeToken } from "./tokenizer";
import { LanguageRegistry, useProcessor } from "./g2p";
import type { LanguageProcessor } from "./g2p";
export type { TokenizerOptions, PhonemeToken };
export { Tokenizer, useProcessor, LanguageRegistry };
export type { LanguageProcessor } from "./g2p";
/**
* Convert text to phonetic representation
*/
export declare function phonemize(text: string, options: TokenizerOptions & {
returnArray: true;
}): PhonemeToken[];
export declare function phonemize(text: string, options?: TokenizerOptions): string;
export declare function phonemize(text: string, returnArray: true): PhonemeToken[];
/**
* Shorthand: pass a language tag (e.g. `"en-GB"`) as the second argument
* to bias dispatch toward processors matching that tag.
*/
export declare function phonemize(text: string, language: string): string;
/**
* Convert text to International Phonetic Alphabet (IPA) notation
*
* @example
* ```typescript
* toIPA("hello world") // "həloʊ wɝld"
* toIPA("中文", { anyAscii: false }) // "ʈʂʊŋ˥˥ wən˧˥"
* toIPA("hello", "en-GB") // RP-flavored output
* ```
*/
export declare function toIPA(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
/**
* Convert text to ARPABET phonetic notation
*/
export declare function toARPABET(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
/**
* Convert text to Zhuyin (Bopomofo) notation. Chinese characters are
* converted to Zhuyin with tone numbers; non-Chinese characters fall
* back to IPA.
*/
export declare function toZhuyin(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
/**
* Add a custom pronunciation to the default global registry's matching
* processor. For multi-instance setups, use `Phonemizer#addPronunciation`.
*/
export declare function addPronunciation(word: string, pronunciation: string, language?: string): void;
/**
* Create a custom tokenizer instance with specific configuration. Useful
* when you want to reuse the same options across many calls.
*/
export declare function createTokenizer(options?: TokenizerOptions): Tokenizer;
/**
* Options for `createPhonemizer()`.
*/
export interface PhonemizerOptions {
/**
* Initial set of language processors. Equivalent to calling
* `useProcessor()` for each on a freshly created instance. The first
* registered processor is the default fallback when no language is
* provided.
*/
processors?: LanguageProcessor[];
/**
* Default language tag applied to every call (overridable per-call).
*/
language?: string;
}
/**
* An isolated phonemizer with its own language registry. Use this when you
* want to register a different set of languages per call site without
* mutating the global registry — for example, a server that handles
* one user request with English-only output and another with the full
* multilingual stack.
*
* @example
* ```ts
* import { createPhonemizer, EnglishG2P } from "phonemize";
*
* const enOnly = createPhonemizer({ processors: [new EnglishG2P()] });
* enOnly.phonemize("hello 中文"); // "həˈɫoʊ 中文" (zh untouched)
*
* const rp = createPhonemizer({
* processors: [new EnglishG2P({ dialect: "en-GB" })],
* language: "en-GB",
* });
* rp.phonemize("doctor"); // RP transformation applied
* ```
*/
export declare class Phonemizer {
readonly registry: LanguageRegistry;
private readonly defaultLanguage?;
constructor(options?: PhonemizerOptions);
useProcessor(processor: LanguageProcessor): this;
unregister(id: string): boolean;
private _resolve;
phonemize(text: string, options: TokenizerOptions & {
returnArray: true;
}): PhonemeToken[];
phonemize(text: string, options?: TokenizerOptions): string;
phonemize(text: string, returnArray: true): PhonemeToken[];
phonemize(text: string, language: string): string;
toIPA(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
toARPABET(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
toZhuyin(text: string, options?: Omit<TokenizerOptions, "format"> | string): string;
addPronunciation(word: string, pronunciation: string, language?: string): void;
createTokenizer(options?: TokenizerOptions): Tokenizer;
}
/**
* Factory shorthand for `new Phonemizer(options)`.
*/
export declare function createPhonemizer(options?: PhonemizerOptions): Phonemizer;
/**
* Phonemize library default export
* Provides all core functions and classes for CommonJS compatibility
*/
declare const phonemizer: {
readonly phonemize: typeof phonemize;
readonly toIPA: typeof toIPA;
readonly toARPABET: typeof toARPABET;
readonly toZhuyin: typeof toZhuyin;
readonly addPronunciation: typeof addPronunciation;
readonly createTokenizer: typeof createTokenizer;
readonly useProcessor: typeof useProcessor;
readonly createPhonemizer: typeof createPhonemizer;
readonly Tokenizer: typeof Tokenizer;
readonly Phonemizer: typeof Phonemizer;
readonly LanguageRegistry: typeof LanguageRegistry;
};
export default phonemizer;