# marginal/qlvideo architecture

> Architecture diagram of the GitHub repository marginal/qlvideo, 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/qlvideo
- Repository: https://github.com/marginal/qlvideo

## Overview

QLVideo is a macOS media compatibility product: it adds Finder thumbnails, Quick Look previews, Finder metadata, and AVFoundation support for media formats and codecs macOS does not natively handle. The user-facing workflow begins in Finder or Quick Look; Spotlight metadata import and Media Extensions are distinct product paths. The repository also contains format-reading, decoding, and contact-sheet components. Source excerpts establish only a few internal calls and imports, so uncertain runtime wiring is omitted rather than inferred.

Main entry points: [`formatreader/formatreader.swift`](https://github.com/marginal/qlvideo/blob/master/formatreader/formatreader.swift) (Format Reader), [`app/AppDelegate.swift`](https://github.com/marginal/qlvideo/blob/master/app/AppDelegate.swift) (App and Extension UI), [`mdimporter/GetMetadataForFile.swift`](https://github.com/marginal/qlvideo/blob/master/mdimporter/GetMetadataForFile.swift) (Metadata Importer), [`videodecoder/videodecoder.swift`](https://github.com/marginal/qlvideo/blob/master/videodecoder/videodecoder.swift) (Video Decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and Preview"]
  node_appdelegate["App and Extension UI<br/>[AppDelegate.swift]"]
  node_crashview["Crash Report View"]
  node_coverart["Cover Art View<br/>[CoverArtView.swift]"]
  node_issueview["Issue View<br/>[IssueView.swift]"]
  node_extensionview["Extension Status"]
end

subgraph group_metadata["Spotlight Metadata"]
  node_metadataimport["Metadata Importer"]
  node_codecname["Codec Naming<br/>[CodecName.swift]"]
end

subgraph group_reading["Media Reading"]
  node_formatreader["Format Reader<br/>[formatreader.swift]"]
  node_readerfactory["Reader Factory"]
  node_packetdemuxer["Packet Demuxer"]
  node_audioreader["Audio Track Reader"]
  node_videoreader["Video Track Reader"]
end

subgraph group_decoding["Video Decoding"]
  node_decoderfactory["Video Decoder Factory"]
  node_videodecoder["Video Decoder<br/>[videodecoder.swift]"]
  node_hdrhelpers["HDR Plane Helpers<br/>[hdr_interleave.c]"]
end

subgraph group_contact["Contact Sheet"]
  node_contactsheets["Contact Sheet App<br/>[AppDelegate.swift]"]
  node_contactcallbacks["FFmpeg Callbacks<br/>[callbacks.h]"]
end

node_finder(("Finder"))
node_quicklook(("Quick Look"))

node_finder -->|"requests metadata"| node_metadataimport
node_finder -->|"requests thumbnails"| node_appdelegate
node_quicklook -->|"requests previews"| node_appdelegate
node_appdelegate -->|"uses view"| node_crashview
node_metadataimport -->|"gets codec names"| node_codecname
node_formatreader -.-> node_readerfactory
node_formatreader -.-> node_packetdemuxer
node_formatreader -.-> node_audioreader
node_formatreader -.-> node_videoreader
node_decoderfactory -.-> node_videodecoder
node_videodecoder -.-> node_hdrhelpers
node_contactsheets -.-> node_contactcallbacks

click node_appdelegate "https://github.com/marginal/qlvideo/blob/master/app/AppDelegate.swift"
click node_crashview "https://github.com/marginal/qlvideo/blob/master/app/CrashReportView.swift"
click node_coverart "https://github.com/marginal/qlvideo/blob/master/app/CoverArtView.swift"
click node_issueview "https://github.com/marginal/qlvideo/blob/master/app/IssueView.swift"
click node_extensionview "https://github.com/marginal/qlvideo/blob/master/app/MediaExtensionsView.swift"
click node_metadataimport "https://github.com/marginal/qlvideo/blob/master/mdimporter/GetMetadataForFile.swift"
click node_codecname "https://github.com/marginal/qlvideo/blob/master/mdimporter/CodecName.swift"
click node_formatreader "https://github.com/marginal/qlvideo/blob/master/formatreader/formatreader.swift"
click node_readerfactory "https://github.com/marginal/qlvideo/blob/master/formatreader/formatreaderfactory.swift"
click node_packetdemuxer "https://github.com/marginal/qlvideo/blob/master/formatreader/packetdemuxer.swift"
click node_audioreader "https://github.com/marginal/qlvideo/blob/master/formatreader/audiotrackreader.swift"
click node_videoreader "https://github.com/marginal/qlvideo/blob/master/formatreader/videotrackreader.swift"
click node_decoderfactory "https://github.com/marginal/qlvideo/blob/master/videodecoder/videodecoderfactory.swift"
click node_videodecoder "https://github.com/marginal/qlvideo/blob/master/videodecoder/videodecoder.swift"
click node_hdrhelpers "https://github.com/marginal/qlvideo/blob/master/videodecoder/hdr_interleave.c"
click node_contactsheets "https://github.com/marginal/qlvideo/blob/master/contactsheet/AppDelegate.swift"
click node_contactcallbacks "https://github.com/marginal/qlvideo/blob/master/contactsheet/callbacks.h"

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_appdelegate,node_crashview,node_coverart,node_issueview,node_extensionview toneBlue
class node_metadataimport,node_codecname toneAmber
class node_formatreader,node_readerfactory,node_packetdemuxer,node_audioreader,node_videoreader toneMint
class node_decoderfactory,node_videodecoder,node_hdrhelpers toneRose
class node_contactsheets,node_contactcallbacks,node_finder,node_quicklook toneIndigo
```

## Components

### App and Preview

- [App and Extension UI](https://github.com/marginal/qlvideo/blob/master/app/AppDelegate.swift): `app/AppDelegate.swift`
- [Crash Report View](https://github.com/marginal/qlvideo/blob/master/app/CrashReportView.swift): `app/CrashReportView.swift`
- [Cover Art View](https://github.com/marginal/qlvideo/blob/master/app/CoverArtView.swift): `app/CoverArtView.swift`
- [Issue View](https://github.com/marginal/qlvideo/blob/master/app/IssueView.swift): `app/IssueView.swift`
- [Extension Status](https://github.com/marginal/qlvideo/blob/master/app/MediaExtensionsView.swift): `app/MediaExtensionsView.swift`

### Spotlight Metadata

- [Metadata Importer](https://github.com/marginal/qlvideo/blob/master/mdimporter/GetMetadataForFile.swift): `mdimporter/GetMetadataForFile.swift`
- [Codec Naming](https://github.com/marginal/qlvideo/blob/master/mdimporter/CodecName.swift): `mdimporter/CodecName.swift`

### Media Reading

- [Format Reader](https://github.com/marginal/qlvideo/blob/master/formatreader/formatreader.swift): `formatreader/formatreader.swift`
- [Reader Factory](https://github.com/marginal/qlvideo/blob/master/formatreader/formatreaderfactory.swift): `formatreader/formatreaderfactory.swift`
- [Packet Demuxer](https://github.com/marginal/qlvideo/blob/master/formatreader/packetdemuxer.swift): `formatreader/packetdemuxer.swift`
- [Audio Track Reader](https://github.com/marginal/qlvideo/blob/master/formatreader/audiotrackreader.swift): `formatreader/audiotrackreader.swift`
- [Video Track Reader](https://github.com/marginal/qlvideo/blob/master/formatreader/videotrackreader.swift): `formatreader/videotrackreader.swift`

### Video Decoding

- [Video Decoder Factory](https://github.com/marginal/qlvideo/blob/master/videodecoder/videodecoderfactory.swift): `videodecoder/videodecoderfactory.swift`
- [Video Decoder](https://github.com/marginal/qlvideo/blob/master/videodecoder/videodecoder.swift): `videodecoder/videodecoder.swift`
- [HDR Plane Helpers](https://github.com/marginal/qlvideo/blob/master/videodecoder/hdr_interleave.c): `videodecoder/hdr_interleave.c`

### Contact Sheet

- [Contact Sheet App](https://github.com/marginal/qlvideo/blob/master/contactsheet/AppDelegate.swift): `contactsheet/AppDelegate.swift`
- [FFmpeg Callbacks](https://github.com/marginal/qlvideo/blob/master/contactsheet/callbacks.h): `contactsheet/callbacks.h`

### Other components

- **Finder**
- **Quick Look**

## Connections

- Finder → Metadata Importer: requests metadata
- Finder → App and Extension UI: requests thumbnails
- Quick Look → App and Extension UI: requests previews
- App and Extension UI → Crash Report View: uses view (evidence: `app/AppDelegate.swift`)
- Metadata Importer → Codec Naming: gets codec names (evidence: `mdimporter/GetMetadataForFile.swift`)
- Format Reader → Reader Factory
- Format Reader → Packet Demuxer
- Format Reader → Audio Track Reader
- Format Reader → Video Track Reader
- Video Decoder Factory → Video Decoder
- Video Decoder → HDR Plane Helpers
- Contact Sheet App → FFmpeg Callbacks
