theShortCut

the-shortcut is a Python package and CLI for local-first, AI-assisted video editing. Model stages may propose editorial intent; deterministic code owns source selection, frame and sample timing, timeline compilation, media execution, export, validation, and QC.

Status

The current package version is 1.0.0. The 1.0 contract covers the documented CLI, persisted data contracts, package contents, and supported delivery targets.

This status does not claim that model-assisted edits are professionally qualified. Editorial quality remains a review outcome. Inspect the current evidence-backed Aspect status locally:

python -m the_shortcut.cli qualify-aspects

Supported delivery targets

CapCut, FCPXML, Final Cut, DaVinci, and user-facing OTIO are reserved rather than supported runnable targets.

Install

Python 3.11 or newer is required. Published releases install with:

python -m pip install the-shortcut

To install from a source checkout in an activated virtual environment:

git clone https://github.com/xuctang/the-shortcut.git
cd the-shortcut
python -m pip install .
python -m the_shortcut.cli --help

For development:

python -m pip install -e '.[dev]'

Stable media execution requires ffmpeg and ffprobe on PATH:

ffmpeg -version
ffprobe -version

Inspect the installed runtime without media or model access:

python -m the_shortcut.cli list-workflows
python -m the_shortcut.cli list-aspects --workflow short_form
python -m the_shortcut.cli qualify-aspects

Project caches are explicit runtime data rather than invisible permanent storage. Inspect one cache without changing it, or move it reversibly into the resolved runtime workspace quarantine:

python -m the_shortcut.cli runtime-workspace \
  --root /absolute/runtime/root \
  --inspect-project-cache /absolute/runtime/root/users/USER/projects/PROJECT
python -m the_shortcut.cli runtime-workspace \
  --root /absolute/runtime/root \
  --quarantine-project-cache /absolute/runtime/root/users/USER/projects/PROJECT

The quarantine command never permanently deletes data. It accepts only the exact Project layout owned by the selected runtime workspace and reports the original and recovery paths. Inspection is portable; quarantine currently requires Linux or macOS so it can use an atomic, directory-anchored move.

Optional Python capabilities and platform troubleshooting are documented in Local Setup and Troubleshooting.

Start 1: edit through Codex

Open this repository in Codex, attach media or provide local paths, and state the requested edit in ordinary language, for example:

Turn these clips into a 45-second vertical product recap. Keep the original speech, use clean captions, and produce a review MP4.

The repository skills under .agents/skills/ handle onboarding and actionable video-edit intake. They preserve task-relevant instructions, place new media in the selected Project by default, build the current v3 intake, and run the same deterministic pipeline used by the CLI. Ask for one-time material explicitly when media should remain Run-owned rather than Project-owned.

If a selected Codex model stage waits, the workflow executes its immutable task bundle once and resumes through the exact invocation receipt. It does not choose a recent Run or reconstruct a request from memory. The corresponding CLI lifecycle is:

python -m the_shortcut.cli video-edit prepare REQUEST.json
python -m the_shortcut.cli video-edit run REQUEST.json
python -m the_shortcut.cli video-edit resume RECEIPT.json
python -m the_shortcut.cli video-edit status RUN_DIR

Codex supplies the model only when the selected Profile stage route declares Codex parent execution. It does not require an external model API credential. See Short-Form Pipeline for the intake, waiting, receipt, and artifact contracts.

Start 2: run a general local project

A minimal project contains requirements and at least one supported media file:

project/
  requirements.md
  raw_footage/
    A001.mp4
    A001.mp4.transcript.json  # required by speech-dependent original-audio paths

Run it with an explicit output directory and delivery target:

python -m the_shortcut.cli run ./project ./run --export-target review

Use --export-target premiere for the XML rough-cut bundle or --export-target ffmpeg for stems. The CLI also accepts repeatable --edit-aspect, an explicit processing mode, and run overrides; inspect the current arguments instead of copying an assumed configuration:

python -m the_shortcut.cli run --help

Profile-aware projects under users/<user_id>/projects/<project_id>/ resolve their selected Profile before execution. A standalone project directory is also valid. Generated state and deliverables stay under the requested Run directory.

Start 3: run short-form from a complete project

Use a registered Project plus a strict short_form_project_brief.v1:

python -m the_shortcut.cli short-form-project \
  ./project \
  ./short_form_project_brief.json \
  ./short-form-run \
  --planner deterministic

The Project/Profile owns the source universe, transcripts, references, processing configuration, and evidence providers. The brief owns narrative, duration, delivery, captions, audio, variants, and handoff intent. Missing required authority fails before media execution rather than receiving an invented default.

Model-assisted short-form uses the same entry point with one exact route file:

python -m the_shortcut.cli short-form-project \
  ./project \
  ./short_form_project_brief.json \
  ./short-form-run \
  --planner model_assisted \
  --llm-config ./llm_stages.json

Run a Codex-backed route through the Codex conversational workflow so the parent can execute and resume waiting task bundles. An explicitly configured LiteLLM route executes its selected provider/model Adapter. There is no silent fallback between Codex, LiteLLM, another model, or deterministic planning.

The full short-form contracts and examples live in Short-Form Pipeline.

Workflows and Aspects

One PipelineRuntime dispatches registered Workflows through exact Input and execution Adapter coverage. Each Workflow retains its own input, candidate, stage-order, timeline, and delivery contracts; the repository does not impose one universal candidate or timeline schema.

List the current executable Workflows and their bound atomic Edit Aspects:

python -m the_shortcut.cli list-workflows
python -m the_shortcut.cli list-aspects --workflow WORKFLOW_ID

Structured Workflows use their strict spec entry point:

python -m the_shortcut.cli workflow WORKFLOW_ID ./spec.json ./run

An Aspect is optional editing guidance plus any declared evidence and validation behavior. Runnable support and professional qualification are separate: experimental or unqualified status is disclosed, not hidden. See Workflows for the current registry and support matrix.

Model execution boundary

Model-assisted stages use the route selected by the active Profile or explicit run configuration:

• a Codex route declares parent execution, its executor skill, and sealed task payload policy;
• a LiteLLM route explicitly declares its provider, model, thinking level, timeout, sampling, and any credential reference required by that registered route.

The runtime does not choose a default model or silently substitute another route. Model output remains platform-independent intent and may reference only the candidate identities exposed by its stage contract. Deterministic code validates that output before compiling executable media operations.

Route details, sealed task bundles, retries, and failure behavior are owned by Model Stage Execution.

Architecture at a glance

raw request
  -> Workflow Input Adapter
  -> prepared request + Workflow registry resolution
  -> Workflow-owned evidence and candidate construction
  -> optional selected model stage
  -> deterministic validation and timeline compilation
  -> audio, captions, render, export, QC, and indexed artifacts

Shared runtime code owns orchestration, artifact publication, model-stage execution, and common delivery mechanics. Workflow Modules own domain input, candidate, planning, timeline, and validation semantics. Export Adapters own target-specific deliverables.

Invalid schemas, source/hash mismatches, unavailable required tools, impossible timeline state, and export contract failures stop execution. Weak evidence or subjective editorial quality remains diagnostic unless an explicit contract makes it a failure.

Read System Architecture Specification for the full runtime boundary and Documentation Index for the module, data-contract, capability, export, and ADR maps.

Repository layout

• the_shortcut/: package runtime, validators, compilers, Adapters, and CLI.
• .agents/skills/: repository-scoped Codex onboarding and execution skills.
• the_shortcut/resources/: packaged schemas, registries, configuration, and executor protocol.
• docs/: architecture, workflow, setup, release, and support documentation.
• tests/: deterministic contract, runtime, packaging, and acceptance tests.
• users/user_template/: example Profile and Project input structure.
• runs/: generated output when a caller explicitly chooses that location; generated runs are not source documentation.

Local verification

The standard local correctness gates do not require an LLM, VLM, ASR provider, Ollama server, or media-pipeline run:

python -m pip install -e '.[dev]'
python -m ruff format --check the_shortcut tests tools
python -m ruff check the_shortcut tests tools
python -m compileall -q the_shortcut tests tools
python -m pytest -q

Before publishing a candidate, also build and inspect both distribution formats:

python -m build
python -m twine check dist/*
python tools/verify_distribution.py dist

The complete clean-install and source-distribution checks are in the Release Checklist.

Documentation and project policy

• Documentation Index
• Local Setup and Troubleshooting
• Short-Form Pipeline
• System Architecture Specification
• Workflows
• Changelog
• Contributing
• Security Policy
• Release Checklist

The project is licensed under Apache-2.0. See LICENSE and NOTICE.