Tutorial back reference table

---
name: tutorial-back-reference-table
description: "Find which of your past tutorials showed each panel or menu, and at what second, with Vivu; get a checked table and timestamp links for your description. Use when a new episode reuses screens."
---

Back reference timestamps from your past tutorials

This skill takes the screens a new tutorial refers back to (a settings panel, an open menu, a dropdown list, a preferences page) and the exported files of the past episodes the creator picks by title (the same cut that was published, so a second in the file is the same second in the public video), and returns a back reference table: for each screen and each episode where it was found and checked, the minute and second, the frame it was checked on, the panel title read from that frame, a link to the creator's own public video at that second, and a line ready to paste into the description or a pinned comment. Claude measures the episodes, compares each length with the public video's, prices them against the user's Vivu plan, uploads them to a private Vivu project, runs one precise search per screen, cuts a half second contact sheet for every returned window, reads the title from a full frame, and writes the table. The creator checks it and posts the links.

The value is in what only the picture shows. Narration says "click here" or "open this", and titles and chapter names stop at the topic ("render output settings"); which panel or menu was on screen, and the second it opened, is only in the video. Vivu's search only suggests where to look. In our test run every window returned for the final wordings showed the screen that was asked for, but when the File Format list opened several times in a single episode Vivu returned one wide window around the first openings and skipped three later brief ones, and it missed a brief Add menu in a whole episode. So every window stays a candidate until a contact sheet and a full frame show the screen, the table gives one checked time per screen per episode, and a screen with no row in an episode may still appear there.

When to use

Use when a creator asks "which of my old videos showed the export settings?", "find where I demoed these panels before so I can link them", "build the back reference links for my new episode", or "make timestamp links to my earlier tutorials for the description".

Not for these:

1. A one off question about one video ("when does the preferences window open in this file?"): search Vivu directly and look at the frames.
2. A whole channel at once. Pick the five to eight episodes whose titles touch the screens (Step 2); indexing dozens of episodes does not fit a monthly plan.
3. Finding what was said (a phrase, an explanation): use the captions or transcript. This skill finds what was on screen.
4. Chapters, cuts, clips or captions. Vivu only finds moments; editing stays in the creator's editor.
5. Other people's videos or YouTube links. The skill works on the creator's own recordings only.

Working principles

1. Report measured numbers, not estimates. When a number is an estimate, say so.
2. Nothing is verified until it has been checked against the source video. Vivu's windows are candidates; a time enters the table only after its contact sheet shows the screen and its title has been read from a full frame.
3. Stop and tell the user when a required capability or tool is missing. Do not guess around it.
4. Ask the user before anything that is expensive to redo (the episode list and its index minutes, before upload; a rerun of a full search) and before writing the full table (one sample row first). The skill posts nothing; the creator pastes the links.
5. Titles in the table come from the frame, never from Vivu's reason text, which can name controls that have already scrolled off screen.
6. A missing row is not proof. Search can merge repeated openings into one window and skip brief ones, so the table and the summary never say an episode does not show a screen.

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.

This skill needs Claude Code on the user's computer (the terminal or the Code tab of Claude Desktop), because it reads local files and runs ffmpeg. Claude on the web and cloud sessions cannot reach the files. It downloads nothing, so no residential IP is needed. Nothing recurs, so no scheduler is involved; run it once per new episode.

Inputs to collect

Ask for anything missing, most important first.

1. SCREENS: the screens the new episode refers back to, usually six to ten. For each one, its name as it appears on screen (the panel title, the menu name, the popup heading) and two to four labels visible at its top. Required.
2. EPISODES_DIR and the episode list: the folder with the exported files of the past episodes as they were published, and for each episode its file, its title, its public address and its length as the public video page shows it. Required. If the user is unsure which episodes to include, Claude suggests some from the titles in Step 2.
3. WORK_NAME: a short name for the working folder and the Vivu project. Default: the new episode's working title.
4. LINK_OFFSET: how many seconds before the checked frame each link lands, so viewers see the click that opens the screen. Default: 1.
5. The line format for the description. Default: "SCREEN, shown in EPISODE_TITLE at M:SS: URL".

Files and state

Keep everything in one working folder next to EPISODES_DIR:

backref-WORK_NAME/
  config.json            screens with query and maximum_results, Vivu project id, LINK_OFFSET, line format
  episodes.csv           file, listed_name, title, public_url, public_length, duration_s, video_id
  results/               one JSON per screen: search results without the result page link
  sheets/                contact sheets, one set per checked window
  read/                  full frames the titles were read from
  candidates.csv         every window Vivu returned, with its check outcome
  back_reference.csv     one row per screen per episode with a checked time
  description_block.txt  the lines to paste
  state.json             steps done, files uploaded, screens searched with job ids, windows checked

The commands in Steps 3 and 6 run from the folder that holds both EPISODES_DIR and backref-WORK_NAME/, so their relative paths resolve.

A rerun reads state.json first and skips finished steps: a file marked uploaded is not uploaded again, a screen with a saved result is not searched again, and a window with a recorded outcome is not checked again. A later episode gets its own working folder; if it draws on the same past episodes, copy the project id from the earlier folder's config.json and reuse that Vivu project instead of uploading them again.

Step 1: Check the Vivu connector and the setup

Goal: confirm every requirement before spending anything.

1. 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. If the account does not show can_create_projects: true, or a later write call fails with "has not granted vivu.write", ask the user to reconnect Vivu and allow write access, then stop until they have.
2. Run ffmpeg -version and ffprobe -version.
3. List EPISODES_DIR and run the ffprobe length command on one file.

Done when vivu_get_account shows can_create_projects: true, ffmpeg and ffprobe print their versions, and ffprobe prints a length for a file in EPISODES_DIR.

Step 2: Pick the screens and the episodes

Goal: a short list of screens and a short list of past episodes worth indexing.

1. Write each screen into config.json with its on screen name and the labels at its top, for example "Render Engine dropdown: Eevee, Workbench, Cycles". The search matches words and shapes that are on screen; values that change from episode to episode (a resolution, a file name) are poor anchors (Step 5 says why).
2. Pick episodes by title. List the titles in EPISODES_DIR (or the ones the user pastes from their channel) and keep those whose topic touches the screens, five to eight of them. Titles are text, so this costs nothing; indexing every episode would.
3. Write episodes.csv with file, title, public_url and public_length (the length the public video page or YouTube Studio shows, as M:SS). The file is the exported episode that was published, not the raw recording, because every link takes its second from the file. Add listed_name: the file name with spaces and punctuation replaced by underscores (hyphens and the dot before the extension stay), because that is how Vivu lists names. If a name still does not match after upload, Step 4 matches by length instead.
4. Confirm the Compliance items with the user.

In our test run the screens came from an assumed outline and the episodes were picked by title from the series; confirming both with a creator was not exercised in our test run.

Done when the user approves the screen list and episodes.csv.

Step 3: Measure the episodes and price them

Goal: an indexed set the user's plan can pay for, approved before upload.

1. Run the ffprobe length command on every file in episodes.csv and write duration_s.
2. Compare duration_s with public_length for every episode. The page shows whole seconds, so up to a second of difference is rounding. If they differ by more than 1.5 seconds, stop for that episode and tell the user: its file is not the cut that was published (a raw recording, or an export made before a later edit), so every link from it would land on the wrong second of the public video. Ask for the exported file that was published. A creator who no longer has it can download their own upload from YouTube Studio (Content, the video's Options menu, Download). If neither is possible, leave the episode out and say which one. Matching lengths do not prove the same cut, which is why Step 7 asks the user to open the sample row's link.
3. Call vivu_get_usage and show one table:

Plan facts: Free is $0 a month with 20 index minutes a month and 50 search credits a month; Premium is $30 a month with 180 index minutes and 500 search credits. A precise search uses 5 credits in total. On Free, the minutes cover about two ten minute episodes a month (estimate), so a Free user starts with the two episodes most likely to show the most screens.

4. If the episodes do not fit, offer levers in this order: drop the episodes whose titles are furthest from the screens, split the list across two months, and only then move to a larger plan. Never drop an episode the user asked for without saying which one, and never trim or recompress a file to save minutes.

The account used in our test run returns no allowance figures, so the comparison with a real plan and the user's approval were not exercised in our test run.

The files in our test run were the public videos themselves, so their seconds matched the public videos by construction; comparing duration_s with public_length, a file cut differently from its public video and the YouTube Studio download were not exercised in our test run.

Done when every episode left in episodes.csv has a duration_s within 1.5 seconds of its public_length, the user approves the episode list and its index minutes, and config.json records both.

Step 4: Upload and index

Goal: every approved episode indexed in a private Vivu project.

1. Call vivu_list_projects and reuse a project named "Back references WORK_NAME" if one exists. Otherwise call vivu_create_project with that name and visibility "private". The default visibility is organization, which shows the project to everyone in the user's Vivu organization, and tutorial recordings can show email addresses, file paths or keys in a corner of the screen.
2. Call vivu_open_upload_page with the project ID immediately before uploading. The link expires in 180 seconds and works once, so never post or store it. Give it to the user to open in their own browser and select the files, or open it in a browser tool that can attach local files. Claude in Chrome accepts at most 10 MB per upload call and screen recordings are usually larger, so they normally go through the user's own browser or the Vivu web app. Never split or recompress a file to fit.
3. Poll vivu_list_videos until every file shows ready. Match each Vivu file name to episodes.csv by listed_name. When a name does not match (file names taken from episode titles often carry commas, apostrophes, # or &), match by length instead: vivu_list_videos reports duration_ms, so compare it with duration_s in milliseconds. Record each video_id in episodes.csv and state.json.

In our test run the 6 episodes (32.81 minutes) were all ready 574 seconds after the upload started. Each duration_ms equaled the ffprobe length of its file, and the hyphens in our file names were kept, so every name matched listed_name and the length fallback was not exercised in our test run. They went through the upload page with an automated browser, so opening the link in the user's own browser was not exercised in our test run.

Done when every file in episodes.csv shows ready and has a video_id.

Step 5: Search each screen

Goal: a saved list of candidate windows for every screen.

One precise search per screen, side by side, because each screen is its own row group in the table. The chain behind each row: the precise search suggests windows, the contact sheet finds the tile where the screen is open, the full frame confirms its title, and the table takes that second. Every search is precise because only precise returns a time window; fast returns whole files with an empty reason, and the episodes are already a chosen set. There is no switch to speech: narration names a panel before or after it opens, and a back reference link needs the moment it is on screen.

These are the wordings from our test run, on tutorials for one 3D program. Write the user's queries the same way: the screen's on screen name, where it is, and two to four labels visible at its top.

The file_format_menu and dimensions_panel wordings were tuned on our test corpus, each after 2 rewordings on the same corpus; the others are first wordings. Name labels, not values: a wording that named the panel's field values matched windows where the panel had scrolled and those fields were gone, while the reason still described them. A new wording for the user's software is untested until its first windows have been through Step 6.

maximum_results is 10 because five to eight episodes rarely show one screen in more than a few places each, and it is also the ceiling on how many windows come back. If a search returns exactly its maximum_results, tell the user and, once they agree, run it again with 30 (5 more credits, estimate).

That rerun with a larger maximum_results was not exercised in our test run.

How far to trust the searches: with the final wordings, the windows that came back on our test corpus showed the screen asked for, including when a neighboring panel or menu looked much the same, but the searches did not return every time a screen was opened, and brief or repeated openings were the ones left out. Treat recall from picture search as weak: every window goes through Step 6, and a missing row proves nothing.

Run each query with vivu_search_videos (project_id, query, mode, maximum_results). It returns a job ID. Call vivu_get_search_results until complete is true; each status call can wait up to 45 seconds, so a pending search is not a stalled one. Save each completed result as results/FIELD.json without its result_page_url field, and record the job_id in state.json. Show the Vivu result page link in the live reply only; it expires after four hours, so it never goes into a saved file or the table.

Done when every screen has a completed result saved in results/, and any search that returned exactly its maximum_results has been run again with the user's approval or is marked capped in state.json.

Step 6: Check every candidate on a contact sheet and read the title from a full frame

Goal: for each screen and episode, the earliest window that really shows the screen, with its title read from a full frame.

Sort each screen's windows by episode and start_ms (Vivu does not return them in time order). For each screen and episode, take the earliest window and cut contact sheets from the local file at two frames a second:

mkdir -p "backref-WORK_NAME/sheets" "backref-WORK_NAME/read"
ffmpeg -v error -y -ss START -to END -i "FILE" -vf "fps=2,scale=480:-2,tile=5x4" "backref-WORK_NAME/sheets/FIELD_STEM_STARTMS_%02d.png"

FIELD is the screen's field name, FILE the local episode file (EPISODES_DIR/ followed by its file name), STEM the file name without its extension, STARTMS the window's start_ms, and START and END the window's start_ms and end_ms divided by 1000. Keep the double quotes around FILE and every backref-WORK_NAME path in these commands: episode file names and the default WORK_NAME often contain spaces, brackets or plus signs, which the shell would otherwise split or expand (zsh stops on brackets with "no matches found"). Each sheet holds 20 tiles covering about 10 seconds; tile k on sheet n (both counted from 0, left to right and top to bottom) is at roughly START + 10 * n + k / 2 seconds. ffmpeg numbers the sheet files from 01, so the file ending _01 is sheet 0, _02 is sheet 1, and so on. The -y flag lets a rerun overwrite a sheet instead of stopping.

1. Look at every sheet of the window and find the first tile where the screen is open: the dropdown list, the menu, the popup or the panel, recognizable by its shape and layout. Tiles are too small to read, so the shape only says where to look.
2. Extract a full frame half a second after that tile's time, T:

ffmpeg -v error -y -ss T -i "FILE" -frames:v 1 "backref-WORK_NAME/read/FIELD_STEM_TMS.png"

TMS is T in milliseconds. A tile can show a frame slightly later than its computed time, so the frame at the tile's own time often still shows the screen closed. If the full frame does not show the screen, add half a second to T and extract again, up to the end of the window. 3. Read the title and the labels from the full frame and compare them with the screen asked for. A neighboring panel, another dropdown in the same panel or a different menu is a rejection, whatever the reason says. If the title is too small to read (a recording made at a high resolution and scaled down, or a zoomed out screen), crop the quarter that holds it and enlarge it:

ffmpeg -v error -y -ss T -i "FILE" -frames:v 1 -vf "crop=iw/2:ih/2:X:Y,scale=iw*2:-2" "backref-WORK_NAME/read/FIELD_STEM_TMS_zoom.png"

X is 0 for the left half or iw/2 for the right half, Y is 0 for the top half or ih/2 for the bottom half. This crop command was not exercised in our test run: every title there could be read on the full frame, and the earlier crops used to settle doubtful frames were cut differently. 4. A window whose tiles and frames never show the screen is rejected: write what they show instead (for example "Edit menu open, not the Render menu") and move on to the next window of that screen in that episode. 5. Once a screen has a checked time in an episode, its later windows in that episode still get a contact sheet, so candidates.csv says for every window whether the screen is in it ("later window, screen shown" or "rejected"). They need no full frame, because the table takes one time per screen per episode. Rejected windows stay in candidates.csv with their note and never enter the table. 6. If a window's reason describes a quick dropdown but no tile shows it, the dropdown may have opened between tiles. Run the sheet command on the few seconds around it with fps=10 instead of fps=2 before rejecting it. (Our test looked at such a moment on frames cut a tenth of a second apart from a crop of the panel; this exact fps=10 command was not exercised in our test run.)

Record every window in candidates.csv (screen, episode, start and end, outcome, sheets, frame, note) and in state.json.

Worked example from our test run

The test corpus was public: 6 official Blender tutorials published under a Creative Commons license (32.81 minutes) from one series, so neighboring panels and menus of the same program appear throughout. The recordings were full screen at 1080p and were indexed at 720p, where panel titles are small. The local files were the public videos themselves, so a second in a file was the same second in its public video by construction; a local file cut differently from its public video was not exercised in our test run.

Before any search the screens and their neighbors were marked by hand on coarse contact sheets. After the search, frames inside returned windows showed brief openings those marks had missed, and part of one stretch marked beforehand as a neighboring screen (the Output panel with the Dimensions panel collapsed or scrolled away) showed the full Dimensions panel on its frames; both were added to the marks. 5 of the 27 windows below, in the Render Engine, Render menu, Add menu and Dimensions results, match only these later marks. Each of them showed the screen asked for on its frames, so they count as real here; judged against the marks made before the search alone, they would have counted as false. The missed counts below cover only what the marks or a search caught.

1. Render Engine dropdown: 4 returned, 4 real, 0 false, 1 missed. The missed one was a quick reopening that no window covered.
2. Render menu: 8 returned, 8 real, 0 false, none missed.
3. File Format list, with the wording in the table after 2 rewordings on the same corpus: 1 returned, 1 real, 0 false, 3 missed. The list opened several times in a single episode. Vivu returned one window, 25.2 seconds wide, that covered the earlier openings, and 3 later, shorter openings in the same episode were missed with all three wordings. By the recall formula of our test (true windows against true windows plus missed openings) that is 1 of 4, although the one window held more than one opening; counted per episode, which is what the table uses, the only episode with this list got its row.
4. Dimensions panel, with the wording in the table after 2 rewordings on the same corpus: 6 returned, 6 real, 0 false, none missed. The previous wording named the panel's field values and returned 7 windows, 5 real and 2 false; in the false ones the resolution fields had scrolled off screen while the reason still said they were visible.
5. Metadata panel: 1 returned, 1 real, 0 false, none missed. It appears in a single episode, so this is a small sample.
6. Keymap page of the preferences: 1 returned, 1 real, 0 false, 1 missed, a second visit to the same page later in that episode.
7. Add menu: 4 returned, 4 real, 0 false, 1 missed. The missed one was the only Add menu in the Right Click Select episode, a brief opening, so that episode got no Add menu row although it shows one.
8. Light properties: 2 returned, 2 real, 0 false, none missed.
9. Across the final wordings that is 27 windows, all 27 real by their frames, 5 of them only after the later marks described above. No window came back for a neighboring screen on its own (another dropdown in the same panel, the Edit and View menus, the right click menu, other preference pages, other property tabs): the Add menu window that ran on into a right click menu also held the Add menu, and the window inside the stretch first marked as a neighbor showed the full Dimensions panel.
10. The 6 episodes were ready 574 seconds after the upload started, and the eight searches with the final wordings completed 98 to 181 seconds after they were submitted; they were polled one after another, so the search times are upper bounds.
11. Every window of the final wordings got a contact sheet, and the earliest window of each screen in each episode also got a full frame. Each of those earliest windows showed the screen on its sheet and its full frame, and every title could be read on the full 720p frame without cropping. In one later window the Render Engine list was open so briefly that it showed on no tile of the half second sheet, only on frames a tenth of a second apart, which is what the fps=10 variant in Step 6 is for. Several frames taken at a tile's computed time showed the menu still closed, which is why Step 6 extracts the frame half a second later.

Done when every window in results/ has a line in candidates.csv, and every screen and episode with a window has either a checked time or only rejected windows.

Step 7: Write the table and the lines to paste

Goal: a table the creator can check against their own videos and paste from, without opening Vivu.

Show the user one sample row and the field mapping. Ask them to open the sample row's link: the public video should show the screen at that second, or open it within a second or two (LINK_OFFSET). Wait for an OK before writing the rest:

screen,episode_file,episode_title,mm_ss,seconds,frame_path,panel_title_read_from_frame,public_url_with_t,description_line,status,coverage_note
File Format list,tut_Gifto41kpJw.mp4,Render Output Settings,01:34,94,read/file_format_menu_tut_Gifto41kpJw_95300.png,"File Format popup: Image column (BMP to Targa Raw) and Movie column (AVI JPEG, AVI Raw, FFmpeg video)",https://www.youtube.com/watch?v=Gifto41kpJw&t=94,"File Format list, shown in Render Output Settings at 1:34: https://www.youtube.com/watch?v=Gifto41kpJw&t=94",VERIFIED,"This episode may also show this screen earlier or later than this time, and an episode with no row for this screen may still show it; search did not return every opening"

The row above is from our test run; the user's rows carry their own screens, files and addresses.

If the link lands somewhere else, stop: that episode's file is not the cut that was published, so none of its rows can be used. Tell the user, and go back to Step 3 for that episode with the exported file that was published; uploading it again costs index minutes, so it needs the user's approval. The length check in Step 3 does not catch an edit that kept the length, so also ask the user to open one link from each other episode before posting.

Write back_reference.csv with one row per screen per episode that has a checked time, sorted by screen and then by time. A screen with no checked time anywhere gets one NOT FOUND row with the note "no checked window; this does not prove the episodes never show it". Write description_block.txt with the description_line of every VERIFIED row, grouped by screen. Both use the creator's own public addresses, never a Vivu result page link, so they keep working after that link expires.

Then tell the user, per screen, how many windows Vivu returned, how many showed the screen and how many were rejected, which episodes have a row and which searched episodes do not, and say plainly that an episode without a row may still show the screen, and that an episode with a row may show it again at other times. If the user remembers a screen in an episode without a row, cut a contact sheet over the minutes they remember with the Step 6 command; it costs no credits.

The table and the lines are the creator's to check and post. If the user asks Claude to put them somewhere (a video description, a pinned comment, a document), name the destination, show the rendered lines and wait for a yes before each write.

In our test run the table, the lines and candidates.csv were written from the dry run's windows and frames; showing the sample row to a creator, opening its link and posting the lines were not exercised in our test run. Every screen had a checked time in some episode, so the NOT FOUND row was not exercised in our test run, and only watch?v= addresses were used, so rewriting other YouTube address forms and Vimeo links was not exercised in our test run either.

Done when back_reference.csv and description_block.txt exist, every VERIFIED row has a frame in read/, the user opened the sample row's link, saw the screen there and approved the sample row and the mapping, and state.json marks the run done.

Compliance

1. Use only the creator's own recordings. Do not import other people's videos or YouTube links; the links in the table point at the creator's own public videos. Confirm this before Step 4.
2. If an episode has a guest on camera or on a call, the guest's consent to uploading the recording to a third party service is needed. If a child appears, upload that episode only with a parent's or guardian's consent; otherwise leave it out. Confirm before Step 4.
3. Screen recordings can show email addresses, file paths, API keys or client files. Ask the user to check the episodes before upload, and create the project as private; the default is visible to the whole Vivu organization.
4. The videos stay in the user's Vivu project until the user deletes them. Delete videos or the project only when the user asks, and confirm first.
5. The skill writes only local files. It does not edit video descriptions, post comments or publish anything; any such write goes through the approval in Step 7. It does no face, logo or identity recognition.

Known failure modes