HOWTO Add Pīnyīn Subtitles to Streaming Movies

This document shows how to add pīnyīn subtitles to streaming movies from sites such as Viki, Netflix, HBO/Max, etc. with browser extensions in Firefox. It likely works with other browsers such as Chromium.

Rationale

Subtitles are a great way to study a foreign language. The problem with this in Mandarin is that the subtitles are in Hànzì, not pīnyīn, so new students typically can't read the subtitles.

Following a Mandarin movie with pīnyīn makes it much easier to understand what the actors are saying.

Hànzì to Pīnyīn

The trick is to have the Hànzì converted to pīnyīn on the fly. The "Pinyin Annotator" extension does this automatically.

It can be downloaded and installed in Firefox:

• https://addons.mozilla.org/en-US/firefox/addon/pinyin-annotator/

Source code (GPLv3):

• https://github.com/fixicelo/pinyin-annotator

Pīnyīn and English

While the "Pinyon Annotator" extension is great for adding pīnyīn, you can't view the English subtitles at the same time.

There is another browser extension, "asbplayer" that allows you to view multiple subtitles at the same time.

It can be downloaded and installed in Firefox:

• https://addons.mozilla.org/en-US/firefox/addon/asbplayer-language-learning/

Source code (MIT):

• https://github.com/asbplayer/asbplayer

With "asbplayer" you can set the subtitle sizes, colors, and many more options. Click to open the side panel to select which subtitles to add.

This also presents some options for the user in how to handle the subtitles. For instance, you could enable Mandarin subtitles in Netflix, then add English subtitles with "asbplayer". But I think the superior solution is to turn off subtitles in the streaming service (e.g. Netflix) and enable both Mandarin and English subtitles in "asbplayer". This allows for the best rendering.

Remove Hànzì

With "Pinyin Annotator" and "asbplayer" working, you now have three subtitles being displayed: Hànzì, pīnyīn, and English.

This can be a bit much on the screen, especially if you don't read the Hànzì. The best solution is to remove the Hànzì.

This can be done with yet another extension that dynamically changes the CSS on the fly.

It can be downloaded and installed in Firefox:

• https://addons.mozilla.org/en-US/firefox/addon/styl-us/

Source code (GPLv3):

• https://github.com/openstyles/stylus

To use this, you need to add custom CSS code for the particular website.

Use this code:

/* Pinyin Annotator: show only pinyin, hide the Chinese characters */
pya.py-chinese-item { display: none !important; }

/* Promote pinyin from tiny ruby text to a normal inline line */
pya.py-result-item ruby { display: inline !important; }
rt.py-pinyin-item {
  display: inline !important;
  font-size: 1em !important;        /* match the subtitle text size */
  margin-inline-end: 0.25em;        /* space between syllables */
}

Sites

This works with:

• Viki (Rakuten)
• Netflix
• HBO/Max

This does not work with:

• IQ

License

Creative Commons Attribution-ShareAlike 4.0 International. See LICENSE-CC.txt for details.

Copyright © 2026 Jeff Moe moe@spacecruft.org

Loveland, Colorado, USA