Skip to content

AGENTS.md

Latest commit

 

History

History
96 lines (66 loc) · 4.39 KB

AGENTS.md

File metadata and controls

96 lines (66 loc) · 4.39 KB
Raw

Shotcut — Workspace Instructions

Shotcut is a free, open-source, cross-platform video editor built on Qt 6 and the MLT multimedia framework.

Build and Run

# Configure (from repo root; output goes to build/cc-debug)
cmake --preset cc-debug

# Reformat code with clang-format
cmake --build build/cc-debug --target clang-format

# Build
cmake --build build/cc-debug

# Run directly from build tree
build/cc-debug/src/shotcut

The default preset cc-debug (defined in CMakePresets.json) uses Ninja, gcc or clang from $PATH and Qt 6.10.3 from ~/Qt/6.10.3, and produces a Debug build.

To properly debug on Windows you must set the environment variable QSG_RHI_BACKEND=d3d11 to prevent running as a child process detached from the debugger.

Architecture

Singleton Macro Role
Mlt::Controller MLT Media engine: producer/consumer/seek/profile
MainWindow MAIN Central hub; owns all docks, undo stack, layout
ShotcutActions Actions Global QAction registry keyed by string
ShotcutSettings Settings QSettings-backed properties; bindable from QML

Data flow: UI events → Actions["someKey"] → undoable QUndoCommand in src/commands/ → MLT producer/filter mutation → Qt signals → model updates → QML views re-render.

QML views (in src/qml/views/): Timeline, Filter, and Keyframes panels are QML; individual filter parameter UIs live in src/qml/filters/<filter-name>/.

Docks (src/docks/): All panels are QDockWidget subclasses — Timeline, Playlist, Encode, Filters, Keyframes, Markers, Subtitles, Jobs, Recent, Files, Scope, Notes.

Models (src/models/): Qt item models bridge C++ data to QML. MultitrackModel is the timeline; PlaylistModel is the source bin.

Code Conventions

  • Member variables: m_ prefix (e.g., m_position, m_gridButton)

  • Class naming: PascalCase; methods/variables: camelCase

  • Slot naming: on<ObjectName><SignalName>() (e.g., onGridToggled, onFrameDisplayed)

  • Header guards: #ifndef CLASSNAME_H / #define CLASSNAME_H

  • Signal/slot style: Do not replace old SIGNAL()/SLOT() macros unless the entire containing block is already using the new-style pointer syntax — do not mix old macros and new-style function pointers in the same block. Use new-style QObject::connect() with function pointers or lambdas for all new code.

  • Action registration: Add new actions in setupActions() or analogous setup functions; register with Actions.add("keyName", action, tr("Group")).

  • Grid/zoom data encoding: Integer data() on QAction encodes the grid type:

    # Type Range / Values Examples
    1 Pixel grids >= 10000 10010 = 10 px, 10020 = 20 px
    2 Safe-area presets specific values 8090, 95
    3 Aspect-ratio frame overlays 20001–29999 20001 = 1:1, 20043 = 4:3, 20169 = 16:9, 20916 = 9:16

  • Update the copyright year in all modified files.

Key Entry Points

  • src/main.cpp — application entry
  • src/mainwindow.cpp — central UI coordination
  • src/player.cpp — video player widget with transport/zoom/grid controls
  • src/mltcontroller.cpp — MLT wrapper
  • src/actions.cpp — global action registry
  • src/settings.cpp — persistent settings

No Automated Tests

There are no C++ unit tests. The only automated tests are JavaScript tests for EDL/chapters export:

node src/qml/export-edl/test-node.js
node src/qml/export-chapters/test-node.js

Dependencies

Qt 6.4+, MLT++ ≥ 7.36.0 (via pkg-config), FFTW, FFmpeg, Frei0r, SDL2. See CMakeLists.txt for the full list.

Missing or Incompatible Dependencies

If configure or build fails due to missing or incompatible dependencies:

  1. Report the missing/incompatible package name and required version in the error output.
  2. Suggest installing or upgrading the package using the platform package manager.
  3. Re-run configure:
cmake --preset cc-debug
  1. If Qt is not found, verify Qt 6.10.3 is installed and available at ~/Qt/6.10.3, or set CMAKE_PREFIX_PATH to the correct Qt location.
  2. If MLT is not found, verify pkg-config --modversion mlt++ works and reports version 7.36.0 or newer.

When dependency checks fail, stop and provide a clear remediation message instead of continuing with partial setup.