---
name: vocab-lesson-flashcard-csv
description: "Turn your own recorded vocabulary lessons into a flashcard CSV (each word spelled as on the card, gloss, lesson, timestamp) with Vivu. Use when you want a review deck that matches the lessons."
---Vocabulary lesson flashcard CSV with Vivu
This skill turns the last few vocabulary lessons you recorded and published (Spanish, French or another Latin alphabet language) into one flashcard deck. Claude measures the lesson files, prices the job against your Vivu plan, has you upload them to a private Vivu project, runs one search for the moments a word card or word caption is on screen, checks every result window against frames from your own files, reads each word from a full frame (accents, articles and the gloss exactly as on the card), sweeps every lesson with a local contact sheet for cards the search missed, and writes flashcards.csv, which Anki and Quizlet import, plus a review sheet you check before sending the deck to students.
The value is in the spelling on screen. Automatic captions hear a Spanish word inside English narration and write an English sounding guess, drop the accent, or leave the word out, and teachers often say the Spanish word without reading the English gloss aloud. The correct spelling, the article that marks gender, the accent marks and the gloss exist only on the card in the picture. Vivu finds the windows where cards are shown; the words themselves always come from a frame Claude reads, never from Vivu's reason text.
When to use
Use when a teacher or creator says "make flashcards from my last three vocab videos", "export every word I put on screen in these lessons as an Anki deck", "build a Quizlet set from my Spanish lessons", or "list the vocabulary cards in my videos with timestamps". For one question about one lesson ("what was the third word in lesson 4"), open the file or search Vivu directly. For subtitles, translating the narration or editing the videos, use other tools; this skill writes a deck and nothing else. It was tested on Spanish cards only, so for scripts other than the Latin alphabet treat every reading as unverified.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- Nothing goes into the deck as verified until a frame from the user's own file shows it. Search windows stay candidates until checked, and the spelling is read from the frame, not from the reason text, which paraphrases.
- Stop and tell the user when a required capability or tool is missing. Do not guess around it.
- Ask the user before anything that is expensive to redo or acts on their behalf: indexing (it uses plan minutes) and the field mapping before the deck is written in bulk. The skill never sends the deck to students; the user does that after checking it.
- Searches miss cards. A lesson with fewer windows than cards is normal, which is why Step 6 sweeps every lesson locally and the deck marks which rows came from the sweep.
What you need before starting
Check each item at the start of the run and tell the user plainly what is missing before doing anything else.
| Requirement | Why | How to check |
|---|---|---|
| Vivu connector with write access | create a private project, open its upload page, search | vivu_get_account shows can_create_projects: true (tool names may carry a server prefix). A write call failing with "has not granted vivu.write" means the connection is read only; ask the user to reconnect Vivu with write access |
| A shell with ffmpeg and ffprobe, on the computer that holds the lesson files | measure minutes, extract frames and contact sheets from the user's own files | ffmpeg -version and ffprobe -version |
| The lesson files in one local folder | every check and every spelling in the deck comes from these files | list the folder; ffprobe one file |
| yt-dlp and node, only if the lessons exist only on the user's YouTube channel | download the user's own videos at 720p; YouTube blocks cloud and datacenter IPs, so this needs a residential IP | yt-dlp --version and node --version |
| A way to upload: the user's own browser, or a browser tool that can attach local files | moving the lessons into Vivu | the user can open a link on this computer; Claude in Chrome accepts at most 10 MB per upload call |
This runs in Claude Code on the user's computer (terminal or the Code tab of Claude Desktop), because it needs a shell and the local files. A residential IP is needed only when the lessons are downloaded from YouTube. Nothing recurs, so there is no scheduled task, and no connector other than Vivu is used.
Inputs to collect
Ask for anything missing, most important first.
- The lesson files, or links to the user's own YouTube lessons. Required. Three or four lessons is a good first deck.
- The language on the cards. Default: Spanish.
- What goes on the back of a card. Default: the gloss or example line shown on screen, or "(no gloss on card)" when there is none; the skill never invents a translation.
- The public link for each lesson, for the video_link column. Default: the YouTube link if known, otherwise empty.
- The Vivu project to reuse, if the lessons are already indexed. Default: create a new private project.
Files and state
Keep everything in one working folder, vocab-deck/, next to the lessons. Run every command from the folder that contains vocab-deck/, so the paths below work as written; LESSON_FILE is always the path to one lesson file from there.
vocab-deck/
archive.txt yt-dlp download archive (Step 2, only when downloading)
config.json language, lesson folder, project_id, video_id to file map, public links
state.json completed steps, job_id, checked window keys (file + start_ms), swept files
results/ raw search results
frames/ start, middle, end frames per window; 0.5 s strips
read/ full frames each card was read from
sheets/ 2 s contact sheets per lesson (Step 6)
candidates.csv every window with its check result (true, duplicate, false positive)
flashcards.csv the deliverable
review_sheet.md rows to look at first, for the user to check
state.json records which steps finished, which windows were checked and which lessons were swept, so a rerun after an interruption reuses the saved job_id and raw file, skips checked windows, and never lists the same card twice (one row per lesson and front text).
Step 1: Check the Vivu connector and the setup
Goal: every requirement is present before anything is uploaded.
- Call vivu_get_account. If the tool does not exist, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. It must show can_create_projects: true. If a later write call fails with "has not granted vivu.write", ask the user to reconnect Vivu with write access.
- Run
ffmpeg -versionandffprobe -version. If either is missing, tell the user and stop. - List the lesson folder. Ask the user to confirm the lessons are their own videos. If students appear on camera in any lesson (common in classroom recordings, and often minors), ask whether those parts may be uploaded; without the students' or guardians' consent, leave those files out.
Asking these two questions was not exercised in our test run, which used public Creative Commons licensed lessons with only the teacher on camera.
Done when the connector shows write access, ffmpeg and ffprobe run, and the user has answered both questions.
Step 2: Get the lesson files
Goal: every lesson is a local mp4 file in the lesson folder.
If the user already has the exported files, skip to Step 3. If a lesson exists only on the user's own YouTube channel, download it on this computer (a residential IP; YouTube refuses cloud and datacenter IPs):
yt-dlp --js-runtimes node --restrict-filenames \
-f "bv*[height<=720]+ba/b[height<=720]" --merge-output-format mp4 \
--match-filter "duration<=1800" \
--download-archive vocab-deck/archive.txt \
-P "temp:SCRATCH_DIR" -P "home:LESSON_FOLDER" \
-o "%(id)s_%(title).60B.%(ext)s" --retries 5 \
"https://www.youtube.com/watch?v=VIDEO_ID"
VIDEO_ID is the 11 character ID from the lesson's link, LESSON_FOLDER the lesson folder, SCRATCH_DIR any folder outside it. 720p keeps card text readable at a fraction of the size of 1080p, and --restrict-filenames keeps names free of spaces and brackets so they match Vivu's names later. The ID at the start of the file name is what later rows use for video_link. If yt-dlp reports "HTTP Error 403: Forbidden", retry once with --extractor-args "youtube:player_client=web_embedded" added. The youtube-competitor-watch skill (https://vivu.ai/skills/youtube-competitor-watch) covers channel verification and download troubleshooting in more depth.
Done when every lesson is an mp4 in the lesson folder and ffprobe reads each one.
Step 3: Measure, price, and upload
Goal: the user approves the cost, and every lesson is ready in one private Vivu project.
- Measure each file and add up the seconds. LESSON_FILE is one file from the lesson folder; run it once per file:
ffprobe -v error -show_entries format=duration -of csv=p=0 LESSON_FILE
- Call vivu_get_usage for the plan and what remains this month, and show one table. The deck needs one precise search for the whole project, and a precise search uses 5 credits in total; with an optional control search that is an estimate of 10 credits per deck.
| These lessons | Plan allowance | Remaining | |
|---|---|---|---|
| Index minutes | measured total | from vivu_get_usage | from vivu_get_usage |
| Search credits | estimate | from vivu_get_usage | from vivu_get_usage |
For reference, Free has 20 index minutes a month and 50 search credits a month; Premium is $30 a month with 180 index minutes a month and 500 search credits a month. If the lessons do not fit, offer to index fewer lessons now and the rest next month, or to leave out a lesson the user says has no word cards, before suggesting a larger plan. Never drop a lesson the user asked for without saying so. 3. After a written yes, call vivu_list_projects and reuse the project the user named; otherwise call vivu_create_project with name "Vocab deck COURSE_NAME" (COURSE_NAME is the course or playlist name) and visibility "private". The default visibility is the whole organization. 4. Call vivu_open_upload_page with the project_id. The upload link expires in 180 seconds, so request it right before use and never paste it into a file or message. Give it to the user to open in their own browser and select the lesson files, or attach the files with a browser tool that can attach local files (Claude in Chrome takes at most 10 MB per upload call; larger files go through the user's own browser or the Vivu web app). Never split or recompress a lesson to fit, because the deck's timestamps must match the user's files. 5. Poll vivu_list_videos about every 30 seconds until every video shows ready. Vivu replaces spaces and brackets in file names with underscores; record in config.json which video_id belongs to which local file, matching on the YouTube ID or the lesson number in the name.
In our test run the upload went through the factory's own upload path, so handing the link to a user and the approval table were not exercised in our test run; ffprobe, vivu_get_usage and the ready check were.
Done when the user has approved the table and vivu_list_videos shows every lesson ready.
Step 4: Find the word card windows
Goal: one raw result file with every window Vivu thinks shows a word card.
Run one search over the whole project (tool names may carry a server prefix):
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| word_card | the few seconds one word card is on screen: a single Spanish headword or short noun phrase written out in full, either alone on a plain white card filling the screen or as a caption with its article over footage of the thing it names. Each card is its own moment, so return each card separately rather than one long stretch that covers many cards. Full sentences, fill-in-the-blank prompts with empty lines, title cards and homework slides are not word cards. | precise | 40 |
| control (optional) | a verb conjugation table on screen with rows for yo, tú, él, nosotros and ellos | precise | 10 |
Change "Spanish" to the user's language and describe the card style the user actually uses (a white box at the bottom, a corner card, a full screen slide), but never list the words: the point is to find cards the user does not remember. Mode is precise because only precise returns time windows; fast returns whole files with no reason. maximum_results 40 is about ten windows per lesson for four lessons and is also the ceiling on how many windows come back; raise it for more lessons. The control query looks for a card type the user says is not in these lessons; any result there is invented, which tells you how far to trust the main search. Run it only when the user does not use that card type. The control uses maximum_results 10 because every result it returns is a false positive, and ten slots are enough to see whether the search invents matches.
Call vivu_search_videos with project_id, query, mode and maximum_results, then call vivu_get_search_results with the job_id until complete is true. Each call can wait up to 45 seconds, so a pending search is not a stalled one. Save the completed result as vocab-deck/results/word_card.json and the job_id in state.json. Show the result page link in the reply only; it expires after four hours, so it never goes into the CSV, the review sheet or config.json.
The chain: this search narrows each lesson to the stretches with cards, Step 5 throws out windows without a card, and Step 6 reads the words and sweeps the gaps. There is no spoken counterpart to this search: the words on the card are what the deck needs, and search over non English speech was not tested.
Done when vocab-deck/results/word_card.json exists and holds the completed result.
Step 5: Check every window
Goal: every window is marked true, duplicate or false positive from frames of the user's file.
For each window, extract a frame near the start, the middle and the end. SECONDS is a time in seconds inside the window, LESSON_FILE the matching local file, OUT the frame path without the extension, such as vocab-deck/frames/pJd9_049_start:
ffmpeg -v error -ss SECONDS -i LESSON_FILE -frames:v 1 -q:v 3 OUT.png
Look at all three. A window is true when at least one frame shows a word card or word caption. It is a duplicate when it only repeats cards already covered (many lessons have a review pass that shows the same captions again; keep it, it can confirm a card the first pass window missed). It is a false positive when it shows only the teacher, a title or homework card, a full example sentence that is not a card, or a fill-in-the-blank prompt. Count the false positives and tell the user. Record every window in candidates.csv and its key in state.json.
Done when every window in the raw file has a judgment in candidates.csv and the user has seen the count of false positives.
Step 6: Read each card and sweep for missed cards
Goal: every card the sweep shows is read from a full frame, and every lesson has been swept.
- Inside each true window, make a 0.5 s strip so each card shows up at least once. START and END are the window bounds in seconds:
ffmpeg -v error -ss START -to END -i LESSON_FILE -vf "fps=2,scale=320:-2,tile=6x5" -frames:v 1 vocab-deck/frames/STRIP.png
STRIP is a name for this strip, such as the lesson ID plus START (pJd9_049). A strip holds 30 frames (15 seconds); for longer windows run it again from START plus 15. Vivu returns a time range that contains the cards, not an exact frame, and full screen flashcards that change every few seconds can come back as one long window over many cards. 2. Sweep every lesson, including those with no window at all, with 2 s contact sheets in 200 second chunks (one sheet for a whole file can silently drop frames). CHUNK_START is 0, 200, 400 and so on:
ffmpeg -v error -ss CHUNK_START -t 200 -i LESSON_FILE -vf "fps=1/2,scale=320:-2,tile=10x10" -frames:v 1 vocab-deck/sheets/LESSON_CHUNK.png
LESSON_CHUNK is the lesson ID plus CHUNK_START (pJd9_0000). Each tile is 2 seconds after the one before it. Mark every card the windows did not cover; those rows get status "sweep". 3. For every card, extract one full size frame where the card is fully shown (the gloss revealed, the fade finished) with the single frame command from Step 5 into vocab-deck/read/, and read the front, the article, the accents, inverted punctuation and the gloss or example line from that frame. Read from the full frame, not from a strip tile: small tiles hide accents. Copy the text exactly as shown, capitals included; when the card itself is cut off or never flipped, copy what is there and mark the row UNCERTAIN with the reason.
Done when every card the windows and the sweep show has a read frame and every lesson has been swept.
Worked example from our test run
In our test run on a test corpus of 4 public Creative Commons lessons by one teacher (28.3 minutes; word cards in a flashcard app, captions over objects and captions over driving footage, plus a distractor lesson with only story sentences and a dictation), every card was listed from contact sheets before any search. The first wording returned 8 windows, 6 real and 2 false: an example phrase over a soap bottle and a fill-in-the-blank quiz frame. The final wording in the Step 4 table, settled after 2 rewordings on the same corpus (an earlier, interrupted run on the same corpus also tried wordings that were not recorded), returned 16 windows and none was false; several of them only repeated cards from the lesson's review pass, and 11 cards were on screen in no window. The full screen flashcard lesson still came back as long windows (the longest 250 seconds), and the 11 missed cards sat between those windows or were short captions over moving footage; the Step 6 sweep showed all 11 of them, but our list of cards was made from the same Step 6 contact sheets, so the sweep was not tested against an independent count; a card shown for less time than the gap between two tiles can fall between them. The control search returned 0. Reading from full frames gave the accents right; Vivu's reason text can drop punctuation, such as the closing exclamation mark of "¡Más jabón!", so it is not used for spelling. The time from upload to ready was not recorded in our test run, so there is no measured wait to quote.
Step 7: Write the deck and the review sheet
Goal: flashcards.csv and review_sheet.md exist and the user has approved the columns.
Show the user one sample row and the column mapping before writing every row:
front,back,lesson,source_file,on_screen,frame,video_link,status
el día festivo,holiday,Lesson 4.2.1,LESSON_FILE_NAME.mp4,05:20,vocab-deck/read/LESSON_320.png,https://www.youtube.com/watch?v=VIDEO_ID&t=320,verified
| Column | Source | If unavailable |
|---|---|---|
| front | the card, read from the full frame in Step 6 | UNCERTAIN in status |
| back | gloss or example line on the card | "(no gloss on card)" |
| lesson | the lesson title card or file name | file name |
| source_file | local file name | none |
| on_screen | first second the card is fully shown, MM:SS | none |
| frame | path of the read frame | none |
| video_link | the user's public link plus &t= seconds | empty |
| status | verified (inside a checked window), sweep (contact sheet only), plus UNCERTAIN and why | none |
Write one row per card per lesson, in order of appearance; drop duplicates from review passes. Anki and Quizlet read the first two columns as front and back; the rest are notes for the creator. Write review_sheet.md with the rows to look at first (UNCERTAIN rows, cards cut off or never flipped, example sentences used as fronts) and what was left out on purpose (example phrases, quiz blanks, title cards). Report the real numbers: how many rows are verified and how many came from the sweep.
Done when the user has approved the sample row and both files exist with one row per card.
Step 8: Hand over the deck
Goal: the user has the files and knows what to check.
Tell the user where flashcards.csv and review_sheet.md are, the counts of verified, sweep and UNCERTAIN rows, and the result page link from Step 4 (labeled as expiring after four hours). The user checks the review sheet, imports the CSV into Anki or Quizlet and shares the deck with students; the skill does not send, post or upload the deck anywhere.
Handing over to a user was not exercised in our test run.
Done when the user confirms they have both files.
Compliance
- Use only the user's own lessons. Have the user confirm this before Step 2; downloading other people's videos may conflict with YouTube's Terms of Service.
- Students on camera, often minors: upload those parts only with the students' or guardians' consent, otherwise leave the files out. Ask before Step 3.
- The lessons stay in the user's Vivu project until the user deletes them. Create the project as private; the default visibility is the whole organization. The skill never deletes projects or videos.
- The skill reads text on screen and nothing else: no subtitles delivered, no editing, no face or logo recognition.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) a window shows a full example phrase or a fill-in-the-blank prompt, not a card | a loose wording matched any Spanish caption; the first wording in our test run had 2 such false windows | use the Step 4 wording that excludes sentences and blanks; Step 5 throws such windows out |
| (observed) one window covers minutes of flashcards | full screen cards that change every few seconds come back as one stretch | make the Step 6 strips across the whole window; do not read only the check frames |
| (observed) cards between two long windows, or short captions over footage, are in no window | precise returns time ranges, not every card; 11 cards were missed in our test run | the Step 6 contact sheet sweep, every lesson |
| (observed) the reason text misquotes the caption, such as "¡Más jabón (Tenemos mucho.)" without the closing exclamation mark | reason text paraphrases | read every word from a full frame |
| (observed) yt-dlp fails with "HTTP Error 403: Forbidden" | YouTube refused the default player client | retry once with the web_embedded player client, as in Step 2 |
| accents or a capital letter are wrong in the deck | read from a small strip tile instead of a full frame | reread from the full frame in vocab-deck/read/ |
| "has not granted vivu.write" | Vivu connected read only | the user reconnects Vivu with write access |
| upload page asks to sign in or shows an error | the one time upload link expires after 180 seconds | request a new link right before opening it |
| a file is rejected by the browser upload tool | file above the tool's size limit | the user adds that file in the Vivu web app; never split or recompress |
| a result's file name does not match the local file | Vivu normalized the file name | match on the YouTube ID or lesson number inside the name |
| a contact sheet ends early with empty tiles | one sheet for a whole long file drops frames | make sheets in chunks as in Step 6 |
| the control search returns a card type the lessons do not have | search ranks the most similar thing instead of returning nothing | treat main search results as candidates only and rely on Step 5 and the sweep |