---
name: walkthrough-chapter-list
description: "Turn your own gameplay walkthrough episodes into YouTube description chapters with Vivu: area and boss names read from the game's title cards. Use before publishing a long walkthrough."
---Chapter list from your gameplay walkthroughs
This skill takes two or three walkthrough or long play episodes that the user recorded and exported, and returns chapter text for each video description plus a check table. Claude measures the episodes, prices them against the user's Vivu plan, indexes them in a private Vivu project, runs one precise search for the game's area name cards and one for boss name cards, checks every window against frames from the user's own file, reads each name off a full frame, sets each chapter start from a half second contact sheet, and writes chapters that start at 00:00 with one line per area or boss. The creator checks the table and pastes the chapters.
The names are what a transcript cannot give. Creators talk over play about everything except where they are, and the game shows the area or boss name for a few seconds as stylized title text, often in the same corner where item pickups and character names also appear. Chapters written from what was said land on activities like "combat and bench rest" instead of the area the player walked into, and captions misspell made up game names. Vivu narrows each episode to a handful of windows around title cards, Claude reads the frames, and a window that does not show the game's own area or boss title stays out of the chapters.
When to use
Use when a creator says "make chapters for this walkthrough", "list the areas and bosses in these episodes with timestamps", "I need the description chapters for parts 4 to 6" or "YouTube's auto chapters are wrong, build them from the game's area names".
Not for these:
- Picking funny or exciting moments to cut into shorts: use the stream-vod-clip-shortlist skill.
- A tournament or league broadcast with map strips and result pages: use the tournament-map-chapter-sheet skill if it is available to you, or search Vivu directly.
- Software tutorials and screen recordings: use the tutorial-back-reference-table skill.
- A video the user did not make, or a link to someone else's YouTube or Twitch video. This skill works on the creator's own local files only.
- A one off question about one moment in one episode: search Vivu directly.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- Nothing is verified until it has been checked against the source. A Vivu window is a candidate until a frame from the user's file shows the game's own area or boss title inside it. Names come from full frames, never from Vivu's reason text, because reason text paraphrases and has misread stylized text in other games.
- 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 (indexing the episodes) and before writing the final chapters (one sample row and the field mapping first). The skill never pastes into YouTube itself.
- Report the real count. If an episode has fewer cards than the user expects, say so; do not fill gaps with guessed areas.
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 user reconnects Vivu and allows write access |
| A shell on the user's computer with ffmpeg and ffprobe | measure the episodes, cut frames and contact sheets | ffmpeg -version, ffprobe -version |
| The episodes as local video files, exactly as uploaded or to be uploaded to YouTube | chapter times must match the published video, and the frames come from these files | ffprobe -v error -show_entries format=duration -of csv=p=0 EPISODE prints a duration for each |
| An upload path | move the episodes into Vivu | vivu_open_upload_page plus the user's own browser, or a browser tool that can attach local files |
This skill needs Claude Code on the user's computer (the terminal or the Code tab of Claude Desktop), because it reads local video 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 again for the next batch.
Inputs to collect
Ask for anything missing, most important first.
- EPISODES: the local files, two or three per run. Required.
- EP_LABELS: a short label per file for the table. Default: EP01, EP02 in the order given.
- INTRO_TITLE: the name of the 00:00 line. Default: "Intro".
- REPEATS: whether a return to an area already listed gets its own chapter. Default: yes, marked "(return)"; a boss retry after a death never does.
- BOSS_PREFIX: text before boss names. Default: "Boss: ".
Files and state
Keep everything in one working folder:
walkthrough-chapters/
config.json episodes, labels, INTRO_TITLE, REPEATS, BOSS_PREFIX, Vivu project id
video/ the episode files (copies or links to the user's masters)
results/ search results as JSON, without the result page link
frames/ frames cut inside each window
sheets/ half second and two second contact sheets
candidates.csv every window Vivu returned, what the frames showed, the verdict
chapter_check.csv one row per chapter with its frame, for the creator to check
chapters.txt the chapter text per episode, ready to paste
state.json steps done, video ids, job ids, windows checked, sheets swept
Run the commands from inside walkthrough-chapters/ so the relative paths resolve.
A rerun reads state.json first and skips finished steps: episodes marked uploaded are not uploaded again, a search with a saved result is not run again, a window with a verdict in candidates.csv is not checked again, and a swept sheet is not swept again.
Step 1: Check the Vivu connector and the setup
Goal: confirm every requirement before spending anything.
- 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 showcan_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. - Run
ffmpeg -versionandffprobe -version, then create the folders:mkdir -p walkthrough-chapters/video walkthrough-chapters/results walkthrough-chapters/frames walkthrough-chapters/sheets. - Ask whether the creator is under 18 (Compliance 2) and confirm the files are their own recordings.
In our test run vivu_get_account returned can_create_projects: true, and ffmpeg and ffprobe ran in the later steps.
Done when vivu_get_account shows can_create_projects: true, both tools print their versions, and the user has answered the two Compliance questions.
Step 2: Gather the episodes and measure them
Goal: the episode files in video/ with simple names and a measured length.
- Copy or link each file into video/ with a name made of the label and the original name, using only letters, digits, underscores and hyphens (EP is the label, NAME the file name):
cp "EPISODE" video/EP_NAME.mp4. Vivu replaces spaces and punctuation in file names with underscores, so simple names match back without guessing. - Measure each one:
ffprobe -v error -show_entries format=duration -of csv=p=0 video/EP_NAME.mp4. - Confirm each file is the exact cut that is or will be on YouTube. If the published video has an extra intro or a trimmed start, ask for the offset in seconds and record it in config.json, because every chapter time is added to it.
In our test run Vivu's video duration matched ffprobe for both files.
Done when video/ holds every episode and config.json lists each with its duration.
Step 3: Price, upload and index
Goal: the episodes indexed in a private Vivu project, with the user's approval of the cost.
- Call vivu_get_usage and show one table:
| This batch | Plan allowance | Remaining this month | |
|---|---|---|---|
| Index minutes | sum of durations / 60 | from vivu_get_usage | from vivu_get_usage |
| Search credits | 10 for the two searches in Step 4, plus 5 for any lookup in Step 6 (estimate) | from vivu_get_usage | from vivu_get_usage |
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. Two 40 minute episodes are more than a Free month, so a Free account fits about one short episode.
- If the batch does not fit, offer the levers in this order: index fewer episodes this month (the rest wait for the next batch), then move to a larger plan. Never cut or recompress an episode to save minutes; the chapters must match the full published video.
- Wait for the user to approve the minutes and credits before creating a project or uploading.
- Call vivu_list_projects and reuse a project named "Walkthrough chapters CHANNEL" (CHANNEL is the user's channel or series 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.
- 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 an episode is far larger, so episodes normally go through the user's own browser or the Vivu web app. Never split or recompress a file to fit.
- Poll vivu_list_videos until every episode shows ready. Match each one to its file by name and record the video ids in state.json.
In our test run both episodes were ready about 8.8 minutes after the upload started (an upper bound from polls). The account used in our test run returns no allowance figures, so the plan table and the user's approval were not exercised in our test run. The files 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 the user approved the cost before the upload, and every episode shows ready with its video id in state.json.
Step 4: Search for area cards and boss cards
Goal: saved lists of candidate windows for every area card and boss card.
Run both in precise mode. Precise is the only mode that returns a time window; fast returns the whole file with an empty reason, which says nothing about where a card is. The chain: the area search finds where the player enters each new area; the boss search flips from areas to fights and finds where each boss is named; the two together cover the chapter list, and Step 6 sweeps for anything neither one returned. There is no speech query: creators rarely say the area name, so the chain stays on what is shown on screen rather than flipping to what is said.
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| area_card | the game shows the name of the area the player has just entered as title text over the gameplay for a few seconds: either large decorative lettering in the centre of the screen with an ornament line, or a smaller name in the bottom left corner, sometimes with a short subtitle line under it. Not an item pickup label, not a character's name next to dialogue text, not a map or menu screen, not the game's title screen. | precise | 40 |
| boss_card | a boss fight begins and the game shows the boss's name as title text on screen while the boss is visible: large lettering in the bottom left corner with a smaller word above it, or a name written over a boss health bar along the top or bottom of the screen. Not an item pickup label, not a character's name next to dialogue text. | precise | 40 |
The queries describe where and how the card looks, never a name, so they work before anyone knows the areas. They were written after looking at contact sheets of our two test games, which share one art style. For another game, look at a sweep sheet (Step 6 command) first and replace the position and style words with what that game shows, for example "a banner across the top of the screen". Treat that wording as untested until the Step 5 frames show it working. A shorter wording, "the game shows the name of a new area or level on screen as title text when the player enters it", returned the same cards in our test run and is a reasonable start for a new game. None of the wordings was reworded on our test corpus.
maximum_results is the ceiling on how many windows come back, so it is also the most cards one search can find. 40 covers the dozen or so cards a long episode can have, with room for repeat visits and retries.
For each search, run vivu_search_videos (project_id, query, mode "precise", maximum_results 40). 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 the results to results/FIELD.json without the result page link, and show the result page link only in the live reply: it expires after four hours, so it never goes into the table or the chapters.
Done when results/area_card.json and results/boss_card.json exist and their job ids are in state.json.
Step 5: Check each window and set the start
Goal: every window labeled, with the name from a full frame and the start from a half second sheet.
- For each window cut frames at the start, middle and end (start_ms, the midpoint and end_ms converted to seconds) and look at all three (SECONDS is the second to cut, NAME names the window):
ffmpeg -v error -ss SECONDS -i video/EP_NAME.mp4 -frames:v 1 -q:v 3 frames/NAME.png
Look at all three because windows run wider than the card: the card can sit only on the middle frame, with a map screen or the boss before its title on the edges. 2. A window counts only when a frame shows the game's own area or boss title. An item pickup label, a character name beside dialogue, a quest or item card, a small area label on the map screen, a creator's own edit card ("a few moments later") or burned in captions do not count. Label those false and count them. 3. Find the first frame of the card in a half second sheet from two seconds before the window to its end (START_S is the first second, LENGTH the seconds covered, 24 cells cover 12 seconds):
ffmpeg -v error -ss START_S -t LENGTH -i video/EP_NAME.mp4 -vf "fps=2,scale=320:-2,tile=6x4" -frames:v 1 -q:v 3 sheets/half_NAME.png
Cell k (counting from 0, left to right, top to bottom) is START_S + k / 2. Use the first cell where the card is fading in, rounded down to the whole second, as the chapter start, and cut a full frame there to read the name. 4. Read the name from a full 720p or larger frame, not a sheet cell, and copy its capitals into title case ("FORGOTTEN CROSSROADS" becomes "Forgotten Crossroads"). Keep a subtitle line ("The Fading Town") out of the chapter unless the user wants it. 5. A later window on the same boss after a death is a duplicate and gets no chapter. A later window on an area already listed is a return; give it a chapter marked "(return)" only when REPEATS is yes. 6. Write every window to candidates.csv with the frames, the verdict, the first card second, the name from the frame and Vivu's reason. The reason never decides the verdict.
Worked example from our test run
The test corpus was two public walkthrough episodes with the creators talking over play, from personal channels that license them CC BY: 2 videos, 46.6 minutes, an episode from each of two games by the same studio. They stand in for a creator's own masters. Before searching we wrote every area card, boss card and lookalike from contact sheets with a frame every second: item pickup labels and character names in the same bottom left corner, quest and item cards in the centre, map screens with small area labels, the creator's own "moments later" cards and burned in caption words.
The area_card search returned 4 windows, 4 real and 0 false, with 0 missed against our list. Some cards were large centred titles and some were small bottom left titles, and the shortest was a return card that faded out quickly. The median window was 9 seconds wide. None of the lookalikes came back.
The boss_card search returned 2 windows, 2 real and 0 false, with 0 missed. Both were the same boss: the second window is the retry after a death, so it got no chapter. Neither game has a boss health bar, so the health bar half of that wording was not tested. A control search for a "game saved" notice, which neither video has, returned 0 windows.
Vivu's reason text named every card correctly here, and the names read from full frames matched. This is two episodes in one art style with four area cards and one boss, so treat every number above as one small sample.
Done when every window has a verdict in candidates.csv, and every real card has a name from a full frame and a start second.
Step 6: Sweep for cards the searches missed
Goal: a second look for cards both searches missed. A two second sweep can still skip a card that is on screen for less than two seconds, so tell the user the sweep lowers the chance of a missing chapter but does not rule it out.
- Make two second sweep sheets for each episode. Each sheet covers 200 seconds in 100 cells, so a 40 minute episode is 12 sheets:
ffmpeg -v error -i video/EP_NAME.mp4 -vf "fps=1/2,scale=240:-2,tile=10x10" -q:v 4 sheets/sweep_EP_%02d.png
Cell k of sheet n is (n - 1) * 200 + k * 2 seconds. 2. Look at each sheet for title text in the places Step 5 found it. Cards that stay on screen for about two seconds can fall between cells, so also look at the stretch after a loading screen or a door, where cards usually appear. 3. For any card the searches missed, set its start and read its name as in Step 5, and mark it "sweep" in candidates.csv. If a whole kind of card is missing (for example every boss), run one more precise search describing what the sweep shows, maximum_results 40. 4. Record each swept sheet in state.json.
In our test run the searches missed nothing, so the sweep found no new card. We made sweep sheets for both episodes but looked at only one of them, which showed the short return card the area search had already found; a full sweep of every sheet was not exercised in our test run, and the extra search for a missing kind of card was not exercised in our test run.
Done when every sweep sheet is marked swept in state.json and every card found by the sweep is in candidates.csv.
Step 7: Write the chapters and the check table
Goal: chapter_check.csv and chapters.txt, checked by the creator before anything is pasted.
- Show one sample row and the field mapping, and wait for a yes before writing the rest:
episode,mm_ss,start_s,kind,name,frame,source_window,repeat_of,creator_checked
EP02,19:05,1145,boss,Fourth Chorus,frames/EP02_1145.png,1142.0-1155.0,,
| Field | Source | If unavailable |
|---|---|---|
| episode | EP_LABELS | none |
| mm_ss, start_s | first card cell in the half second sheet, plus any offset from Step 2 | NOT FOUND |
| kind | area or boss, from which search or sweep found it | none |
| name | full frame, in title case | UNCERTAIN, with the frame path |
| frame | the full frame that was read | blank |
| source_window | the Vivu window, or "sweep" | none |
| repeat_of | the earlier chapter for a return to an area | blank |
| creator_checked | left blank for the creator | blank |
- Write chapters.txt per episode: the first line "00:00 INTRO_TITLE", then one line per chapter in time order, "MM:SS NAME" (H:MM:SS past an hour), boss lines with BOSS_PREFIX. YouTube generally wants the first chapter at 00:00, at least three chapters and each at least 10 seconds long; when two cards fall within 10 seconds, keep the first and tell the user. An episode with fewer than two cards cannot get chapters on YouTube; say so instead of padding.
- Tell the user the counts per episode: chapters, windows labeled false, duplicates, cards found only by the sweep, and names marked UNCERTAIN.
- Give the user chapters.txt to paste into each video's description. Pasting is the creator's step; this skill does not post to YouTube.
In our test run chapters.txt has the intro line plus one line per real card for each episode, with the boss retry left out and no NOT FOUND or UNCERTAIN rows. The standing searches cost 10 credits per batch (estimate). The user's approval of the sample row was not exercised in our test run.
Done when chapter_check.csv and chapters.txt exist with one row per chapter, the user approved the sample row, and the user has the chapter text with the counts.
Compliance
- Use only episodes the creator recorded and owns; do not pull a YouTube or Twitch link, and do not index someone else's video. Confirm before Step 3.
- A creator under 18 needs a parent or guardian to agree to uploading their recordings to a third party service; without that, the skill does not run. Ask in Step 1.
- Game footage belongs to the game's publisher. The skill only reads frames to write chapters; it does not cut, caption or redistribute the footage.
- Facecam, voice and on screen chat can show the creator and viewers. The skill reads only the game's title cards and does not write viewer names, chat text or anything about the people on camera into the table. It does not identify anyone from faces.
- The episodes stay in the user's Vivu project until the user deletes them. The project is created private because the default visibility shows it to the whole Vivu organization. Delete a project or video only when the user asks, and confirm first.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) the end frame of an area window is a map screen with a small area label, not the card | windows run several seconds past the card, and the map shows the same name small | judge on the middle frame; a map label alone is not a card |
| (observed) the start frame of a boss window shows the boss but no name | the name appears a few seconds after the boss does | look at every frame and the half second sheet before judging |
| (observed) a second boss window names a boss already in the list | the player died and retried, and the game shows the title again | label it duplicate; only the first fight gets a chapter |
| (observed) an area window lands on a return to an area already listed | the game shows a smaller card each time the player comes back | mark it as a return or drop it, per REPEATS |
| item pickup labels or character names are taken for area cards | they appear in the same corner in some games | a card is the game's title text for a place; check the frame, label anything else false |
| a creator's own "moments later" card or burned in captions come back | edits and captions are large text on screen | label them false; describe the game's card style in the query |
| no area windows on a new game | its cards look different from the query's style words | look at a sweep sheet, rewrite the style and position words, and rerun; an empty result does not prove the game has no cards |
| a short card is missing from the chapters | one search does not reach every card, and short text has been missed in other footage | run the Step 6 sweep; look after loading screens and doors |
| a stylized name is misspelled | reason text paraphrases, and stylized fonts are hard to read in small cells | read the name from a full frame; if it is still unclear, mark UNCERTAIN |
| 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 |
| an episode is rejected by the browser upload tool | Claude in Chrome accepts at most 10 MB per upload call | the user opens the upload link in their own browser or adds the file in the Vivu web app |
| "has not granted vivu.write" | Vivu connected read only | the user reconnects Vivu with write access |