# Stitch

> Play stills, dialogue, music, and video as one sequence in the browser with the stitch command. Use when the user runs /stitch, or asks to stitch, preview, or play a cut from local or remote (http(s) URL) image, audio, and video files.

- Skill: `openstory-so/stitch` (Agent Skill)
- Install (CLI): `npx get-skill add openstory-so/stitch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openstory-so/stitch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openstory-so (https://skillmd.com/u/openstory-so)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/openstory-so/stitch

---


# stitch

`/stitch` runs the `stitch` command and leaves it running. The page it opens is the player.

## Command

From the directory that holds the files, with paths that reach them, or with `http(s)` URLs anywhere a file goes:

```sh
npx @openstory/stitch@latest \
  --frame 9:16 \
  --music score.mp3 --music-gain -3 \
  --subs lines.srt \
  shot.mp4 --poster board.png --cue 0-1.5 "Love that accent." \
  board.png --audio line.wav --seconds 3 --cue 0-2 "Coming over?"
```

1. Put the stills and videos in play order. Each is a path or an `http(s)` URL. The command reads a URL itself and serves it to the page from its own origin, so a remote without CORS headers still plays and exports.
2. A `.mp4`, `.webm`, or `.mov` is a video. Its dialogue is the audio inside the file. Do not pass `--audio` for a video.
3. A `.png`, `.jpg`, `.jpeg`, or `.webp` is a still. The command reads its width and height.
4. `--audio` adds a line (a `.wav`, `.mp3`, `.m4a`, or `.ogg`) to the still before it. Repeat it for another line. The still stays up for the longer of `--seconds` and that sound. `--seconds` defaults to 4.
5. `--cue START-END TEXT` is a subtitle on the clip before it. Quote the text. Times are seconds from the start of that clip.
6. `--subs lines.srt` (or `.vtt`) is one subtitle file for the whole cut. Times in the file are from the start of the first clip. A cue that crosses a cut is split onto both clips. Use this instead of one `--cue` per line when a file already exists.
7. `--poster` is the still shown while the cut opens. It belongs on an opening video. `--fallback` is the picture tried when the still before it fails to load.
8. `--music` is the bed under the whole cut, a `.wav`, `.mp3`, `.m4a`, or `.ogg`. `--music-gain` changes only that bed, in dB. It defaults to 0. The page can turn that bed off; dialogue stays.
9. `--frame 9:16` (or `1080x1920`) is the shape of the page. Give it when the shape is known: without it the command reads the first clip to find out. Every clip is fitted into that box.
10. Run that `npx` command and give the user the `http://127.0.0.1:` URL it prints. Leave the process running until they are done. `--no-open` skips opening a browser.

## Sharing

`npx @openstory/stitch@latest bundle <dir> …` takes the same cut options and writes a folder: the player page, `cut.json`, and every file (a URL is downloaded) under `media/`. The folder plays from any static host, at any sub-path.

`npx @openstory/cli@latest share …` (the OpenStory CLI, not stitch) uploads that bundle to OpenStory and prints a link anyone can open. It takes the same cut options. The first share prints a short code and opens the approval page; let the user approve it. The key is kept in `~/.openstory/credentials.json`. Use `share` when the user wants to send the cut to someone, and `bundle` when they want the files themselves.

Without a shell, or when the files are not on disk, call `openstory_create_stitch` on the OpenStory MCP server instead (the OpenStory plugin connects it). It takes the same cut: each media slot is `{ url }` for a file the server can fetch, or `{ data, mimeType }` with base64 for a small file. Base64 travels through the model, so send stills and short lines inline and give clips as URLs. It returns the same kind of link. Prefer the command when the files are on disk: it uploads each file as it is, up to about 100 MB per file. Either way every still is checked for a real person; one who is needs the basis for using their likeness: `--portrait-rights <basis>` on the command, `portraitAttestation` on the tool.

## Installing this command

Prefer the OpenStory plugin, which includes this skill plus `create-style` and `create-sequence`: `npx skills add openstory-so/skills`. Grok, Claude Code, Codex, and the ChatGPT desktop app install that repo as a marketplace plugin named OpenStory. If `/stitch` is missing, tell the user to install the plugin.

`npx @openstory/stitch@latest skill` copies this skill and the player contract into `.agents/skills/` and `.claude/skills/`. `--global` copies both trees into the home directory.

## Embedding the player

Wiring `StitchedPlayer`, a `PlaybackClip` list, music, or an MP4 export is the `stitch-player` skill. Read that skill before writing a clip list.

