Eartype

An English listening trainer with two ways to practise:

• Video dictation. Pick a YouTube video; the app cuts its captions into 3-to-8-second segments, plays one, pauses exactly at its end, and compares what you typed against the real caption, word by word.
• Vocabulary. A flip-card deck: a Portuguese word on the front, the English typed (or spoken) back. A daily session is suggested from how each word has gone so far.

The idea behind dictation is simple: understanding a video with the subtitles on is easy, and it lies to you. Typing what you heard does not forgive — either the word reached your ear or it did not.

It is a personal tool: UI in Portuguese, no login, progress kept in the browser. Engineering conventions are in docs/RULES.md; agent instructions are in AGENTS.md.

Video dictation

library video, or URL + .srt/.vtt, or URL alone (yt-dlp)  →  cues  →  segments
                                                                         ↓
          word-by-word diff  ←  what you typed  ←  plays and pauses at the end

The way in, on /videos, goes in the order that works:

1. The library — videos whose captions ship with the project (content/library/). They open straight into practice, no download.
2. A new video with its caption file — paste the URL and drop an .srt or .vtt. Links to third-party caption download sites are offered, already filled in for that video. From here the video can be added to the library in one click.
3. Automatic lookup through yt-dlp — convenient when it works, but YouTube blocks it often, so it is the last option, not the first.

Five decisions shape everything else:

• The pause is polled. The YouTube IFrame API never says "I reached time X", so the app reads getCurrentTime() every 100ms and pauses on crossing the mark. Measured: it stops ~64ms late, with ±8ms of spread. Pausing early would clip the last syllable, so there is no compensation — 64ms late lands in the silence between sentences.
• Correction is lenient by default. Case and punctuation do not count; "I'm gonna go" and "I am going to go" are the same answer, and we'll typed as well is accepted. Strict mode is a toggle, offered only when the captions are manual and have punctuation worth enforcing.
• Raw captions are unusable as they come. A 0.8s cue, a cue that lingers 20s after the speech ended, [Music], >>, the rolling text of auto-generated captions, a 20-word cue holding three sentences. Cues are split at sentence and clause breaks, then regrouped by the segmenter. When both tracks exist, hand-written captions are re-timed against the ASR word timings, because hand-typed timings wander by up to ~2s.
• Bringing your own caption file is a first-class path, not an error screen. It is the only route that does not depend on an undocumented endpoint staying up.
• The transcript sits alongside, blurred. Each line leaves the blur when you answer its segment, so the filled-in panel is your progress.

Around the loop:

• Word slots ("Dica de letras") — the input draws one blank per letter of each word, filled as you type, so you know how many words there are and how long each one is. Ctrl+↓ reveals just the next word when you are stuck.
• Transcript panel — lift the blur entirely, change the subtitle size (− / +), copy a line, or translate a line to Portuguese on request (Google Translate's free endpoint, through /api/translate).
• Video settings (gear icon) — the word-slots hint and strict mode on or off, mark every remaining segment done, or restart the run. The actions that rewrite the run ask first.
• Progress is kept per video in localStorage: close the tab and you come back to where you stopped. Outcomes are keyed by the segment's start time, so re-segmented captions keep what still lines up.

Shortcuts

Your hands never have to leave the keyboard:

shortcut	action
Enter	check; after a miss, accept and move on
Shift+Enter	line break
Ctrl+Enter	replay the segment
Ctrl+Space	pause / resume
Ctrl+↓	reveal the next word
Ctrl+→	reveal the answer and move on
Alt+← / Alt+→	previous / next segment

Get it exactly right and "✓ acertou" appears; the segment advances on its own after 1.2s.

The library

One folder per video in content/library/<videoId>/, with captions.srt (or .vtt) and a meta.json. Instructions, including adding by hand, are in content/library/README.md. Library pages are prerendered at build.

When running locally the library is writable: cards can be added from the practice screen and deleted from their card. A production build is read-only unless LIBRARY_WRITABLE=1 is set.

If a new video's subtitles run early or late, the YouTube upload usually has an intro the caption file lacks (TED: ~12s). Compare a line at the start and one at the end against YouTube's transcript; if the gap is the same, shift every timestamp in captions.srt by that amount.

Vocabulary

On /vocabulary:

• Today's session comes first, worked out from each word's stats: words you keep missing, then words you have not seen in a while, then new ones. Or pick a subject (category) yourself.
• Typing or voice. Typing is lenient about case, articles and accepted synonyms, strict about spelling — a one-letter slip shows as "almost" but counts as a miss. In voice mode the browser's speech recognition fills the field and you confirm the answer yourself. The choice sticks between visits.
• Past-tense verbs are their own deck, asked in English: the present on the card, the past typed back. Always typed — a recognizer hears the past of read as red.
• Every answer is saved as you go, so stopping loses nothing.

This is the beginning of the README. Read the rest at the original. Read the full README ↗