---
name: tournament-map-chapter-sheet
description: "Turn your own tournament broadcast recording into a VOD chapter sheet with Vivu: map starts, map names and final scores read from frames. Use after a match day to post chapters."
---Map chapter sheet for tournament broadcast recordings
This skill takes one series from a tournament broadcast that the user's own organization recorded, cut from the match day by the schedule, and returns a chapter sheet for the VOD. Claude prices the recording against the user's Vivu plan, indexes it in a private Vivu project, runs one precise search for map openings, one for post game result pages and one for the casters moving to the next map, reads each map name and final score off a full frame, sets each start from a half second contact sheet, and writes a CSV plus a block of chapter lines for the video description. An operator checks the sheet and pastes the chapters.
The map name and the score are what the schedule and the transcript cannot give. A schedule has planned times, and matches run late. Casters often do not name the map when it opens, and automatic captions mangle game names and team names: in our test run the captions wrote the map SAKE as "Soc". The broadcast shows both facts on screen, in the map strip during the opening and on the result page after the map. Vivu narrows a long recording to a few windows, Claude reads the frames, and a window that does not show a map opening or a result page stays out of the sheet.
When to use
Use when a tournament organizer, campus league broadcast lead or league VOD editor says "make chapters for yesterday's grand final", "where does each map start in this series recording?", "list the maps and scores for the VOD description" or "the match ran late, fix the timestamps from the schedule".
Not for these:
- Whole match days uploaded in one piece. They usually exceed a monthly plan; cut one series at a time by the schedule (Step 2).
- Finding funny or hype moments for clips: use the stream-vod-clip-shortlist skill.
- Live highlights, automatic clip cutting or judging how anyone played. This skill lists maps, times and scores.
- A broadcast the user's organization does not own, or a link to someone else's channel.
- A one off question about one moment in one video: 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 inside it shows the map opening or the result page. Map names and scores come from full frames, never from Vivu's reason text, because reason text has invented numbers on small or stylized game graphics.
- 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 recording) and before anything that acts on their behalf (pasting chapters into a video page; show the rendered text first).
- Report the real count. If a map cannot be found, it stays in the sheet marked NOT FOUND, so the operator sees the gap instead of a guessed time.
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 recording, cut the series, cut frames and contact sheets | ffmpeg -version, ffprobe -version |
| The broadcast recording as a local file, from the organization's own production | it is uploaded to Vivu and the frames come from it | ffprobe -v error -show_entries format=duration -of csv=p=0 RECORDING prints a duration |
| The schedule entry for the series (teams, planned start, format) and the list of maps if the organizer has one | it picks the part of the day to cut and tells how many maps to expect at most | the user pastes it |
| A timestamped transcript (.vtt or .srt), optional: a captioning file, or a local speech to text tool such as whisper.cpp | supplies the casters' line for each chapter; the sheet still works without it, with that column NOT VERIFIED | grep -c " --> " TRANSCRIPT prints a count above zero |
| An upload path | move the recording 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 it needs no residential IP. Nothing recurs, so no scheduler is involved; run it again for the next series.
Inputs to collect
Ask for anything missing, most important first.
- RECORDING: the local broadcast file. Required.
- SCHEDULE: teams, format (best of 3, best of 5) and planned start of the series. Required.
- SERIES_NAME: a short name for the working folder and the Vivu project. Default: TEAM_A-vs-TEAM_B-DATE.
- MAP_LIST: the map pool or planned maps. Default: none; map names come from the frames.
- TRANSCRIPT: a timestamped transcript. Default: none; the caster_line column is NOT VERIFIED.
- VOD_OFFSET: the second of the posted VOD at which second 0 of the indexed file falls, added to every start. Use a negative number if the VOD starts later than the indexed file. Default: 0.
- CHAPTER_STYLE: what each chapter line shows. Default: "MM:SS Map N MAP_NAME MODE (TEAM_A SCORE-SCORE TEAM_B)".
Files and state
Keep everything in one working folder:
chapters-SERIES_NAME/
config.json series, schedule entry, recording, VOD_OFFSET, Vivu project id
video/ the series file (.mp4)
subs/ the transcript, if there is one
results/ search results as JSON, without the result page link
frames/ frames cut inside each window and at each start
sheets/ contact sheets
candidates.csv every window Vivu returned, what the frame showed, and the verdict
map_chapters.csv the chapter sheet, one row per map played
chapters.txt the chapter lines for the description
state.json steps done, video_id, job ids, windows checked, maps found, paste status
Run the commands from inside chapters-SERIES_NAME/ so the relative paths resolve.
A rerun reads state.json first and skips finished steps: a recording marked uploaded is not uploaded again, a search with a saved result is not run again, a window with a recorded verdict is not checked again, and chapters marked pasted are not pasted 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 working folder and its subfolders:mkdir -p chapters-SERIES_NAME/video chapters-SERIES_NAME/subs chapters-SERIES_NAME/results chapters-SERIES_NAME/frames chapters-SERIES_NAME/sheets. - Ask for the recording and the schedule entry if they are not in the request. Ask whether any player is a minor (Compliance).
In our test run vivu_get_account returned can_create_projects: true, and ffmpeg and ffprobe ran in the later steps. Our test recording had adult professional players, so the minors question did not apply.
Done when vivu_get_account shows can_create_projects: true, both tools print their versions, and the user has given the recording and the schedule entry and answered the minors question.
Step 2: Cut the series and look at the graphics
Goal: one file holding one series, and proof that the broadcast shows map names and scores on screen.
- Measure the file:
ffprobe -v error -show_entries format=duration -of csv=p=0 RECORDING. - If the file is a whole match day, cut one series. Pick the range from the schedule with generous margins, because matches run late. Check the edges with a one frame per minute sheet:
ffmpeg -v error -i RECORDING -vf "fps=1/60,scale=240:-1,tile=8x6" -q:v 3 sheets/day_%02d.png
Then cut without re-encoding (START and END are HH:MM:SS, SERIES is the file name):
ffmpeg -v error -ss START -to END -i RECORDING -c copy video/SERIES.mp4
Record START in config.json as VOD_OFFSET when the posted VOD is the whole day, so chapter times can be added back. Stream copy cuts on keyframes, so measure the offset from a frame rather than trusting START when a chapter must land exactly.
If it already holds one series, copy it in place so later commands find it (SERIES is the file name):
cp RECORDING video/SERIES.mp4
- Build a ten second overview of the series and look at it. It shows how this production marks a new map and whether it has a result page:
ffmpeg -v error -i video/SERIES.mp4 -vf "fps=1/10,scale=240:-1,tile=10x10" -q:v 3 sheets/overview_%02d.png
If no map name or score is ever on screen, tell the user the score column has to be filled by hand and map starts rest on the casters and the in game HUD.
In our test run the source was already a single series, so cutting a series out of a whole match day was not exercised in our test run; we ran the sheet and stream copy commands on the series file to confirm they work. The overview showed this production's graphics: a stage screen with the map name, a map strip along the bottom during the flyover, an in game scoreboard HUD, and after each map a series score card, a full screen result page and a map board.
Done when video/ holds one series file and the user has seen which graphics this production uses.
Step 3: Price, upload and index
Goal: the series indexed in a private Vivu project, with the user's approval of the cost.
- Call vivu_get_usage and show one table:
| This series | Plan allowance | Remaining this month | |
|---|---|---|---|
| Index minutes | duration / 60 | from vivu_get_usage | from vivu_get_usage |
| Search credits | 15 for the three searches in Step 4, plus 5 for each 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. A match day of six to eight hours is more than a Premium month by itself, which is why this skill works one series at a time.
- If the series does not fit, offer levers in this order: index only the maps the VOD needs (cut breaks, analyst desk segments and ad blocks that hold no map start, and record each cut so times can be added back), then move to a larger plan. Never drop a map without telling the user which one, and never recompress a file to save minutes.
- Wait for the user to approve the index minutes and credits before you create a project or upload. In the same message confirm that the organization owns or may index this recording and that its participant and broadcast terms allow it to go to a third party processor (Compliance 1 and 3).
- Call vivu_list_projects and reuse a project named "Chapters 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 file, or open it in a browser tool that can attach local files. Claude in Chrome accepts at most 10 MB per upload call and a broadcast recording is far larger, so it normally goes through the user's own browser or the Vivu web app. Never split or recompress the file to fit.
- Poll vivu_list_videos until the file shows ready. Vivu replaces spaces and punctuation in file names with underscores; keep the series name simple and match on it. Record the video_id in state.json.
In our test run the 48.0 minute series was ready about 25 minutes after the upload started (an upper bound, measured from polls). The account used in our test run returns no allowance figures, so the plan comparison and the user's approval were not exercised in our test run. The file 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 and the rights before the upload, and the recording shows ready with a video_id in state.json.
Step 4: Search for map openings, result pages and caster transitions
Goal: saved lists of candidate windows for where each map starts and ends.
Run these in precise mode on the whole series. Precise is the only mode that returns a time window; fast returns the whole file with an empty reason, which says nothing inside a single recording. The chain: the map opening search finds where each map begins; the result page search confirms the map finished and gives the frame that holds the score, and two neighboring result pages bound where the next opening can be; the caster search flips from what is shown to what is said and confirms which map comes next, so a map named by the casters with no opening window is looked up in Step 6.
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| map_start | a new map begins: the broadcast shows a flyover of the map with a strip of map names and game modes along the bottom of the screen, just before the match starts | precise | 20 |
| map_result | a full screen post game results page after a map ends, showing the map name, the game mode, the final score of the two teams and a table of player stats | precise | 20 |
| caster_next_map | the casters say which map and game mode comes next as the teams head into the next map | precise | 20 |
| map_result_lookup (Step 6, one per missing page) | a full screen post game results page for a MODE map, with the final score at the top and a table of STAT_COLUMNS for each player | precise | 5 |
Adapt map_start to what the Step 2 overview shows. We wrote it after seeing our test production's bottom map strip, so on a production with a different opening, describe that opening instead and treat the search as untested until the Step 5 frames show it working. None of the wordings above was reworded on our test corpus.
maximum_results is the ceiling on how many windows come back, so it is also the most maps a search can find. 20 is about four windows per map of a best of five, which leaves room for repeat windows on one map; the lookup uses 5 because it targets one page.
For each search, run vivu_search_videos (project_id, query, mode "precise", maximum_results 20). 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 sheet or the chapters.
Done when results/map_start.json, results/map_result.json and results/caster_next_map.json exist and their job ids are in state.json.
Step 5: Read each window and set the start
Goal: each window labeled, with the map name and score from a full frame and the start from a half second sheet.
- For each map_start and map_result window, cut frames at the start, middle and end (start_ms, the midpoint and end_ms converted to seconds) and look at all three, because a result page window can fit the page so tightly that only the middle frame shows it (SECONDS is the second to cut, NAME names the window):
ffmpeg -v error -ss SECONDS -i video/SERIES.mp4 -frames:v 1 -q:v 3 frames/NAME.png
- A map_result window counts only when a frame shows that map's result page. A round end card, a series score card, a map board listing past scores or the in game HUD does not count. Read the map name, mode and score from a full frame, not a contact sheet cell. A later window on a result page already found is labeled "duplicate".
- A map_start window counts only when it sits on a map opening. Find the second in a half second sheet from 30 seconds before the window to the end of the window (START_S is the first second, LENGTH the seconds covered):
ffmpeg -v error -ss START_S -t LENGTH -i video/SERIES.mp4 -vf "fps=2,scale=320:-1,tile=8x8" -q:v 3 sheets/start_NAME_%02d.png
Use the first frame with the in game scoreboard HUD as the chapter start, because that is when play is about to begin and the viewer lands on the map. If the user prefers the chapter on the flyover, step back to the stage screen or the first flyover frame and note the choice in config.json, so every map follows one rule. 4. Read each caster_next_map window in the transcript. Without a transcript, read the summary segments for the window with vivu_get_video_summary (include_segments, start_ms and end_ms around the window). These windows confirm which map comes next. They do not set a start, because the talk can come long before the map opens, so a caster window with no map opening near it goes to Step 6 instead of the sheet. 5. A map board is useful as a cross check: boards that list past scores should match the scores read from result pages, and maps on the board with no score were not played. Never add a chapter for an unplayed map. 6. Write every window to candidates.csv with the label, what the frame showed and Vivu's reason. The reason never decides the label. Count false windows and tell the user.
Worked example from our test run
The test corpus was one public series broadcast from a professional esports league's official channel: 1 video, 48.0 minutes, a best of five that ended after three maps, with adult professional players. It stands in for an organizer's own recording. Before searching we wrote each map's first in game HUD second and final score from contact sheets and full frames, plus the rule that a window counts when it sits on the opening and, with a short margin, contains that second. This is three maps from one production and one game title, so treat every number below as one small sample.
The map_start search returned 3 windows, 3 real and 0 false, with 0 missed: each of the 3 maps got one window, between 8 and 17 seconds wide. Each window held the map's first HUD second, and the half second sheets gave the start. Series score cards, map boards, round end cards, player stat cards, ads and the analyst desk were not returned.
The map_result search returned 2 windows, 2 real and 0 false, with 1 missed: the Search and Destroy result page was on screen and did not come back. The map_result_lookup query, naming that mode's own stat columns, returned 1 window, 1 real, and that window held the missed page. We knew those columns from our truth frames, so this shows the lookup works once the mode is known, not that the first search can find every page. On all three pages the score read from a full frame matched the final map board. Vivu's reason text also had these three scores right, on large full screen pages; earlier tests on small scoreboards had invented numbers, so the frame stays the source.
The caster_next_map search returned 4 windows, 4 real and 0 false, covering all 3 maps, with 0 missed against the map list. Only the first sat at a map opening. The other three were analyst talk before the map, and one of those ended before an ad block, well ahead of the opening, which is why this search confirms the map and never sets the start. At the openings of the second and third maps the casters did not say the map name at all. A control search for a map name that never appears in the broadcast returned 0 windows. The screen searches rely on stylized game graphics, and small in game text was not tested.
Done when every window has a label in candidates.csv, and every map found has a name and score from a full frame and a start second.
Step 6: Look up what the searches missed
Goal: a start and a score, or NOT FOUND, for every map played.
- Work out how many maps were played from the last map board, the last series score card or the schedule's format and the result.
- A map with a result page but no opening: start from the end of the previous map's result page and step forward with a ten second sheet, then a half second sheet, until the map opening appears.
- A map with no result page: look at the frames after the last gameplay in that map. Some productions skip the page; a map board with the score is the second source. If no frame shows the score, the score stays NOT VERIFIED and an operator fills it in.
- For a result page the search missed, run map_result_lookup from Step 4. MODE is the missing map's mode from its map strip. STAT_COLUMNS are that mode's stat columns if the user knows them or an earlier page of that mode showed them; otherwise drop that clause, a shorter wording that was not exercised in our test run. Check the window as in Step 5.
- Run one more precise search only if a map still has no opening: "the MAP_NAME map opening at the start of a new map", maximum_results 5. This opening lookup was not exercised in our test run, because the map_start search found all 3 maps.
In our test run the map_result_lookup search found the one missed result page.
Done when every map played has a start second or NOT FOUND and a score or NOT VERIFIED.
Step 7: Write the sheet and check it with the user
Goal: map_chapters.csv and chapters.txt, checked before anything is posted.
- Show one sample row and the field mapping, and wait for a yes before writing the rest:
seq,map_name,mode,score,start,start_s,start_frame,score_frame,caster_line,chapter_line,ops_checked
1,MAP_NAME,MODE,TEAM_A 93 - 250 TEAM_B,00:20,20,frames/map1_start.png,frames/map1_score.png,"let's get it on","00:00 Map 1 MAP_NAME MODE (TEAM_A 93-250 TEAM_B)",
| Field | Source | If unavailable |
|---|---|---|
| seq | order of play | none |
| map_name, mode | full frame of the result page, cross checked with the map strip or map board | NOT VERIFIED |
| score | full frame of the result page | NOT VERIFIED |
| start, start_s | half second sheet, plus VOD_OFFSET | NOT FOUND |
| start_frame, score_frame | the frames that were read | blank |
| caster_line | copied from the transcript, caption errors marked in brackets | NOT VERIFIED |
| chapter_line | built from the fields above in CHAPTER_STYLE | none |
| ops_checked | left blank for the operator | blank |
- Write map_chapters.csv in order of play and chapters.txt. Video sites generally want the first chapter at 00:00. When the first map starts within the first minute, put its chapter line at 00:00 and keep the true start in the start column; when it starts later, add a "00:00 Pre show" line. Do not include player names in the sheet.
- Tell the user the counts: maps found, NOT FOUND, windows labeled false, duplicate windows, and scores read from a frame.
In our test run the sheet has 3 rows, none NOT FOUND, and the chapters are at the map starts. The standing searches came to 15 credits (estimate, from the 5 credit rule). The user's approval of the sample row was not exercised in our test run.
Done when map_chapters.csv and chapters.txt exist with one row per map played, the user has approved the sample row, and the counts are reported.
Step 8: Hand over the chapters
Goal: the approved chapters in the VOD description, posted once.
- Name the destination and show the full text exactly as it will appear. Posting acts as the user, so wait for an explicit yes. When no connected tool can write to the destination, give the user the text to paste.
- Use the posted video's own timestamps, never a Vivu result page link (it expires after four hours) or a local file path.
- Record the paste in state.json so a rerun does not paste it again.
Pasting was not exercised in our test run; Step 8 rendered chapters.txt as a file and posted nothing.
Done when the user has approved the rendered text and it is in the named place, or the user has the text to paste, and state.json records which.
Compliance
- Use only recordings the user's organization produced or has the right to index; do not pull a live platform link or someone else's channel. Confirm before Step 3.
- Campus and youth leagues can include minors. Uploading a recording of minors needs guardian consent; without it, this skill does not run on that recording. Ask before Step 3.
- Casters, players and audience are on camera. Confirm the organization's participant and broadcast terms allow the recording to go to a third party processor before Step 3.
- The sheet lists maps, times and scores only. It does not rate players, name them or identify anyone from faces or logos.
- The recording stays in the user's Vivu project until the user deletes it. 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.
- Pasting chapters into a video page acts as the user and needs approved text first (Step 8).
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) a result page on screen does not come back from the map_result search | one search does not reach every page; in our test run 1 missed, the Search and Destroy page | count the maps played, then run map_result_lookup or step through the gap between maps with sheets (Step 6) |
| (observed) the start and end frames of a result window show a score card and a replay, not the page | the window fits the page tightly | look at the middle frame before judging; a window counts when any frame shows the page |
| (observed) the reason names a map that does not exist: "6 Star Hardpoint" | reason text paraphrases what was heard, and the casters' words were mangled | take the map name from a frame, never from the reason or the captions |
| (observed) a caster window lands long before the map opens | analysts talk about the next map before the break and the ad block | use caster windows to confirm the map; set the start from the opening and the half second sheet |
| (observed) the start frame of an opening window shows a team record strip, not the map strip | the opening has several graphics in a row | read the whole window; the map strip was on the middle frame |
| (observed) the casters never say the map name at the opening | they talk about the teams instead | use the on screen map strip and the result page |
| a map board lists maps with no score | best of series ended early, those maps were not played | never add a chapter for an unplayed map |
| a series score card or round end card is taken for a result | they share the same colors and fonts | a result page has the map name, the final score and a player table; label anything else false |
| scores on small scoreboards come back wrong in the reason | reason text has invented numbers on small graphics | read the full frame; if it cannot be read, mark NOT VERIFIED |
| empty search on a new production | its opening or result page looks different from the wording | adapt the wording to the Step 2 overview; an empty result does not prove the graphic is absent |
| 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 |
| the recording 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 |