media-project

name	media-project
description	Package completed visual storytelling video outputs into OpenShot editor projects with the system-installed media-project command. Use when an agent needs to run or verify a playable .osp handoff, preserve production sidecar metadata, or decide whether a project is ready for OpenShot packaging.

Media-project OpenShot handoff

Use this skill when packaging selected generated clips into an OpenShot project with the media-project command. The command is expected to be installed at the system tool level before this skill is used, normally with uv tool install.

Do not assume the story project contains the media-project source tree. The story project normally contains only generated media, metadata, prompts, and editor handoff outputs.

Hard stop

Before running media-project package-openshot, verify both commands exist:

command -v media-project
command -v ffprobe

If media-project is absent, stop immediately and report that the command must be installed system-wide with uv tool install before packaging can proceed. Do not look for repository-local source directories or try to run the command through a project checkout.

If ffprobe is absent, stop immediately. Do not run the packager, do not write a minimal .osp, and do not tell the user the project is packaged. Report that ffprobe is required because OpenShot playback depends on full FFmpeg reader metadata in both files[] and clips[].reader.

Inputs

Only package a project after video-generator has produced reviewed local media and these project-root-relative files:

• generated/assembly_order.md
• generated/generation_log.md
• every selected local video file named by those tables

Preferred generated/assembly_order.md columns are:

Column	Meaning
Order	Final timeline order.
Shot ID	Stable shot identifier.
Sub-clip	Sub-clip identifier.
Selected clip	Project-root-relative local video path.
Boundary after	Edit-boundary or transition intent after the clip.
Notes	Editor handoff notes.

Some older assembly files may use File instead of Selected clip or Boundary (next) instead of Boundary after. Treat those as compatibility aliases only when the installed tool version documents support for them.

Sub-clip is mandatory even when a shot was not decomposed into separate sub-clips. The packager matches assembly rows to generation-log rows using Shot ID, Sub-clip, and the selected local file path, so the same non-empty Sub-clip value must appear in both tables. For non-decomposed shots, use - as the placeholder in both generated/assembly_order.md and generated/generation_log.md; do not leave the cell blank or omit the column.

generated/generation_log.md must identify the same selected files and include completed statuses, accepted review states, duration metadata, model/job metadata, actual file size, actual resolution, prompt hash, and audio mute intent. Do not package blocked, missing, incomplete, or unreviewed required clips.

Command

Run the already installed command from the story project repository or from any working directory where project-root paths are clear:

media-project package-openshot \
  --project-root /path/to/story-project \
  --assembly-order generated/assembly_order.md \
  --generation-log generated/generation_log.md \
  --manifest prompts/manifest.md \
  --output generated/media-project/project.osp \
  --sidecar generated/media-project/media-project.json

The command refuses to overwrite existing outputs unless --force is passed. Use --force only when replacing the generated .osp and sidecar is intentional.

Expected .osp shape

A playable OpenShot handoff needs full FFmpeg reader metadata. Check generated projects for these invariants:

• files[] entries are full FFmpegReader objects, not minimal path records.
• Each clips[] entry has a reader object with the same media metadata as its matching file entry.
• reader.type is FFmpegReader.
• reader.duration_strategy is VideoPreferred.
• Reader metadata includes codecs, stream indexes, bit rates, time bases, frame count, file size, duration, frame rate, dimensions, display ratio, sample rate, channel data, pixel data, and container metadata.
• Clip gravity is integer 4, and clip scale is integer 1.
• Clip layer matches an OpenShot layer number such as 1000000, and the project has a matching layers[] entry.
• Clip properties such as alpha, volume, time, transforms, audio/video flags, and waveform colour are OpenShot keyframe curve objects with Points, not scalar values.

The sidecar JSON remains the production provenance record. Preserve transition intent there and in clip metadata; do not invent OpenShot transition effects unless the tool version explicitly supports them with a verified reference shape.

Verification

After packaging, inspect the generated project before handing it off:

jq '.files[0].type, .clips[0].reader.type, .clips[0].gravity, .clips[0].scale, .clips[0].layer' \
  /path/to/story-project/generated/media-project/project.osp

Expected values are:

"FFmpegReader"
"FFmpegReader"
4
1
1000000

When OpenShot is available, perform a manual smoke test: open the .osp, press play on the timeline, and verify that at least the first selected clip decodes and plays rather than merely appearing as a timeline block. If OpenShot is not available in the current environment, report that the manual smoke test was not run.