Quickstart

This guide walks through the fastest path to a usable result with videoedit.

It assumes:

you are new to Python tooling
you want to work from PowerShell first
you want to concatenate a folder of videos using the current defaults

If you prefer Git Bash or WSL2 later, see Bash Integration.

1. Get the library

Open PowerShell in the project folder and create a local virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

This installs:

the video-edit command
the Python package in editable mode
development tools such as pytest

2. Make sure FFmpeg is available

This project uses the system ffmpeg and ffprobe executables.

Check they are available:

ffmpeg -version
ffprobe -version

If PowerShell says the commands are not found, install FFmpeg and make sure it is on your PATH before continuing.

3. Choose how you want to run the CLI

After installation, you can usually run either form:

video-edit probe .\input.mp4
python -m videoedit probe .\input.mp4

For day-to-day use in this repo, video-edit ... is the most convenient.

4. Concatenate a folder of videos with defaults

Put your source videos in a folder such as .\clips.

Then run:

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

This will:

discover supported video files in .\clips
sort them by filename
concatenate them in that order
write the result to .\output.mp4

5. Preview a playlist manifest before rendering

If you want an editable JSON scaffold first, generate one from the same folder:

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

For a fuller scaffold with defaults and more editable fields:

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

Copy that JSON into a file such as .\playlist.json, then edit the order or timing as needed.

6. Validate the playlist

Before rendering from a manifest, validate it:

video-edit validate .\playlist.json

If the manifest is valid, the command prints a short summary and exits with code 0.

7. Render from the playlist

Once the playlist looks right:

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

8. Use the library API directly

If you are integrating videoedit into another Python app, the service and manifest helpers are the canonical API:

from pathlib import Path

from videoedit import VideoEditingService, load_manifest, plan_render, summarize_plan

service = VideoEditingService()
manifest = load_manifest(Path("playlist.json"))
plan = plan_render(Path("playlist.json"))
summary = summarize_plan(Path("playlist.json"))

Use the higher-level render helpers when you already have a manifest on disk:

from pathlib import Path

from videoedit import render_canvas, render_playlist, render_timeline

render_playlist(Path("playlist.json"))
render_timeline(Path("timeline.json"))
render_canvas(Path("canvas.json"))

9. Normalize mismatched clips before a render

If your source clips do not share the same shape or frame rate, normalize them first and render from the normalized outputs later:

from pathlib import Path

from videoedit import VideoEditingService

service = VideoEditingService()
service.normalize_video(
    input_path=Path("portrait-source.mp4"),
    output_path=Path("portrait-source.norm.mp4"),
    width=160,
    height=90,
    fps=24,
)

That workflow is especially useful before timeline or playlist rendering when the original material comes from mixed devices or exports.

10. Know what the backend can do today

The current backend is now broader than the first concat-only walkthrough:

concat playlist rendering with titles, markers, fades, and spacers
timeline rendering from cut-list style manifests
canvas rendering, including multi-panel layouts, finales, and audio mixes
normalization before rendering when source footage is mismatched

Common questions

How do I set the gap between videos to `0`?

In a concat playlist manifest:

"defaults": {
  "spacer_seconds": 0.0
}

For one specific item:

{
  "path": "clips/topic-b.mp4",
  "spacer_seconds": 0.0
}

How do I set the fade in and fade out timing of the audio?

In the playlist defaults:

"defaults": {
  "audio_fade_in_seconds": 0.5,
  "audio_fade_out_seconds": 0.5
}