zh-lx/pinyin-pro

pinyin-pro is a JavaScript library that converts Chinese characters into pinyin, which is the standard romanization system used to write out how Mandarin Chinese words are pronounced. If you have Chinese text and need to display it with pronunciation guides, search it using phonetic spelling, or process it in ways that require the spoken form, this library handles that conversion for you. The library runs in both web browsers and Node.js environments, and you install it through npm or load it from a CDN link. Once installed, you call its functions by passing in a string of Chinese text and getting back pinyin in whatever format you need: a single string, an array of syllables, with tone marks, without tone marks, or with tones written as numbers instead of accent symbols. It also has a special mode for handling Chinese surnames, which often have different pronunciations than the same characters used in other contexts. Beyond basic conversion, pinyin-pro includes a matching function that lets you search Chinese text using pinyin input. A user typing partial pinyin like "zwp" can match the full Chinese phrase "中文拼音" because the library knows how to connect abbreviations and full spellings to the underlying characters. There is also a conversion function for switching between different pinyin notation formats, and an HTML function that wraps Chinese characters in markup that displays pronunciation above each character, similar to furigana in Japanese. The README benchmarks pinyin-pro against two other popular libraries. On accuracy, pinyin-pro reaches 99.846% versus roughly 94% for its alternatives. On speed, converting 5,000 characters takes about 6 milliseconds compared to 749 milliseconds for the slowest competitor. One competing library fails entirely on very large inputs due to memory errors, while pinyin-pro handles one million characters without issue. The project is licensed under MIT, meaning it is free to use in personal and commercial projects without restriction.