# filmvocab

> filmvocab turns the subtitles of films and series into a personal English vocabulary list: the words the user does not know yet, most used first, each with the line where it is spoken and a translation into the user's language, plus spaced-repetition reviews.

Everything the web pages do is available to AI assistants and scripts: find and add films, see their words, mark words known or learning, quiz the user on words due for review, and follow their progress.

## Connect

- MCP server: https://filmvocab.com/mcp (Streamable HTTP). Assistants that support OAuth, like Claude and ChatGPT, need only this address: the user logs in and allows access.
- REST API: https://filmvocab.com/api/v1, described by the OpenAPI document at https://filmvocab.com/api/openapi.json.
- Sign-in: OAuth 2.1, authorization code with PKCE and dynamic client registration (https://filmvocab.com/.well-known/oauth-authorization-server), or a personal token made on https://filmvocab.com/profile and sent as `Authorization: Bearer <token>`.

## Tools

- get_account: Who the user is, the language words are translated into, how many films and words they have, and how many reviews are due. A good first call.
- set_language: Change the language that words are translated into. Missing translations are fetched in the background.
- list_films: The films and episodes in the user's list, newest first, with how much of each one's vocabulary the user already knows.
- get_film: A film's vocabulary: the words most used in it first, each with a translation, how often it is spoken, how common it is in English (rank 1 is the most common), and an example line from the film. Coverage says what share of the spoken words the user knows and how many more to learn to reach 95%.
- find_subtitles: Search subtitle sites for a film or an episode. For an episode give the series title with season and episode. Some sites answer after a few seconds: if still_searching is not empty, call again for more results. Pass a result's source to add_film.
- add_film: Add a film to the user's list, either from a find_subtitles result (source) or from subtitle text you have (name and content, in SRT, VTT or ASS format, in English). Finding the words takes up to a minute; get_film shows the status.
- rename_film: Change the name a film is listed under. Names like "Show S01E02" group episodes into a series.
- remove_film: Remove a film from the user's list. Their word lists stay as they are.
- list_words: Words from all the user's films in one list: new (not in any list yet), learning (being reviewed) or known. Search matches the start of the English word or any part of its translation.
- get_word: Everything about one word: translations by part of speech, English definitions, whether the user knows or is learning it, their own meaning and note, when it is next due for review, and the lines where it is spoken in their films.
- set_word_status: Mark words as known (they drop out of the lists to learn), start learning them (they come up for review), or return them to new (their own meaning and note are kept).
- update_word: Set the meaning shown on the user's review cards (comma-separated, replaces the previous one; empty restores the dictionary meaning) and a personal note. The note suits a memory aid: a vivid image linking the word to a similar-sounding word in the user's language, or a sentence the user wrote with the word. A word not yet in a list starts learning.
- import_known_words: Mark every English word in a text as known: a word list, an Anki export or any text the user understands. Words already in a list are left alone.
- prepare_film: Before the user watches a film: start learning the words that help most with it, most spoken first, keeping words with the same meaning apart. They are due at once: quiz them with next_review and film_id.
- next_review: Words due for review, to quiz the user. Vary the kind of question: ask for the meaning of the word, for the English word from its meaning, or for the missing word in the cloze line from a film (its first letter is a fair hint). Then reveal the answer and record it with answer_review. Each card says when the word comes back after each grade.
- answer_review: Record how well the user recalled a word: again (forgot), hard (recalled with effort), good (recalled) or easy (instantly). The schedule adapts to the answers (FSRS): new words come back after minutes, then after growing numbers of days, and are known once they are expected to stick for months. Answers before a word is due only count when the user forgot it.
- get_progress: Review activity over the last 30 days: how many reviews, the share remembered, the current streak, words learned, and how many reviews are coming up.

## Flows

- Add a film: find_subtitles, then add_film with a result's source, then get_film once it is ready.
- Prepare for watching: get_film lists the words to learn, most spoken first, with the line where each is spoken.
- Quiz: next_review gives the due words; ask the user, then answer_review with good or again.