Narrator with Subtitles is a web application to help with language learning.
For some languages (like those of India other than Hindi), there are very few resources to practice listening skills. Listening to everyday conversations or watching videos may be difficult for beginners because natural conversations are fast, use a wide vocabulary, and may have non-standard accents and slang. Often, only English subtitles are available, which helps understand the meaning but may not be good for understanding the words.
Some languages have good textual resources but not good spoken resources. This is where Narrator with Subtitles can help. It speaks out text using a text-to-speech engine and enables easy navigation across sentences in a lesson. Other features:
This web app's source code can be found at
github:
To use this web application, you must open an article. An article is a file containing text, along with other information like which language it is in and translations for each sentence. This app supports three article formats: CSV, HTML, and plain text (TXT).
To open an article, click the leftmost button. You can then either:
You can also drag-and-drop files onto the web page.
Another way to open an article bundled with this web app is using querystrings.
Appending ?article=ict-20 to the URL
will open ‘ICT Lesson 20’.
The codes for all built-in articles can be found in
fetchers.ts.
The app’s interface consists of three main parts. They are (from top to bottom):
After an article is opened, at any point in time, one of the sentences is selected. The selected sentence is highlighted in blue. You can select a different sentence by clicking it, by using the Previous and Next buttons, or using the left and right arrow keys.
Every article has an associated primary language. The article may include translations of text from the primary language to one or more secondary lanuages. For example, ICT Lesson 20’s primary language is Telugu. It provides translations in Hindi and English, so those are secondary languages.
The spotlight shows the translation of the currently selected sentence in one of the secondary languages. You can specify your preference order for secondary languages in Text Settings (accessible by clicking the gear icon in the toolbar). Text Settings also displays the primary language at the top.
Pressing the play button in the toolbar (or pressing spacebar on the keyboard) will speak the currently selected sentence, or pause it if it is already speaking. However, for this to work, a text-to-speech engine must be available for the primary language. If it is unavailable, the play button and the voice settings button will be disabled.
This web app relies on the web browser’s Speech Synthesis service, which in turn (usually) relies on the operating system’s text-to-speech service. If a text-to-speech engine is not available for the primary language, you may be able to install it. Keep in mind that after this installation, for the changes to take effect, you may have to restart your web browser.
(Instructions tested on .)
macOS (Sonoma):
This app supports three article formats: CSV, HTML, and plain text (TXT). The built-in articles have an example of each:
Each format has its unique advantages. TXT is the simplest, but it doesn't allow providing translations. CSV is also quite simple, and it allows providing translations. HTML is the most expressive (allowing arbitrary document markup).
In all formats, languages are specified by their two-letter
IETF language tags.
E.g., the tag for English is en and the tag for Hindi is hi.
CSV stands for ‘Comma-Separated Values’. It is a format for representing tables. Each line of the file is a row, and the cells of the row are separated by commas. For example, here is a table and its CSV.
| A1 | A2 | A3 |
| B1 | B2 | B3 |
A1,A2,A3
B1,B2,B3
The CSV article has a column or each language: the first column for the primary language and the remaining columns for secondary languages. The first row contains the IETF codes for the languages. Each subsequent row contains a sentence and its translations. A line with blank cells marks the end of a paragraph. See SK1 Chapter 2 (csv) for an example (the opened article can be seen here).
You can view and edit CSV files using a text editor, Google Sheets, or macOS Numbers. Microsoft Excel also works, but you may have to work around encoding-related issues. When saving a CSV file in Excel, ensure that you select ‘CSV UTF-8’ as the file format. If you have trouble opening CSV files in Excel, follow these steps by Microsoft.
A plain text (txt) article just contains text in the primary language. A blank line (two newline characters) marks the end of a paragraph. See Clarinette (txt) for an example.
Unlike CSV and HTML, the file's contents do not specify the primary language,
so it must be deduced through other means.
When uploading a txt file, the file's name should be of the form A.B.txt,
where B is the IETF tag for the language.
The ‘Paste or write text’ option for opening an article uses the txt format.
In the HTML article format, the primary language is specified via the lang
attribute of the <html> element.
The article's contents are in the <body> element.
The <head> can be empty.
Any HTML element containing the lang attribute is a tagged sentence.
Tagged sentences must not be nested.
When the article is opened, only tagged sentences can be selected and spoken.
If the value of the lang attribute of an element is the same as the primary language,
the element will show up in the reader, otherwise it is a translation of its
closest previous sibling with the primary language.
See
ICT Lesson 33 (html) for an example.
To prevent XSS attacks, the HTML is aggressively sanitized. If the sanitization alters the document, a warning will be displayed in the reader. Built-in articles are not sanitized.
The nodeJS script convert.js can convert a CSV article to an HTML article. This script is useful if you want to create a first version of the article using CSV and then switch to HTML later for its expressiveness.