# marginal/quicklookvideo architecture

> Architecture diagram of the GitHub repository marginal/quicklookvideo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marginal/quicklookvideo
- Repository: https://github.com/marginal/quicklookvideo

## Overview

QuickLook Video extends macOS media support: users see Finder thumbnails and Quick Look previews, and Spotlight supplies richer Finder metadata. The documented product has two Media Extensions for non-native formats and video codecs; the tree also exposes format reading, decoding, thumbnail/contact-sheet, and metadata components. The README establishes the platform integrations, but sampled source does not show all extension dispatch or call paths, so those internal links are marked unverified rather than presented as confirmed calls.

Main entry points: [`app/AppDelegate.swift`](https://github.com/marginal/quicklookvideo/blob/master/app/AppDelegate.swift) (App controls), [`formatreader`](https://github.com/marginal/quicklookvideo/tree/master/formatreader) (Format reader), [`videodecoder/videodecoder.swift`](https://github.com/marginal/quicklookvideo/blob/master/videodecoder/videodecoder.swift) (Video decoder), [`formatreader/audiotrackreader.swift`](https://github.com/marginal/quicklookvideo/blob/master/formatreader/audiotrackreader.swift) (Track readers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["App and previews"]
  node_app["App controls<br/>[AppDelegate.swift]"]
  node_coverart["Cover art<br/>[CoverArtView.swift]"]
  node_issues["Issue views<br/>[IssueView.swift]"]
end

subgraph group_media["Media extensions"]
  node_formatreader["Format reader"]
  node_trackreaders["Track readers"]
  node_videotrack["Video track reader"]
  node_decoder["Video decoder<br/>[videodecoder.swift]"]
  node_decoderfactory["Decoder selection"]
  node_contactsheet["Contact sheets"]
end

subgraph group_metadata["Spotlight metadata"]
  node_metadataimporter["Metadata importer"]
  node_codecnames["Codec names<br/>[CodecName.swift]"]
end

subgraph group_support["Media support"]
  node_simpleplayer["Media playback<br/>[simpleplayer.swift]"]
  node_hdrhelpers["HDR pixel helpers<br/>[hdr_interleave.c]"]
end

node_finder(("Finder"))
node_quicklook(("Quick Look"))
node_spotlight(("Spotlight"))
node_avfoundation(("AVFoundation"))

node_finder -.->|"manage support"| node_app
node_finder -->|"request metadata"| node_spotlight
node_spotlight -->|"index media"| node_metadataimporter
node_finder -->|"request preview"| node_quicklook
node_quicklook -.->|"preview media"| node_avfoundation
node_avfoundation -.->|"read formats"| node_formatreader
node_avfoundation -.->|"decode codecs"| node_decoder
node_formatreader -.->|"provide tracks"| node_trackreaders
node_trackreaders -.->|"read video"| node_videotrack
node_decoderfactory -.->|"select decoder"| node_decoder
node_metadataimporter -->|"name codecs"| node_codecnames
node_decoder -.->|"convert HDR planes"| node_hdrhelpers
node_contactsheet -.->|"read media"| node_formatreader
node_app -.->|"show artwork"| node_coverart
node_app -.->|"show issues"| node_issues

click node_app "https://github.com/marginal/quicklookvideo/blob/master/app/AppDelegate.swift"
click node_coverart "https://github.com/marginal/quicklookvideo/blob/master/app/CoverArtView.swift"
click node_issues "https://github.com/marginal/quicklookvideo/blob/master/app/IssueView.swift"
click node_formatreader "https://github.com/marginal/quicklookvideo/tree/master/formatreader"
click node_trackreaders "https://github.com/marginal/quicklookvideo/blob/master/formatreader/audiotrackreader.swift"
click node_videotrack "https://github.com/marginal/quicklookvideo/blob/master/formatreader/videotrackreader.swift"
click node_decoder "https://github.com/marginal/quicklookvideo/blob/master/videodecoder/videodecoder.swift"
click node_decoderfactory "https://github.com/marginal/quicklookvideo/blob/master/videodecoder/videodecoderfactory.swift"
click node_contactsheet "https://github.com/marginal/quicklookvideo/blob/master/contactsheet/contactsheetview.swift"
click node_metadataimporter "https://github.com/marginal/quicklookvideo/blob/master/mdimporter/GetMetadataForFile.swift"
click node_codecnames "https://github.com/marginal/quicklookvideo/blob/master/mdimporter/CodecName.swift"
click node_simpleplayer "https://github.com/marginal/quicklookvideo/blob/master/simpleplayer/simpleplayer.swift"
click node_hdrhelpers "https://github.com/marginal/quicklookvideo/blob/master/videodecoder/hdr_interleave.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_coverart,node_issues toneBlue
class node_formatreader,node_trackreaders,node_videotrack,node_decoder,node_decoderfactory,node_contactsheet toneAmber
class node_metadataimporter,node_codecnames toneMint
class node_simpleplayer,node_hdrhelpers toneRose
class node_finder,node_quicklook,node_spotlight,node_avfoundation toneIndigo
```

## Components

### App and previews

- [App controls](https://github.com/marginal/quicklookvideo/blob/master/app/AppDelegate.swift): `app/AppDelegate.swift`
- [Cover art](https://github.com/marginal/quicklookvideo/blob/master/app/CoverArtView.swift): `app/CoverArtView.swift`
- [Issue views](https://github.com/marginal/quicklookvideo/blob/master/app/IssueView.swift): `app/IssueView.swift`

### Media extensions

- [Format reader](https://github.com/marginal/quicklookvideo/tree/master/formatreader): `formatreader`
- [Track readers](https://github.com/marginal/quicklookvideo/blob/master/formatreader/audiotrackreader.swift): `formatreader/audiotrackreader.swift`
- [Video track reader](https://github.com/marginal/quicklookvideo/blob/master/formatreader/videotrackreader.swift): `formatreader/videotrackreader.swift`
- [Video decoder](https://github.com/marginal/quicklookvideo/blob/master/videodecoder/videodecoder.swift): `videodecoder/videodecoder.swift`
- [Decoder selection](https://github.com/marginal/quicklookvideo/blob/master/videodecoder/videodecoderfactory.swift): `videodecoder/videodecoderfactory.swift`
- [Contact sheets](https://github.com/marginal/quicklookvideo/blob/master/contactsheet/contactsheetview.swift): `contactsheet/contactsheetview.swift`

### Spotlight metadata

- [Metadata importer](https://github.com/marginal/quicklookvideo/blob/master/mdimporter/GetMetadataForFile.swift): `mdimporter/GetMetadataForFile.swift`
- [Codec names](https://github.com/marginal/quicklookvideo/blob/master/mdimporter/CodecName.swift): `mdimporter/CodecName.swift`

### Media support

- [Media playback](https://github.com/marginal/quicklookvideo/blob/master/simpleplayer/simpleplayer.swift): `simpleplayer/simpleplayer.swift`
- [HDR pixel helpers](https://github.com/marginal/quicklookvideo/blob/master/videodecoder/hdr_interleave.c): `videodecoder/hdr_interleave.c`

### Other components

- **Finder**
- **Quick Look**
- **Spotlight**
- **AVFoundation**

## Connections

- Finder → App controls: manage support
- Finder → Spotlight: request metadata
- Spotlight → Metadata importer: index media
- Finder → Quick Look: request preview
- Quick Look → AVFoundation: preview media
- AVFoundation → Format reader: read formats
- AVFoundation → Video decoder: decode codecs
- Format reader → Track readers: provide tracks
- Track readers → Video track reader: read video
- Decoder selection → Video decoder: select decoder
- Metadata importer → Codec names: name codecs (evidence: `mdimporter/GetMetadataForFile.swift`)
- Video decoder → HDR pixel helpers: convert HDR planes
- Contact sheets → Format reader: read media
- App controls → Cover art: show artwork
- App controls → Issue views: show issues
