If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mltframework/shotcut shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 91% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mltframework/shotcut repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mltframework/shotcut.

What it runs against: a local clone of mltframework/shotcut — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mltframework/shotcut | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mltframework/shotcut. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mltframework/shotcut.git
#   cd shotcut
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mltframework/shotcut and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mltframework/shotcut(\\.git)?\\b" \\
  && ok "origin remote is mltframework/shotcut" \\
  || miss "origin remote is not mltframework/shotcut (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f ".github/workflows/build-linux.yml" \\
  && ok ".github/workflows/build-linux.yml" \\
  || miss "missing critical file: .github/workflows/build-linux.yml"
test -f ".github/copilot-instructions.md" \\
  && ok ".github/copilot-instructions.md" \\
  || miss "missing critical file: .github/copilot-instructions.md"
test -f "CuteLogger/include/Logger.h" \\
  && ok "CuteLogger/include/Logger.h" \\
  || miss "missing critical file: CuteLogger/include/Logger.h"
test -f ".clang-format" \\
  && ok ".clang-format" \\
  || miss "missing critical file: .clang-format"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mltframework/shotcut"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Shotcut is a free, open-source, cross-platform video editor built with Qt 6 and MLT (multimedia authoring framework) that provides a graphical interface for video composition, filtering, and export. It handles multimedia authoring across Windows, macOS, and Linux by wrapping MLT's powerful codec and effects pipeline in a Qt-based UI with QML for modern interface components. Monolithic Qt application: src/main.cpp and related C++ files form the core editor engine interfacing with MLT, while QML files (2.3M lines) define the UI layer in src/qml/. CMakeLists.txt orchestrates a single build target with vendored dependencies (CuteLogger logging library, drmingw debugging tools) bundled directly. GitHub workflows in .github/workflows/ handle multi-platform CI/CD.

Video creators, filmmakers, and open-source enthusiasts who need a professional-grade, non-linear video editor without subscription costs. Contributors are primarily C++/QML developers working on cross-platform multimedia applications and video processing pipelines.

Shotcut is production-ready and actively maintained. The project has multiple GitHub Actions CI workflows (build-linux.yml, build-macos.yml, build-windows.yml, build-windows_arm64.yml), uses CMake with presets for robust builds, and maintains a consistent release cadence with binaries published at shotcut.org. The codebase is large (3.4M lines C++, 2.3M QML) indicating mature feature completeness.

Primary risk is single/dual maintainer dependency (Dan Dennedy listed as main author with one contributor). The project depends on complex external multimedia stacks (MLT, FFmpeg, Frei0r, SDL, FFTW) which introduce transitive dependency risk and platform-specific build brittleness. No test framework visible in the file structure suggests limited automated testing coverage for a video processing tool where correctness is critical.

Active development with CI/CD pipelines for Linux, macOS, Windows (x86_64 and ARM64). The repo has Copilot integration hints (.github/copilot-instructions.md) and structured filter UI generation prompts (.github/prompts/new-filter-ui.prompt.md), suggesting ongoing work on filter authoring and AI-assisted development workflows. Translation infrastructure via Transifex indicates internationalization is actively maintained.

git clone https://github.com/mltframework/shotcut.git
cd shotcut
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -GNinja ..
cmake --build .
cmake --install .

Ensure Qt 6.4+, MLT, FFmpeg, Frei0r, SDL, and FFTW are installed (system-dependent; Qt Creator simplifies this).

Daily commands: After install, run shotcut or the installed binary directly. For development in Qt Creator: open CMakeLists.txt, configure with your Qt 6.4+ kit, and click Build/Run. CLI builds via cmake --build . in a separate build directory.

• CMakeLists.txt — Root build configuration defining all dependencies, platforms, and compilation targets—essential for understanding the project structure and dependencies.
• .github/workflows/build-linux.yml — Primary CI/CD pipeline for Linux builds; defines test, build, and deployment automation that all contributors must respect.
• .github/copilot-instructions.md — Contributor guidelines for AI-assisted development; establishes coding standards and conventions used throughout the project.
• CuteLogger/include/Logger.h — Core logging infrastructure used across the entire codebase; understanding this is critical for debugging and tracing execution flow.
• .clang-format — Code formatting standard enforced via CI; all code changes must conform to this specification.
• README.md — Primary project documentation; defines scope, feature set, and architecture rationale for the video editor.
• CMakePresets.json — Build presets and platform-specific configurations; critical for local development setup across Windows, macOS, and Linux.

• Qt GUI (QML — undefined

Add a new video filter or effect

1. Create a new filter preset file in filter-sets/ directory with your filter configuration and metadata (filter-sets/[Filter Name])
2. Define the filter UI in QML following the pattern in .github/instructions/qml.instructions.md (.github/instructions/qml.instructions.md)
3. Register the filter in the main CMakeLists.txt under the appropriate platform section (CMakeLists.txt)
4. Add icon asset for the filter in icons/dark/32x32/ directory (icons/dark/32x32/[filter-icon].png)

Add support for a new platform or architecture

1. Create a new build preset in CMakePresets.json with compiler, architecture, and platform-specific flags (CMakePresets.json)
2. Add a new GitHub Actions workflow in .github/workflows/ for the new platform (.github/workflows/build-[platform].yml)
3. Update CMakeLists.txt to add platform-specific dependencies and build rules (CMakeLists.txt)
4. Document platform requirements and build instructions in CONTRIBUTING.md (CONTRIBUTING.md)

Fix a code style or formatting issue

1. Review the clang-format configuration to understand the required style (.clang-format)
2. Apply clang-format to your modified files following the standard (.clang-format)
3. The CI pipeline will validate formatting via check-code-format.yml before merge (.github/workflows/check-code-format.yml)

• Qt Framework (CMake-based) — Provides cross-platform GUI, multimedia, and deployment tools; QML enables rapid UI development with declarative syntax.
• MLT (Media Lovin' Toolkit) — Industry-standard multimedia framework for video composition, effects, codecs, and real-time playback; core abstraction for media operations.
• CMake with Presets — Enables unified build configuration across Windows, macOS, Linux with different compilers and SDKs; presets simplify local development setup.
• CuteLogger — Lightweight, multi-appender logging library; supports console, file, and OS-specific outputs without Qt dependencies.
• GitHub Actions — Native CI/CD integration for automated builds, testing, and packaging across all supported platforms on each commit.

• Use MLT as media abstraction layer rather than direct codec/renderer integration

  • Why: MLT provides consistent API across codecs and OS; reduces platform-specific code; simplifies feature parity.
  • Consequence: Adds dependency on external library; performance bottlenecks in MLT affect entire editor; less control over low-level rendering.

• Qt for UI rather than web-based (Electron) or native (Cocoa/WinAPI)

  • Why: Qt offers true cross-platform parity; native look-and-feel on each OS; strong multimedia support; mature ecosystem.
  • Consequence: Larger binary footprint than web; steeper learning curve for web developers; requires Qt compilation on all platforms.

• Modular filter-sets as separate preset files rather than hardcoded filters

  • Why: Allows users and contributors to create custom filter presets without recompilation; easier discovery and sharing.
  • Consequence: Runtime parsing overhead; potential for invalid presets; harder to version-control filter changes across releases.

• CuteLogger for logging instead of Qt's built-in logging or spdlog

  • Why: Lightweight, no Qt dependency for standalone modules; multiple appender types; simple API.
  • Consequence: Less feature-rich than spdlog; smaller community; potential performance cost for high-volume logging.

• Real-time collaborative editing (not mentioned in roadmap or architecture)
• Cloud-based project storage or rendering (editor is desktop-only)
• GPU-accelerated encoding beyond MLT's capabilities (limited to MLT support)
• Embedded or mobile versions (Qt mobile ports not in scope; desktop only)
• Audio-only editing without video timeline
• VR/360° video editing as primary feature

MLT dependency brittleness: MLT version mismatches cause runtime crashes with cryptic error messages; verify exact MLT version in CI workflows. QML path resolution: QML files must be installed (cmake --install) or Shotcut fails silently to load the UI—running from build dir without install is broken. Platform-specific builds: Windows ARM64 requires separate SDK build (build-windows_arm64.yml); native builds may fail without matching toolchain. No in-tree tests: no visible test/ directory means manual testing required; changes to video processing logic carry high regression risk.

• MLT Producer-Consumer Pipeline — Shotcut's entire video processing model (sources, transitions, effects, export) is built on MLT's producer-consumer chain; understanding this abstraction is essential for modifying video processing logic.
• QML Property Binding & Reactive Updates — 2.3M lines of QML rely on property binding to keep UI in sync with video state (timeline position, filter parameters); critical for debugging UI responsiveness issues.
• Non-Linear Video Editing (NLE) — Shotcut implements standard NLE concepts (tracks, clips, keyframes, transitions); understanding this domain prevents architectural mistakes in timeline or composition features.
• Cross-Platform Build Abstraction (CMake Presets) — CMakePresets.json centralizes platform-specific compiler flags and paths; modifying builds for new platforms requires understanding this abstraction layer.
• Audio-Video Synchronization (A/V Sync) — Video editors must maintain frame-accurate sync between audio and video tracks; Shotcut's MLT integration handles this, but regressions here are catastrophic for users.
• Keyframe Interpolation & Animation — Video effects parameters are animated via keyframes; understanding interpolation curves and timing is essential for filter UI features and timeline scrubbing.

• mltframework/mlt — Shotcut's core multimedia authoring engine; all video processing, codec handling, and effects pipeline implementation lives here.
• obsproject/obs-studio — Alternative cross-platform Qt-based multimedia tool (streaming/recording); shares similar MLT/FFmpeg dependency stack and Qt UI patterns.
• kdenlive/kdenlive — Another Qt-based, open-source non-linear video editor; primary competitor with overlapping feature set and similar architectural decisions.
• FFmpeg/FFmpeg — Transitive dependency providing codec/format libraries; understanding FFmpeg's API is essential for video format support in Shotcut.
• dyne/frei0r — Video effects plugin framework integrated into Shotcut; contributes filters and transitions available in the UI.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for code format validation on all platforms

The repo has .clang-format config and check-code-format.yml workflow, but it only runs on Linux. Given that Shotcut is cross-platform (Qt/C++) with builds for Linux, macOS, and Windows, formatting checks should run on all platforms to catch platform-specific formatting issues early. This prevents inconsistent code style across contributions.

• [ ] Review .github/workflows/check-code-format.yml to understand current validation approach
• [ ] Extend the workflow to run on macos-latest and windows-latest runners in addition to Ubuntu
• [ ] Verify clang-format is available on all platforms and handles line endings correctly (especially Windows CRLF)
• [ ] Test the updated workflow on a branch to ensure it catches formatting issues consistently across platforms

Add unit tests for CuteLogger module with coverage reporting

CuteLogger is a vendored logging library (CuteLogger/ directory) with multiple appenders (Console, File, Rolling File, Android, OutputDebug). There's no evidence of unit tests for this critical component. Adding tests would ensure log output reliability across platforms and prevent regressions when updates are made.

• [ ] Create CuteLogger/tests/ directory with CMake test configuration
• [ ] Write tests for each appender class: ConsoleAppender, FileAppender, RollingFileAppender, AbstractStringAppender
• [ ] Test key scenarios: log rotation, file creation, thread safety, different log levels
• [ ] Integrate tests into CMakeLists.txt and add test execution to CI workflows (build-linux.yml, build-windows.yml, build-macos.yml)

Document QML filter UI patterns and create missing filter-set UI implementations

The repo has .github/instructions/qml.instructions.md and .github/prompts/new-filter-ui.prompt.md (AI prompts for filter creation), plus 4 example filter-sets in filter-sets/. However, there's likely a gap between the instruction documentation and actual implementation patterns. Creating a structured guide with code examples and potentially implementing missing filter UIs would help contributors submit higher-quality filter PRs.

• [ ] Review existing filter-sets (Glow Intensity, Obscure With Blur, etc.) and identify their QML structure and patterns
• [ ] Enhance .github/instructions/qml.instructions.md with concrete code examples showing filter UI implementation (parameter types, layouts, bindings)
• [ ] Document the relationship between filter-sets and MLT filter definitions
• [ ] Audit the codebase for TODO or incomplete filter implementations and create new filter-set examples for missing common filters

• Add unit tests for QML components in src/qml/ (video player, timeline, filter dialogs) using Qt Test framework—currently no test infrastructure exists for the 2.3M lines of QML code.
• Document the MLT pipeline integration in src/ with code comments and a ARCHITECTURE.md file—new contributors cannot easily understand how the Qt UI marshals requests to MLT's multimedia backend.
• Create a Makefile or shell script in the repo root to simplify local builds (cmake + ninja + install) for developers unfamiliar with CMake presets, reducing CI/local parity issues.

The Shotcut codebase shows a generally moderate security posture. The primary concerns are the inclusion of pre-compiled binary executables (drmingw tools) in version control, which increases supply chain risk, and the lack of visible dependency management practices (no lock files evident). The project appears well-maintained with CI/CD workflows (GitHub Actions) in place, which is positive. No obvious code-level vulnerabilities are apparent from the static file structure analysis, but deeper code review would be needed to assess injection risks, authentication/authorization mechanisms, and secure coding practices. The absence of a visible security policy is a minor governance concern. Recommendations focus on tightening dependency management, removing binaries from version control, and establishing clear security disclosure procedures.

• Medium · Third-party Debug Tool Included in Repository — drmingw/x64/bin/. The repository includes 'drmingw' (Dr. MinGW), a debug tool with compiled binaries (exchndl.dll, dbghelp.dll, mgwhelp.dll, symsrv.dll) checked into version control. Including binary executables in the repository increases the attack surface and makes it difficult to verify integrity and scan for malware. Fix: Remove binary files from version control and distribute them separately through signed releases or package managers. Use a .gitignore rule to exclude binaries. Consider documenting the tool's purpose and providing a secure download mechanism instead.
• Low · Missing Dependency Lock File — CMakeLists.txt, CuteLogger/CMakeLists.txt. The provided file structure does not show a lock file (package-lock.json, yarn.lock, Pipfile.lock, etc.) for dependency management. Without lock files, builds may be vulnerable to supply chain attacks through dependency version changes. Fix: Implement and commit dependency lock files to ensure reproducible builds. Use pinned versions for all third-party dependencies. Regularly audit dependencies using tools like OWASP Dependency-Check or Snyk.
• Low · No Security Policy Visible — Repository root. The repository structure does not show a SECURITY.md or security policy file for responsible vulnerability disclosure. This may prevent security researchers from reporting issues responsibly. Fix: Create a SECURITY.md file at the repository root that outlines how to responsibly report security vulnerabilities. Include a security contact email or use GitHub's security advisory feature.
• Low · CuteLogger License Clarity — CuteLogger/LICENSE.LGPL. CuteLogger is included as a subdirectory with an LGPL license (LICENSE.LGPL), while the main project is licensed under GPLv3. While these licenses can coexist, there is potential for license compliance confusion regarding derivative works and distribution. Fix: Document the license compatibility clearly in the main README.md and CONTRIBUTING.md. Ensure all binary distributions properly attribute the LGPL-licensed component. Consider consolidating license information.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.