Skip to content

concat

Purpose

Build one linear output from multiple videos.

concat supports two usage styles:

  • quick file-list mode for fast playlist-style outputs
  • playlist JSON mode for refined per-clip timing and marker control

Usage

video-edit concat output.mp4 clip1.mp4 clip2.mp4 clip3.mp4

Build from a folder of videos:

video-edit concat output.mp4 --input-dir clips

Concatenate from a playlist manifest:

video-edit concat output.mp4 --playlist examples/manifests/concat-playlist.v1.json

Generate a manifest-style JSON preview instead of rendering:

video-edit concat output.mp4 --input-dir clips --json-preview

Generate a full preview with explicit defaults and editable fields:

video-edit concat output.mp4 --input-dir clips --json-preview --full-preview

Planned refined mode:

video-edit concat output.mp4 --playlist playlist.json

Example playlist manifest:

examples/manifests/concat-playlist.v1.json

Notes

  • Requires at least two input files
  • You can provide explicit input files or --input-dir, but not both at the same time
  • You can provide explicit input files, --input-dir, or --playlist, but only one source mode at a time
  • --input-dir discovers supported video files and sorts them by filename
  • --json-preview prints a bare-bones manifest-style JSON scaffold and exits without rendering
  • --json-preview --full-preview prints a fuller scaffold with defaults and explicit editable fields
  • --playlist accepts the same manifest-style JSON scaffold generated by preview mode
  • a ready-to-edit example playlist manifest lives at examples/manifests/concat-playlist.v1.json
  • reusable title styling is defined once in manifest title_styles and referenced per item
  • Stream copy is the default when compatible
  • Use --reencode if the inputs do not concatenate cleanly
  • If you use --start, --end, --spacer-seconds, --audio-fade-seconds, or --markers, concat automatically switches to a filter-based render path and re-encodes the output
  • --markers creates clip-start chapter markers from normalized filenames
  • filename marker labels replace underscores and hyphens with spaces
  • --start and --end are applied to each input clip using timecodes relative to that source video
  • --json-preview is useful when you want a quick generated playlist that you can reorder and edit by hand
  • bare preview is optimized for quick cleanup and reordering
  • full preview is optimized for exposing the editable structure and available knobs up front
  • Validate playlist manifests with video-edit validate ... before rendering from --playlist
  • In v1 planning, quick mode may grow support for:
  • optional black spacers between clips
  • optional clip-start markers derived from normalized filenames
  • simple global trim and audio fade defaults
  • Playlist mode is intended to support:
  • source-relative per-clip start and end
  • per-clip markers
  • simple per-clip audio fade overrides
  • simple per-clip text titles with reusable manifest title styles
  • future interstitial controls
  • Current playlist support is intentionally narrow:
  • ordered item paths
  • per-item start, end, or duration
  • per-item markers
  • per-item title, title_start, title_duration, and title_style
  • defaults plus per-item overrides for spacer and audio fade values
  • manifest-level title_styles for reusable concat title styling
  • See Manifest Formats for the concat playlist manifest structure