Local conversion

EPUB Pinyin Converter

Add tone-marked pinyin above each Chinese character in reflowable EPUB files. Your book never leaves your device.

Open conversion tool

How it works

  1. Open the conversion tool and upload a reflowable EPUB with Simplified Chinese body text (drag-and-drop or file picker).
  2. The browser checks scope on your device—valid EPUB, reflowable layout, no DRM, file size, and a Traditional-Chinese sample—then annotates spine chapters in a background worker using pinyin-pro. You see chapter-level progress and can cancel.
  3. When conversion finishes, download {name}-pinyin.epub and open it in your e-reader.

FAQ

Scope and limits for the first version. See CONTEXT.md in the repository for full product terminology.

What kinds of EPUBs are supported?

Reflowable EPUBs whose spine body text is mostly Simplified Chinese. The tool walks spine chapters in order and adds tone-marked pinyin above plain Chinese text. Navigation files, images, and other assets are copied unchanged.

What is not supported in v1?
  • Fixed-layout books (comics, picture books, and similar)
  • DRM-protected EPUBs
  • Books that appear to use mostly Traditional Chinese (heuristic sample; see below)
  • Files over 100 MB (warning at 50 MB)
  • Batch conversion, in-browser chapter preview, or custom word lists
  • Non-UTF-8 chapter encodings (v1 reads and writes UTF-8 only)
How are Traditional Chinese books detected?

Before conversion starts, a sample of spine body text is scanned. Characters that match a static list of common Traditional forms are counted. Conversion is allowed when those markers make up at most 5% of Chinese characters in the sample. Books using Traditional forms outside the list may pass incorrectly; Simplified books with many marker characters (names, mixed editions) may fail incorrectly.

What file size limits apply?

Files over 50 MB show a warning but you may continue; files over 100 MB are rejected before conversion starts. Large books can take tens of seconds to process in the browser.

What pinyin format is used?

Tone-marked pinyin only (syllables with diacritics, e.g. zhōng). Tone numbers and toneless spellings are not offered in v1. Name-aware readings and tone sandhi are applied automatically.

What happens to existing ruby or code in a chapter?

Existing ruby markup is left unchanged. Scripts, styles, code blocks (code, pre), and embedded graphics or formulas (svg, math) are not annotated. Chinese in HTML attributes (such as image alt text) is also left unchanged.

Will the annotated book work on my e-reader?

Annotated books target standard reflowable EPUB readers, but display varies by device and app. There is no compatibility guarantee in v1.

Why does validation unpack my file before conversion?

Scope checks run on the main thread before the worker starts. On success, the worker unpacks the EPUB again to convert it. That double read is a known v1 cost for large files.

Privacy

Local conversion: the annotated book is produced entirely on your device. Source books are not transmitted to or stored on any server. The conversion tool runs in your browser; closing the tab ends the session. No account or upload is required.

The landing page is static HTML. Only the conversion tool loads the worker and libraries needed to process your file.

Source

Open source under the MIT License.