---
name: device-setup-friction-log
description: "Turn in-home device setup study recordings into a setup friction log with Vivu: where participants opened the paper guide or said they were stuck, by setup step, with time, frame and quote."
---Device setup friction log
This skill takes one round of an in-home out of box setup study (a recording per participant, usually 20 to 40 minutes of a tripod or handheld camera on the table and the participant's hands, with the participant ID in the file name), the moderator's notes with the rough start and end of each setup, and the five or six steps from the product's quick start guide (for example unbox, mount the base, connect the wires, pair the app, put it on the wall). It returns setup_friction_log.csv: one row per moment where a participant opens the paper guide, says a part does not fit or a step is not working, or holds up the phone to read the setup app, with the participant ID taken from the file name, the setup step, the category, the start and end time, the participant's words from a transcript, a description written from the frames, the frame path and an empty attribution column (guide, packaging, hardware or app) for the researcher. Claude trims each recording to the setup stretch from the notes, prices the indexing against the user's Vivu plan, uploads the trimmed sessions to a private Vivu project, runs one search per category, checks every window against a contact sheet of frames or the transcript, and only then writes the log.
The value is in what the picture shows and the transcript does not. A participant says "this won't fit" or "where does this go", and which part, how they held it, whether they had the guide open and whether the phone was in their hand only exist on camera. Many friction moments are silent: people flip through the booklet without saying so. Vivu finds candidate windows by what is on screen and what is said. Telling the paper guide apart from the box, an insert or a sheet lying on the table is where it is least reliable, so every window is checked against frames before it becomes a row, and rejected windows are counted.
When to use
Use when a UX researcher or hardware PM says "find every time participants went to the paper manual in this round of setup sessions", "where did people get stuck installing the device", "build a setup friction log from these seven in-home recordings for the hardware and packaging teams", or "which step sent people to the app". For one question about one session, search Vivu directly. For usability tests of an app or website recorded as screen captures, use a usability issue skill instead; for diary studies of daily life, use a diary study skill. This skill does not score participants, judge their skill, or decide whether the guide, the packaging, the hardware or the app caused a problem; the attribution column is left for the researcher.
Working principles
- Report measured numbers, not estimates. When a number is an estimate, say so.
- A moment becomes a row only after its frames show it (guide, phone) or the transcript has the words (stuck). Vivu's results are candidates until then; rejected candidates are counted and kept in rejected.csv.
- Stop and tell the user when a required capability, consent or file is missing (no ffmpeg, no write access in Vivu, sessions without consent for cloud processing, no transcript for the spoken category). Do not guess around it.
- Ask the user before anything that is expensive to redo or that acts on their behalf: the trimmed setup stretches before upload, the indexing cost, the sample rows before the full log, and a Notion page before it is created.
- Describe what the session shows and says. Never judge the participant and never infer who someone is from a face or a voice; the participant ID comes from the file name only.
What you need before starting
Check each item at the start of the run and tell the user plainly what is missing.
| 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; the user reconnects Vivu and allows write access |
| A shell with ffmpeg and ffprobe on the machine that holds the recordings | trim the setup stretch, measure minutes, make contact sheets and frames | ffmpeg -version and ffprobe -version |
| The session recordings as local video files, with the participant ID in each file name | trims and frames come from the local files; Vivu has no export tool; IDs come from file names | ls SESSIONS_FOLDER and show the user three file names with the ID pattern |
| The moderator's notes with the setup start and end per session | only the setup stretch is indexed | the user points to the notes file; read the times for two sessions back to them |
| The quick start guide's steps | rows are grouped by setup step | the user lists five or six steps, or shares the guide |
| A transcript per session (VTT, SRT or TXT, from the recording tool or local speech to text) | the stuck category is checked and quoted from it, never from Vivu's reason text | ls SESSIONS_FOLDER for transcript files; tell the user which sessions have none |
| The consent record for the round | only sessions whose consent covers recording in the home and upload to a third party cloud service may be indexed | the user confirms which participants are covered |
| A browser that can open the Vivu upload page | the connector has no direct upload tool | the user opens the link, or Claude in Chrome is connected |
| Notion connector, only if the log should also go to a Notion page | Step 7 | open the parent page the user names |
The skill needs a shell and local files, so it runs in Claude Code on the user's computer (terminal or the Code tab of Claude Desktop). It downloads nothing from YouTube, so no residential IP is needed, and nothing is scheduled.
Inputs to collect
Ask for anything missing, most important first.
- The sessions folder (SESSIONS_FOLDER). Required.
- The moderator's notes with each session's setup start and end. Required; without them the whole session is indexed, which costs more minutes and adds unboxing chatter.
- The setup steps, five or six, each with a key (for example unbox, base, wiring, app_pairing, mount). Required.
- Which participants are covered by consent. Required; sessions outside it are left out.
- The participant ID pattern in the file names. Default: the leading P plus digits (P03_session.mp4 gives P03); confirm on three real names.
- Whether to also create a Notion page. Default: no, setup_friction_log.csv only.
- The Vivu project name. Default: "Setup study PRODUCT round N", private, where PRODUCT is the product's short name.
Files and state
Keep everything in one working folder next to the sessions:
setup-friction/
sessions.csv file, participant_id, setup start and end, minutes, consent ok, transcript file, vivu video id
trimmed/ the setup stretch of each session, the files that are uploaded
steps.json setup step keys with their time ranges per session
results/ raw search results, one JSON file per category
sheets/ 0.5 second contact sheets of each window
frames/ one full frame per verified row
setup_friction_log.csv verified rows
rejected.csv windows that failed the check, with the reason
state.json trims made, uploads, searches with job ids, every window with its verdict, rows written, Notion page created
state.json is updated after every step. A rerun reads it first: sessions already trimmed or uploaded are not done again, searches already run are not rerun, checked windows keep their verdicts, and a Notion page already created is never created twice, so an interrupted run resumes where it stopped and no moment is written twice.
Step 1: Check the Vivu connector and the setup
Goal: every row of What you need is confirmed before anything is trimmed or uploaded.
- Call vivu_get_account. If the tool is missing, tell the user to add the Vivu connector in Claude (https://mcp.vivu.ai/mcp) and stop. If can_create_projects is not true, or a write call later fails with "has not granted vivu.write", ask the user to reconnect Vivu with write access and stop until they have.
- Run ffmpeg -version and ffprobe -version. List SESSIONS_FOLDER, show three file names and the participant ID each yields, and note which sessions have a transcript file.
- Read the moderator's notes and the setup steps back to the user for two sessions.
- If a Notion page is wanted, open the parent page the user names.
- Create the working folders; ffmpeg does not create an output folder:
mkdir -p setup-friction/trimmed setup-friction/results setup-friction/sheets setup-friction/frames
Run every later command from inside setup-friction/ (cd setup-friction), with SESSION_FILE as the path to the session from there.
Done when vivu_get_account shows can_create_projects: true, ffmpeg and ffprobe print versions, the ID pattern is confirmed on three names, and the working folders exist.
Step 2: Confirm consent and trim the setup stretch
Goal: trimmed/ holds only the setup stretch of each consented session.
- Ask the consent question in Compliance item 1 before anything else in this step. Leave out every session whose participant is not covered, and every participant under 18.
- For each session, cut the setup stretch from the notes (START and END in seconds; re-encoding keeps the cut points exact, and the participant ID stays at the front of the file name):
ffmpeg -v error -ss START -to END -i SESSION_FILE -c:v libx264 -c:a aac trimmed/PARTICIPANT_ID_setup.mp4
- Cut the transcript to the same stretch, or keep the offset START in sessions.csv so transcript times can be shifted when checking.
- Write sessions.csv and show it to the user with each trim's start and end.
Done when the user has confirmed consent and approved the trims in sessions.csv.
Step 3: Price the indexing and get approval
Goal: the user sees the cost before anything is uploaded.
- Measure each trimmed file and sum the minutes:
ffprobe -v error -show_entries format=duration -of csv=p=0 trimmed/PARTICIPANT_ID_setup.mp4
- Call vivu_get_usage for the plan and what remains this month.
- Estimate search credits: one precise search per category, plus a second wording for the stuck category and one rewording per visual category in case the first page is not clean. A precise search uses 5 credits in total. Label the total as an estimate.
- Show one table and wait for approval:
| This round | Remaining on the plan | |
|---|---|---|
| Index minutes | measured sum | from vivu_get_usage |
| Search credits | estimate | from vivu_get_usage |
For reference, the Free plan has 20 index minutes a month and 50 search credits a month; Premium is $30 a month with 180 index minutes and 500 search credits. For example, seven sessions trimmed to twenty minutes each would fit Premium, not Free. If the round does not fit, offer these levers in order: trim tighter to the steps the team cares about most (for example only mounting and pairing), index the participants the report is about first and the rest next month, and only then a larger plan. Never drop a session the user asked for without saying so.
Done when the user has approved the minutes and the credit estimate.
Step 4: Upload and index
Goal: every trimmed session is ready in a private Vivu project.
- Call vivu_list_projects and reuse the project named in the inputs if it exists. Otherwise call vivu_create_project with that name and visibility "private". In-home recordings show homes and family members; the default visibility is the whole organization.
- Call vivu_open_upload_page with the project ID right before the upload. The link expires in 180 seconds and is a sign in link, so never paste it into a message or file. Give it to the user to open in their own browser and choose the files in trimmed/, or attach them with a browser tool that can upload local files. Claude in Chrome accepts at most 10 MB per upload call; larger files are added by the user in the Vivu web app. Never split or recompress a session to fit.
- Poll vivu_list_videos about every 30 seconds until every file shows ready. Match each video back to sessions.csv by file name; Vivu turns spaces and punctuation in names into "_", so compare names with those characters replaced. Record the video IDs in sessions.csv and state.json.
Done when vivu_list_videos shows every file in trimmed/ as ready.
Step 5: Search each category and check every window
Goal: for each category, a list of checked moments with rejected windows counted.
Run each category's query with vivu_search_videos (project_id, query, mode "precise", maximum_results as in the table). 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/CATEGORY.json. Show the result page link in the live reply only; it expires after four hours, so it never goes into the log, Notion or any file. All searches are precise because rows need time ranges; a fast search returns whole files, and after trimming there is no file choice left for fast to make.
These wordings ran in our test; adapt the device words to the product and keep the shape:
| Field | Query | Mode | maximum_results |
|---|---|---|---|
| manual | the person holds a paper instruction booklet or quick start guide open in their hands or on the table and looks down at its pages while setting up the device | precise | 30 |
| stuck_spoken | the person runs into trouble during the install and says so: something won't fit, won't come off or isn't working, or they don't know which way a part goes | precise | 30 |
| phone_app | the person holds up a phone and looks at the setup app on its screen while pairing the device | precise | 20 |
| part_fit (candidates only) | the person holds a cable, screw, bracket or small part against the device or the wall and tries to work out where it goes | precise | 20 |
maximum_results is 30 for manual and stuck_spoken because a round of seven sessions rarely has more moments of one kind than that; it is also the ceiling on what comes back, so a list that stops at exactly that number means the cap was hit: raise it and rerun. phone_app and part_fit use 20 because pairing happens once per session and part_fit is a candidate list the researcher reviews by hand; if either list comes back with exactly 20, raise it and rerun. Why this chain: manual and phone_app find the silent moments that the transcript does not have, stuck_spoken finds the spoken ones, and the contact sheet of every stuck window turns "this won't fit" into which part was in the participant's hands, a flip from said to shown.
Vivu returns a time range that contains the moment, not an exact frame, and the reason text describes what Vivu thinks it saw or heard; it can name an object that is not there. Check every window:
- Visual categories (manual, phone_app): make a contact sheet of the window at two frames a second (START is start_ms / 1000, DURATION is (end_ms - start_ms) / 1000, ROWS is DURATION x 2 / 10 rounded up, SESSION is the trimmed file name without its extension, for example P03_setup):
ffmpeg -v error -ss START -t DURATION -i trimmed/SESSION.mp4 -vf "fps=2,scale=240:-2,tile=10xROWS" -frames:v 1 sheets/CATEGORY_SESSION_START.png
Look at the sheet. The window is real only if a cell shows it: for manual, a paper booklet or instruction sheet open in the participant's hands or under their hands with pages visible; for phone_app, a phone in the hand with a setup app screen. Reject it when it is the retail box, a box insert, the back of the box, a booklet lying closed on the table, or a screen recording with no phone in the picture. When a cell shows it, extract one full frame at that cell's time (SECONDS is START plus the cell's index divided by 2; cells count from 0, left to right, top to bottom) and look at it before writing the row:
ffmpeg -v error -ss SECONDS -i trimmed/SESSION.mp4 -frames:v 1 -q:v 3 frames/CATEGORY_SESSION_SECONDS.png
Keep the quotes around the filter; some shells treat the comma list as a pattern otherwise. 2. Spoken category (stuck_spoken): read the transcript lines inside the window (shift by the trim START if the transcript is for the untrimmed session). The window is real only if the participant says, about the install, that something does not fit, is not working, or that they do not know how a step goes. Explaining a step ("you're supposed to") or a general opinion is not a row. Then make the contact sheet of the same window and write what is in their hands, because that is what the hardware team needs: the modality flip from said to shown. 3. Keep the stuck_spoken wording concrete (won't fit, won't come off, isn't working, which way a part goes). In our test run a looser first wording returned guesses and slips as well as real stuck moments; if the first page has false positives, reword once and rerun, and keep both result files. 4. Assign each verified moment to a setup step from steps.json by its time, or by what the frames show when the notes are coarse; mark the step UNCERTAIN when neither settles it. 5. Rejected windows go into rejected.csv with the reason; they are counted, not dropped silently. A window that cannot be settled from the frames stays a candidate for the researcher. 6. An empty result or a short list does not prove participants never opened the guide or got stuck. Tell the user, and grep the transcripts as a free second pass (for example grep -n -i -E "doesn't fit|won't fit|not working|not sure|manual|instructions" TRANSCRIPT_FILE, where TRANSCRIPT_FILE is the session's transcript).
Hunting for where a part goes (part_fit) is a hand action, and Vivu's search for actions is still listed as untested; in our test run it was the noisiest category (numbers below). Treat its windows as candidates: a part_fit row is written only when the contact sheet shows a part being held against the device or wall, and a wide shot where the parts are too small to see stays a candidate for the researcher. Do not use an empty part_fit result as evidence that nobody struggled to place a part.
Worked example from our test run
In our test run we used 7 public videos, 34.0 minutes in total, cut from Creative Commons smart home install videos (thermostats, video doorbells, a keypad deadbolt and an indoor camera) and renamed like participant sessions. These are edited videos by people installing on camera for an audience, not study sessions: they narrate more than participants do, the framing changes, and one includes an edited insert, so silent friction and a fixed tripod view were only partly represented. Before searching we wrote down from contact sheets and subtitles which sessions showed each category, plus distractors: a retail box held and turned over, a booklet lying closed on the table in a wide shot, a box insert, and an app screen recording with no phone in the picture. From the upload to all 7 sessions ready took 17.5 minutes.
The manual query returned 5 windows: 5 real, 0 false, and 0 missed of the booklet moments we had marked. Two of the real ones were a printed sheet unfolded or held in one hand while the participant followed the app on the phone, which we had marked as unclear before searching; we counted them because the sheet was open in the hand, and a stricter reader might not. The box, the closed booklet, the insert and the screen recording were never returned. The median window was 19 seconds, so the contact sheet, not the window, sets the row's time.
The first stuck_spoken wording returned 6 windows: 4 real, 2 false and 1 missed. One false window was a participant guessing how the back of a doorbell comes off, which the reason text described as being not sure how to detach it; the other was a slip while stripping a wire. The wording in the table, after 1 rewording on the same corpus, returned 5 windows: 5 real, 0 false and 0 missed, including a statement we had not marked before searching (a participant saying they don't know which way a plate goes). For every real stuck window the contact sheet showed the part in hand, such as a doorbell with a small key in its back screw or a new base plate over old screw holes.
The phone_app query returned 5 windows: 5 real and 0 false, with a median window of 35 seconds; one was an edited insert filmed in another room, which a real session would not have. The part_fit query returned 6 windows: 4 real, 1 false (a hand pointing at screw holes after the plate was already up), 1 we could not settle from a wide shot, and it missed 1 of the sessions we had marked.
Consent, trimming from moderator notes and the user's browser upload were not exercised in our test run: we trimmed from subtitles, the clips were public, and the upload went through a script.
Done when every window of every category has a verdict in state.json and the user has seen the real, rejected and candidate counts per category.
Step 6: Assemble the log and confirm the sample
Goal: one table the researcher hands to the hardware PM and the packaging designer.
- Build one row per verified moment. Narrow start and end to the cells or transcript lines that show it, not the whole Vivu window:
participant_id,session_file,setup_step,category,start_mmss,end_mmss,quote,quote_source,what_the_frame_shows,frame_path,privacy_flag,status,attribution
P04,P04_setup.mp4,base,stuck,03:22,03:55,"the Allen key doesn't seem to fit",transcript,"Holds the doorbell face down and pushes the small key into the screw at its base",frames/stuck_P04_setup_215.png,,verified,
- Field mapping:
| Field | Source | If unavailable |
|---|---|---|
| participant_id | the file name with the confirmed pattern | UNCERTAIN |
| session_file | the trimmed file name from sessions.csv | none |
| setup_step | steps.json time ranges or the frames | UNCERTAIN |
| category | the search category | none |
| start_mmss, end_mmss | the contact sheet cells or transcript lines inside the window | the Vivu window, marked UNCERTAIN |
| quote | the transcript lines, word for word | NOT VERIFIED |
| quote_source | the session transcript or local speech to text | none |
| what_the_frame_shows | Claude's description of the full frame (inferred) | none |
| frame_path | the full frame the row was checked on | blank when the frame is privacy flagged |
| privacy_flag | what private content the frames show | blank |
| status | verified | candidate when it could not be checked |
| attribution | left empty for the researcher (guide, packaging, hardware or app) | blank |
- Show two or three sample rows and the mapping and wait for a yes before writing the full log. Say which fields are inferred: what_the_frame_shows is Claude's reading of the frame and setup_step can be a guess when the notes are coarse; if they are wrong, a box insert can read as the guide or a moment lands under the wrong step.
- Write setup_friction_log.csv and rejected.csv, and give the user the counts: rows per step and category and per participant, windows rejected per category and why.
In our test run the log and rejected.csv were built from the checked windows; the user's approval of the sample rows was not exercised in our test run.
Done when setup_friction_log.csv exists with one row per verified moment and the user has approved the sample rows.
Step 7: Create a Notion page (optional)
Goal: the log as a Notion page under the parent page the researcher chose.
- Only if the user asked for it in the inputs. Render the page from setup_friction_log.csv: one section per setup step, one line per row with participant, category, session file, time and quote or frame description. Use the session file and time, never a Vivu result page link (it expires after four hours). Leave out privacy flagged frames.
- Creating the page acts as the user. Name the parent page, show the full rendered page, and wait for an explicit yes. Record the page in state.json so a rerun never creates it twice.
Step 7 was not exercised in our test run: the page was rendered to a file and the Notion connector was never called.
Done when the approved page exists and is recorded in state.json, or the user chose setup_friction_log.csv only.
Compliance
- Index only sessions whose consent covers recording in the participant's home and uploading the video to a third party cloud service for analysis. Ask before Step 2 and leave out every session that is not covered. Do not run this skill on participants under 18; studies with minors need guardian consent and a separate review.
- Family members, house numbers, mail and screens with account details can appear in an in-home recording. Create the Vivu project as private (the default is visible to the whole organization). Frames with family members or private details get a privacy flag and never go into the log or a shared page; pick another frame or leave the row's frame blank.
- The trimmed sessions stay in the user's Vivu project until the user deletes them; the skill never calls vivu_delete_video or vivu_delete_project unless the user asks, and confirms first. If a participant withdraws, tell the user which videos to delete.
- No face, voice or identity recognition. Participant IDs come only from file names.
- The log records what sessions show and say. It never rates participants, and the attribution column is the researcher's call.
Known failure modes
| Symptom | Cause | Fix |
|---|---|---|
| (observed) the reason says the participant was unsure, but the transcript only has a guess; in our test run the first stuck_spoken wording had 2 false windows, one with the reason "explains they are not sure exactly how to detach the backplate" | the reason text is a paraphrase and can make a hedge sound like a stuck moment | judge stuck windows from the transcript lines only, and copy quotes from the transcript |
| (observed) a loose stuck wording returns slips and guesses; in our test run the first wording returned 6 windows with 2 false and missed 1 | a wording about being unsure also matches people thinking aloud | use the concrete wording in the table (won't fit, won't come off, isn't working, which way a part goes) and grep transcripts as a second pass |
| (observed) a window much longer than the moment; in our test run the phone_app median window was 35 seconds | precise returns a range that contains the moment | narrow the row's time to the contact sheet cells that show it |
| (observed) a part_fit window cannot be settled; in our test run 1 window was a wide shot where the parts were too small to see | hand actions are small in a wide tripod view | keep it as a candidate in rejected.csv; ask the moderator to frame the table and hands closer next round |
| (observed) the guide is in one hand while the participant reads the phone | people move between the sheet and the app at the pairing step | write the moment once under manual and once under phone_app, and say in what_the_frame_shows which one they were looking at |
| the retail box, a box insert or a booklet lying on the table is reported as the guide | visual search reads paper and cardboard coarsely | reject windows where the booklet is not open in or under the participant's hands |
| an empty result for a session | many friction moments are short or silent; an empty result does not prove the footage has no such moment | skim that session's contact sheet at a frame a second, and grep its transcript |
| the reason text quotes the participant with words they did not say | the reason is a paraphrase, not a transcript | copy quotes from the transcript only |
| a list stops at exactly maximum_results | the cap cut the list short | raise maximum_results and rerun that category |
| "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 | Claude in Chrome takes at most 10 MB per upload call | the user adds that file in the Vivu web app; never split or recompress it |
| a result's file name does not match sessions.csv | Vivu replaced spaces or punctuation in the name | compare names with those characters replaced by "_" |