For founders working through an AI assistant. By the end you have a short MP4 of your app with chapter markers, background music and a voice track, and a credit line to publish with it. This page is a worked example. Options and error codes are in Record a demo video of the phone, including the music and narration errors.
Before you start
- The simulator is running (
shipvo sim) and your assistant is connected to@shipvo/mcp. ffmpegandffprobeon your PATH, andpython3for music.- Music needs the mixer script
scripts/video/bgmusic.py, which a repo checkout has. With an npm install, setSHIPVO_BGMUSICto the path of a copy of that script. Narration alone needs neither. npm i -D playwright && npx playwright install chromium.- For narration, a
.wavfile with your voice, for examplenarration.wav. Without a music service, setSHIPVO_MUSIC_FILEto a local track (an mp3). Otherwise a track is picked from Jamendo, which needs network access. The example on this page used a local track.
Ask your assistant
Open the Tide and Tackle app. Record a vertical demo. Add a chapter at each screen. Tap the search button. Stop and add music and my voice from
narration.wav.
It makes these calls, in this order. Tap refs such as e9 come from the screen tool: your assistant reads them from the latest screen, so yours will differ.
open_app { app: "tide" } -> session "tide-1a2b3c"
record_start { format: "9:16", title: "demo" } -> recording to .shipvo/recordings/demo-<time>.mp4 (1080x1920)
record_marker { caption: "Home" }
tap { session: "tide-1a2b3c", ref: "e9" } -> "Open search" (example ref)
record_marker { caption: "Search" }
record_stop { music: true, narration: "narration.wav" }
end_session { session: "tide-1a2b3c" }record_stop returns the file, the length, the chapters and any notes:
{
"file": ".shipvo/recordings/demo-<time>.mp4",
"duration_s": 0.692,
"chapters": [{ "t": 0.003, "caption": "Home" }, { "t": 0.618, "caption": "Search" }],
"notes": ["narration was 3.0 s and the video is 0.7 s: the narration was trimmed to the video length"],
"credits": ".shipvo/recordings/demo-<time>.credits.json"
}(Shortened. The ffprobe length is a little longer than duration_s because the audio mux adds a few hundredths of a second. The run on the sample app had no waits between steps, so the video is under a second. Waits longer than 0.6 s are cut, so a real demo needs real actions.)
Music
music: true mixes a music bed under the video. Open the .credits.json next to the MP4 and use its credit_line where you publish. It has the fields video, music (the track title, artist, provider, license and source) and credit_line, for example:
{ "video": "demo-<time>.mp4", "music": { "title": "...", "artist": "...", "provider": "...", "license": "...", "source": "..." }, "credit_line": "Music: \"<title>\" by <artist> (<provider>, <license>) <source>" }If the mixer script is missing you get music_unavailable. If it fails (for example python3 is not installed), you get music_failed. In both cases the silent video is kept.
Narration
narration is the path to a .wav. It is mixed over the video. If it is longer than the video it is cut to fit, and notes says so. If it is shorter, the rest is silent. With music: true, the music gets quieter while the voice plays. If the file is missing, you get the error narration_unreadable and the silent video is kept.
Check the file
ffprobe -v error -show_entries stream=codec_type,codec_name,width,height:format=duration -of default=nw=1 .shipvo/recordings/demo-<time>.mp4For the run above this printed an h264 video stream at 1080x1920 and an aac audio stream (duration 0.733 s):
codec_name=h264
codec_type=video
width=1080
height=1920
codec_name=aac
codec_type=audio
duration=0.733Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
recorder_unavailable | The tool that films the phone is not installed | Ask your assistant to run npm i -D playwright && npx playwright install chromium, then try again |
frame_unreachable | The phone is not running | Start it with shipvo sim or shipvo run, then record again |
recording_active | A recording is already running | Ask the assistant to stop it first |
encode_failed | ffmpeg is missing | Install ffmpeg, then record again |
narration_unreadable or music_failed | The voice file or music step failed | Your silent video is kept. Fix the file path or install python3, then add sound again |
| The video is under a second long | Waits longer than 0.6 s are cut, and steps with no wait are fast | Ask the assistant to tap and scroll through the real screens |
Every error code is explained in Record a demo video of the phone.
Next steps
- Record a demo video of the phone: all options and error codes.
- Videos