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/Marginal/QuickLookVideo 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 1w ago
• 3 active contributors
• GPL-2.0 licensed
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ 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 Marginal/QuickLookVideo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Marginal/QuickLookVideo.

What it runs against: a local clone of Marginal/QuickLookVideo — 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 Marginal/QuickLookVideo | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.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 ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Marginal/QuickLookVideo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Marginal/QuickLookVideo.git
#   cd QuickLookVideo
#
# 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 Marginal/QuickLookVideo and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.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 "formatreader/formatreader.swift" \\
  && ok "formatreader/formatreader.swift" \\
  || miss "missing critical file: formatreader/formatreader.swift"
test -f "formatreader/videotrackreader.swift" \\
  && ok "formatreader/videotrackreader.swift" \\
  || miss "missing critical file: formatreader/videotrackreader.swift"
test -f "app/AppDelegate.swift" \\
  && ok "app/AppDelegate.swift" \\
  || miss "missing critical file: app/AppDelegate.swift"
test -f "mdimporter/GetMetadataForFile.swift" \\
  && ok "mdimporter/GetMetadataForFile.swift" \\
  || miss "missing critical file: mdimporter/GetMetadataForFile.swift"
test -f "formatreader/formatreaderfactory.swift" \\
  && ok "formatreader/formatreaderfactory.swift" \\
  || miss "missing critical file: formatreader/formatreaderfactory.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/Marginal/QuickLookVideo"
  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).

QuickLookVideo is a macOS system extension that enables Finder, QuickLook, and Spotlight to recognize and display thumbnails, previews, cover art, and metadata for 50+ video and audio formats (Matroska, WebM, AVI, VP8/VP9, AV1, HEVC, etc.) that macOS natively does not support. It bridges the gap between AVFoundation's limited codec/container support and modern multimedia files by providing a Spotlight metadata extension and two Media Extensions that extend the system's media capabilities. Three-module architecture: (1) app/ contains the installer/UI app with AppDelegate, CoverArtView, and CrashReportView for user interaction; (2) formatreader/ is the core media engine using Swift-Objective-C bridges (formatreader-bridge.h, callbacks.m) to wrap libavformat/libavcodec for decoding and extracting metadata (audiotrackreader.swift, decodedsamplecursor.swift); (3) the QLVideo.xcodeproj coordinates both as a macOS application bundle. The project uses .xcodeproj for dependency management and build configuration rather than Swift Package Manager.

macOS users who work with non-standard video/audio formats (filmmakers, video editors, archivists, software developers handling diverse media) who expect Finder previews and metadata to work seamlessly. Maintainers are open-source contributors interested in system-level media support and AVFoundation workarounds.

Actively maintained and production-ready. The project has been under active development since 2014, with Swift/Objective-C/C codebase totaling ~328K lines. The presence of structured source (formatreader/, app/ modules), comprehensive BUILDING.md documentation, DMG distribution config, and recent language diversity suggests ongoing maintenance. Appears to be a mature, single-maintainer project with real users (GitHub wiki with Getting Started and Troubleshooting guides).

Single-maintainer risk is significant (Marginal org appears to be one developer). The reliance on private AVFoundation extensions and low-level media callbacks (callbacks.m/h) creates tight coupling to macOS versions, making compatibility fragile across OS updates. No visible CI/CD pipeline in the file list, test suite presence is unclear, and the GPL v2 license may limit corporate adoption. The formatreader module's Objective-C bridging and direct ffmpeg/libavformat integration suggests potential memory safety and security surface area.

Unable to determine from file structure alone—no git log, PR list, or issue tracker visible in the provided data. However, the language distribution (Swift 295K > Shell/C/Obj-C) and presence of recent Swift files (audiotrackreader.swift, decodedsamplecursor.swift with modern naming) suggest active migration from Objective-C to Swift. The .xcstrings files (mul.lproj/Main.xcstrings) indicate ongoing localization work.

git clone https://github.com/Marginal/QuickLookVideo.git
cd QuickLookVideo
open QLVideo.xcodeproj

Then read BUILDING.md for compilation steps (likely requires Xcode and ffmpeg libraries via Homebrew). No package.json/CocoaPods/Carthage visible, so build uses Xcode project directly.

Daily commands:

xcodebuild -scheme QLVideo -configuration Release

Then install the .app or .qlgenerator bundle into ~/Library/QuickLook or /Library/QuickLook. See BUILDING.md and QLVideo.dmgbuild for distribution setup. No traditional 'dev server'—this is a system extension that auto-activates on installation.

• formatreader/formatreader.swift — Core media file reader abstraction that parses and demultiplexes video/audio tracks from non-native formats; every codec integration flows through this.
• formatreader/videotrackreader.swift — Video track decoding pipeline; responsible for frame extraction used by QuickLook thumbnails and previews.
• app/AppDelegate.swift — Main application entry point and coordinator for the QuickLook, Spotlight, and Media Extensions ecosystem.
• mdimporter/GetMetadataForFile.swift — Spotlight metadata extraction entry point; bridges FFmpeg format readers to macOS Spotlight indexing.
• formatreader/formatreaderfactory.swift — Factory pattern implementation that instantiates format-specific readers based on file type detection.
• formatreader/callbacks.m — C/Objective-C callbacks for FFmpeg integration; handles low-level audio/video stream callbacks.

Add Support for a New Video Codec

1. Verify FFmpeg has the codec available by building with scripts/buildffmpeg (scripts/buildffmpeg)
2. Create a new specialized track reader if needed (e.g., videotrackreaderdv.swift for DV), or extend videotrackreader.swift (formatreader/videotrackreader.swift)
3. Update formatreaderfactory.swift to detect the new codec and instantiate the correct reader (formatreader/formatreaderfactory.swift)
4. Test frame extraction via FormatReader; handle edge cases in decodedsamplecursor.swift if frame caching fails (formatreader/decodedsamplecursor.swift)
5. If metadata is needed, update mdimporter/GetMetadataForFile.swift to extract codec-specific attributes (mdimporter/GetMetadataForFile.swift)

Add Support for a New Container Format

1. Ensure FFmpeg can parse the container by verifying buildffmpeg script includes it (scripts/buildffmpeg)
2. Update formatreader.swift to detect the new format and initialize FFmpeg correctly (formatreader/formatreader.swift)
3. Use packetdemuxer.swift to extract audio and video packets; no new demuxer needed if FFmpeg handles it (formatreader/packetdemuxer.swift)
4. Add format-specific metadata extraction in mdimporter/GetMetadataForFile.swift (mdimporter/GetMetadataForFile.swift)

Add a New Metadata Field to Spotlight Indexing

1. Define the metadata key in mdimporter/en.lproj/schema.strings (mdimporter/en.lproj/schema.strings)
2. Extract the value in mdimporter/GetMetadataForFile.swift using FormatReader or AudioTrackReader (mdimporter/GetMetadataForFile.swift)
3. Add the same schema key to all language localizations (mdimporter/*/schema.strings) (mdimporter/fr.lproj/schema.strings)
4. Test metadata indexing by rebuilding and re-importing a test file in Spotlight (mdimporter/GetMetadataForFile.swift)

• FFmpeg (C library) — Only cross-platform library supporting 100+ audio/video codecs and container formats; required for non-native format parsing.
• macOS QuickLook/Spotlight Extensions — System sandbox security model mandates separate extension processes; allows thumbnail/metadata extraction without full app launch.
• Swift + Objective-C interop — Leverages modern Swift for business logic while maintaining C callback compatibility with FFmpeg's C API.
• dav1d (AV1 decoder) + zimg (color space converter) — Specialized high-performance libraries for AV1 and advanced color space conversions not available in FFmpeg's default build.

• Separate metadata indexing via Spotlight mdimporter vs. inline extraction

  • Why: Spotlight requires a separate sandboxed process; avoids parsing every file on every Finder browse.
  • Consequence: Metadata updates are asynchronous (eventual consistency); newly added files may not be indexed immediately.

• Frame decoding in memory vs. streaming to disk

  • Why: Thumbnail generation requires fast random-access frame seeking; in-memory decoded sample cursor enables ~50ms thumbnail generation.
  • Consequence: High memory usage for long videos; could exhaust RAM on resource-constrained systems if multiple large files are previewed simultaneously.

• FFmpeg built as custom static libraries rather than system dynamic links

  • Why: Ensures codec support is always available (e.g., AV1, VP9) regardless of macOS version; avoids dependency on system FFmpeg.
  • Consequence: Larger app bundle (~100–200 MB); longer build times; requires rebuild for each macOS version update.

• DV codec handled by specialized VideoTrackReaderDV instead of generic FFmpeg path

  • Why: DV requires frame-accurate extraction; generic path would lose quality or precision.
  • Consequence: Code duplication; maintenance burden for DV-specific edge cases.

• Real-time video playback (QuickLook is preview-only, not a media player)
• Transcoding or format conversion
• Hardware acceleration (decoding is CPU-bound; no GPU support)
• Audio-only metadata extraction via AVFoundation (requires custom FFmpeg parsing)
• Support for copy-protected or DRM-encumbered formats
• Windows or Linux support (macOS QuickLook/Spotlight extensions are platform-specific)

1. ffmpeg dependencies not in repo: libavformat/libavcodec must be pre-installed (likely via Homebrew or compiled locally); no CocoaPods/SPM lock file visible, so build environment is fragile. 2. macOS version coupling: System extensions (Spotlight, Media Extensions) are tightly bound to specific macOS versions; changes in AVFoundation or extension APIs between OS releases break functionality. 3. Code signing and entitlements: The .entitlements files (formatreader.entitlements, QuickLookVideo.entitlements) require proper signing with Apple Developer certificates; local builds may fail notarization. 4. Objective-C memory management: callbacks.m uses manual memory management and C callbacks—potential for leaks if not careful, especially in error paths. 5. Single-threaded ffmpeg usage: libavformat is generally not thread-safe; the formatreader likely serializes access, so concurrent thumbnail generation could bottleneck.

• QuickLook Generator Extensions — QLVideo's primary mechanism for injecting thumbnail/preview generation into Finder—understanding QL plugin architecture is essential for debugging preview failures and adding new preview types
• Media Extensions (AVFoundation) — Modern (Monterey+) macOS mechanism to extend AVFoundation's codec/format support without modifying the system; QLVideo uses this to make non-native formats decodable by the OS, not just by the app
• Spotlight Metadata Extensions — Enables Finder to index and search video metadata (title, duration, codecs) for non-native formats; critical for full-text search and file sorting by metadata attributes
• libavformat Container Demuxing — The ffmpeg library QLVideo wraps; understanding how libavformat detects container types, parses headers, and streams frames is necessary to debug format detection failures and add new container support
• Swift-Objective-C Bridging — QLVideo bridges Swift (modern app code) with Objective-C (system framework integration) and C (libav* libraries); understanding bridging headers and @objc annotations is critical for any cross-language modifications
• Codec Profile and Level Detection — Different video codecs (H.264, HEVC, VP9, AV1) have profiles/levels that affect decoding requirements and compatibility; QLVideo must correctly identify these to generate compatible previews
• Memory-Mapped I/O with Custom Callbacks — formatreader's callbacks.m implements custom I/O to handle unusual file access patterns (encrypted containers, network streams, sparse files); understanding ffmpeg's AVIOContext is key to extending this

• Perian/Perian — Direct spiritual predecessor—Perian was the QuickTime equivalent before AVFoundation; understanding its approach to codec extension informs QLVideo's architecture
• mpv-player/mpv — Comprehensive ffmpeg/libavformat wrapper with robust codec and container support; potential source for handling edge cases and untested format combinations
• FFmpeg/FFmpeg — Core dependency; understanding libavformat's format detection and libavcodec's codec capabilities is essential for extending QLVideo's format support
• HandBrake/HandBrake — Similar macOS video tool that wraps libav* libraries; reference for safe Objective-C bridging patterns and handling diverse input codecs

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 comprehensive unit tests for formatreader module

The formatreader directory contains critical decoding logic (videotrackreader.swift, audiotrackreader.swift, samplecursor.swift, etc.) but has no visible test files. Given this handles parsing diverse codecs (VP9, HEVC, AV1, etc.), unit tests would catch regressions and validate codec-specific edge cases. This is especially valuable since the module bridges to Objective-C callbacks (callbacks.h/m).

• [ ] Create Tests/FormatReaderTests/ directory structure
• [ ] Add tests for formatreader.swift factory methods with various container formats
• [ ] Add tests for videotrackreader.swift with sample files (matroska, webm, mov)
• [ ] Add tests for audiotrackreader.swift with non-native codecs (Vorbis, WMA)
• [ ] Add tests for samplecursor.swift time-seeking logic with edge cases
• [ ] Test the Objective-C callback bridge (callbacks.m) integration

Add GitHub Actions CI workflow for building and code signing

The repo contains an Xcode project (QLVideo.xcodeproj) and dmg build config (QLVideo.dmgbuild) but no visible CI pipeline. A GitHub Actions workflow would validate builds on every PR, catch Swift compilation errors early, and could automate test execution for the formatreader module. BUILDING.md suggests there are build steps that should be automated.

• [ ] Create .github/workflows/build.yml workflow file
• [ ] Add step to validate Swift syntax and compile QLVideo.xcodeproj
• [ ] Add step to run any existing unit tests (once formatreader tests are added)
• [ ] Add step to validate the mdimporter and formatreader extension builds
• [ ] Document macOS version requirements (minimum deployment target) in workflow
• [ ] Add workflow status badge to README.md

Document supported codecs and container formats with test coverage matrix

README.md lists supported formats and codecs (VP9, HEVC, Matroska, WebM, etc.) but lacks a structured reference. Create a detailed compatibility matrix document showing which codecs work in which containers, linked to specific test files. This helps users troubleshoot and guides contributors toward gaps in codec support.

• [ ] Create SUPPORTED_FORMATS.md documenting each container format (Matroska, WebM, AVI, etc.)
• [ ] Create a table showing codec × container compatibility matrix
• [ ] For each codec, reference the relevant videotrackreader.swift or audiotrackreader.swift implementation
• [ ] Add known limitations or edge cases (e.g., Dolby Vision constraints)
• [ ] Link test case files that validate each codec-container pair
• [ ] Update README.md to reference SUPPORTED_FORMATS.md instead of inline list

• Add unit tests for formatreader/audiotrackreader.swift—currently no test files visible; create XCTest cases for metadata extraction from sample .mkv, .webm, .f4v files to improve reliability and prevent regression.
• Document the ffmpeg linking process in BUILDING.md with exact Homebrew commands and version constraints—new contributors report build failures; add a troubleshooting section with common linker errors and fixes.
• Refactor callbacks.m error handling to use Swift Result<T, Error> types in the formatreader-bridge.h—currently errors are likely propagated via NSError/out params, which is unidiomatic for modern Swift and error-prone.

The QuickLookVideo application has moderate security concerns primarily related to untrusted media file processing, unsafe C/Objective-C bridge code, and system-level metadata extraction. The application processes arbitrary video and audio files provided by users, which inherently carries risks of exploitation through malformed or malicious files. The use of FFmpeg-based decoding and memory-unsafe bridge code increases vulnerability

• High · Unsafe Media File Processing — formatreader/ (particularly formatreader.swift, videotrackreader.swift, audiotrackreader.swift, callbacks.m). The application processes untrusted media files (video/audio) from user-provided sources without apparent sandboxing or validation. The formatreader component uses FFmpeg-based decoding (inferred from averror.swift, callbacks.m) which has a history of vulnerabilities. Processing malformed or malicious media files could lead to buffer overflows, arbitrary code execution, or denial of service. Fix: Implement strict input validation on media files before processing. Consider using sandboxing (App Sandbox entitlements) to limit the impact of potential exploits. Keep FFmpeg and related libraries updated. Implement fuzz testing for media file parsing.
• High · Potential Unsafe Objective-C Bridge — formatreader/callbacks.m, formatreader/callbacks.h, mdimporter/mdimporter-bridge.h, formatreader/formatreader-bridge.h, app/app-bridge.h. The codebase uses Objective-C/C bridge layers (callbacks.m, mdimporter-bridge.h, formatreader-bridge.h, app-bridge.h) which bypass Swift's memory safety guarantees. These bridges interact with system frameworks and FFmpeg without visible bounds checking or memory safety mechanisms, potentially exposing the application to memory corruption vulnerabilities. Fix: Audit all Objective-C/C bridge code for memory safety issues. Minimize use of unsafe code. Use Swift exclusively where possible. Implement comprehensive bounds checking and memory validation in bridge code. Use Address Sanitizer (ASan) and Memory Sanitizer during testing.
• Medium · Metadata Importer Running as System Service — mdimporter/GetMetadataForFile.swift, mdimporter/main.c. The mdimporter component (metadata importer) runs as a Spotlight extension with system-level privileges. If vulnerabilities exist in the metadata parsing logic (GetMetadataForFile.swift), an attacker could potentially exploit this to execute code with elevated privileges through specially crafted media files. Fix: Implement strict input validation in metadata extraction logic. Use the App Sandbox entitlements to restrict capabilities. Implement resource limits to prevent DoS attacks. Regularly audit the metadata extraction code for vulnerabilities.
• Medium · Missing Code Signing Verification — app/QuickLookVideo.entitlements, formatreader/formatreader.entitlements. While entitlements files are present (QuickLookVideo.entitlements, formatreader.entitlements), there is no visible evidence of code signing validation or signature verification mechanisms for loaded plugins or extensions. This could allow code injection attacks. Fix: Ensure all code is properly signed with a valid Apple developer certificate. Implement runtime signature verification for any dynamically loaded components. Use the hardened runtime entitlements where applicable.
• Medium · Potential Integer Overflow in Video/Audio Processing — formatreader/decodedsamplecursor.swift, formatreader/passthrusamplecursor.swift, formatreader/samplecursor.swift. The sample cursor implementations (decodedsamplecursor.swift, passthrusamplecursor.swift) and track readers handle potentially large file offsets and sample counts without visible overflow protection. Malicious files with crafted metadata could trigger integer overflows leading to memory access violations. Fix: Implement safe integer arithmetic with overflow checks. Use Swift's safe numeric types. Validate all offsets and sizes before use. Implement fuzzing tests with malformed video files.
• Low · Unencrypted Local Cache Potential — app/ (runtime cache behavior not visible in source). The application generates thumbnails and metadata which may be cached locally. If sensitive information is extracted from protected media files, this could potentially be exposed if the cache is not properly encrypted or access-controlled. Fix: Ensure all cached data is stored with proper file permissions. Consider encrypting cached thumbnails and metadata. Implement secure cleanup of cached data when the application terminates.

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.