# QuickLook Video: Finder thumbnails and Quick Look previews for MKV, WebM and more

> QuickLook Video is a GPL-2.0 macOS app that adds Finder thumbnails, Quick Look previews and Get Info metadata for media formats AVFoundation does not handle, including MKV, WebM, AVI and WMV. Installation steps live in a wiki page rather than the README.

**Marginal/QuickLookVideo** — Finder Thumbnails, Quick Look previews, Get Info metadata and previews for most types of audio and video files.

- Repository: https://github.com/Marginal/QuickLookVideo
- Stars: 3,594 · Forks: 129
- Language: Swift
- License: GPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/marginal-quicklookvideo

## What QuickLook Video fixes, and who it is for

macOS ships with Quick Look, AVFoundation and Spotlight, and those frameworks understand a narrow set of media. The README puts it plainly: they cover "mostly only MPEG audio and video codecs within ISO file formats." Drop an MKV, a WebM, an AVI or a WMV onto a Mac and the practical result is a generic document icon in Finder, a preview that refuses to open, and a Get Info panel with no duration, no codec and no dimensions. The bytes are fine. The system just has no reader for them.

QuickLook Video exists to close that gap. It is for people who keep a mixed media library on a Mac, typically video pulled from sources that encode in VP9, AV1, HEVC/H.265 or older codecs like DivX and Sorenson, and who want the file browser to behave as if those files were native. The README lists the target formats explicitly: Matroska `.mka` and `.mkv`, WebM `.webm`, Windows Media `.wma` and `.wmv`, Ogg Video `.ogm` and `.ogv`, AVI, QuickTime `.mov`, Flash Video `.flv` and `.f4v`, Real Media `.ra`, `.rm`, `.rv`, and the SMPTE `.gxf` and `.mxf` containers. Audio codecs include Vorbis, Windows Media Audio, WavPak and ATRAC. Video codecs include VP6, VP8, VP9, AV1, HEVC/H.265, VVC/H.266, Dolby Vision, Theora, DXV, HAP, Sorenson, Cinepak, AIC, Flash, Real Video, DivX, Intel Indeo and QuickTime animation.

That list is the product. There is no editing, no transcoding and no player interface to learn. The README also frames the project historically, noting that long-time Mac users may remember Perian, which did a similar job for the QuickTime framework before AVFoundation replaced it. QuickLook Video is the same idea rebuilt on the frameworks macOS uses now.

## Three extensions, not one: Spotlight plus two Media Extensions

The architecture is worth understanding before installing, because it explains why the app can appear to half-work. According to the README, the app contains a Spotlight extension that adds support for non-native file formats, and two Media Extensions that add support to AVFoundation for non-native file formats and video codecs.

Those are separate registration points in macOS, and they fail independently. The Spotlight extension is what feeds Finder's index, which is where thumbnails and Get Info metadata come from. The Media Extensions plug into AVFoundation, which is what Quick Look uses to actually decode and draw a preview frame. A file can therefore show a correct thumbnail and metadata while the preview still fails, or the reverse, if only one extension is enabled in System Settings.

The repository layout matches this split. The top level contains `mdimporter/`, which is the Spotlight metadata importer, alongside `formatreader/` and `videodecoder/`, which correspond to the format and codec sides of the AVFoundation support. There is also `simpleplayer/` and `contactsheet/`, plus vendored dependencies in `dav1d`, `ffmpeg` and `zimg`. The presence of ffmpeg and dav1d as submodules tells you where the decode capability comes from: this app is largely a macOS integration layer wrapped around existing decoders, not a from-scratch codec implementation. That is a reasonable design, and it also means the supported codec list is bounded by what those libraries expose.

## Installing QuickLook Video and getting a first preview

The README does not contain installation steps. It points to a wiki page, Getting Started, at `https://github.com/Marginal/QLVideo/wiki/Getting-Started`, and the README's first line is a badge linking to the Mac App Store listing for QuickLook Video. If you want the packaged app, that link is the path the project itself presents. If you want to build from source, the repository carries a `BUILDING.md` file and an Xcode project, `QLVideo.xcodeproj`, at the top level.

After installing, the extensions have to be enabled. macOS manages this in System Settings, and the exact pane depends on your macOS version, so check the Getting Started wiki page rather than guessing. Once the extensions are on, the first real test is a single file. In Finder, select a file in one of the formats the README lists, such as `sample.mkv`, and press Space to trigger Quick Look. What you should see is a preview rendered from the video rather than a refusal to open. Then press Command-I for Get Info: the README's screenshots show the metadata panel populated, which is the third surface this app touches.

If the thumbnail appears but the preview does not, or the reverse, that is the expected signature of one extension being active and another not. The README directs anyone with problems to a separate troubleshooting guide at `https://github.com/Marginal/QLVideo/wiki/Troubleshooting`, which is where extension registration issues are presumably covered. Neither wiki page's contents are reproduced in the repository, so treat them as required reading rather than optional.

## Where QuickLook Video stops being the right tool

The README is silent on rollback. There is no documented uninstall procedure, no list of files the app writes, and no statement about what happens to the Spotlight index after the extensions are removed. On macOS, removing a metadata importer can leave stale index entries until the volume is reindexed, and the project does not address that in what it publishes at the repository root. If you manage machines you cannot easily rebuild, that gap matters more than any codec on the support list.

The second limitation is structural. This is a macOS-only integration. It has no meaning on Windows or Linux, not because the codecs are unavailable there but because the entire product is a set of macOS extension points: Spotlight, Quick Look and AVFoundation. A user searching for Quick Look behaviour on Windows is looking for a different class of software entirely.

The third is scope. The README says "most types" of audio and video files, and the codec list is long, but it is a list. Formats outside it get nothing, and the README does not describe a fallback or an error message for unsupported input. There is also no transcoding: if a file is unsupported, QuickLook Video will not convert it into something that is. For a one-off file, a converter is the faster answer. QuickLook Video earns its place when the problem is a library, not a file.

## QuickLook Video compared with converting your library instead

The obvious alternative is not another Quick Look extension. It is a transcoding workflow: run files through a converter or an ffmpeg-based tool and produce MP4 or MOV copies that macOS already understands. The difference in approach is fundamental. Transcoding changes the artifact. You end up with a second file, a lossy or lossless re-encode depending on settings, roughly double the disk usage, and a library where the thing you watch is no longer the thing you downloaded. In exchange, every native macOS surface works forever, on any machine, with no extensions to enable and no System Settings to revisit after an OS upgrade.

QuickLook Video takes the opposite position. It leaves the bytes alone and teaches the system to read them. That is strictly better when the file is the master copy and you care about keeping it intact, when the library is large enough that converting everything is impractical, or when new files arrive continuously and you would otherwise be re-running a conversion on each one. It is strictly worse when you need the media to work outside Finder, in an editor that does not use AVFoundation, or on a machine where you cannot install and manage system extensions.

The README's own comparison point is Perian, which it describes as having performed a similar function with the QuickTime framework before QuickTime was replaced by AVFoundation. That is the honest framing: this is a compatibility shim for a framework gap, and its lifetime is tied to how long the gap stays open.

## Licence, releases and what upgrading costs you

QuickLook Video is licensed under the GNU Public License version 2 or later. The README states the copyright as "Copyright © 2014-2026 Jonathan Harris" and links to the GPL-2.0 text, and the repository carries `LICENSE.txt` at the top level. GPL-2.0-or-later is a copyleft licence. If you are only installing the app for personal use, that is uncomplicated. If you intend to redistribute it, bundle it into a product, or ship a modified build, the copyleft terms apply to what you distribute, and that is a question for your own legal review rather than something this article can settle. Note also that the Mac App Store listing and the GPL build are two distribution channels for the same project, which is a combination worth understanding before you assume either channel's terms cover both.

Maintenance is visible in the release history. The most recent push to the default branch was on 2026-09-23, and the release tags are close behind: rel-312 (Release 3.12) on 2026-09-21, rel-311 (Release 3.11) on 2026-08-08, and rel-310 (Release 3.10) on 2026-07-02. That is a steady cadence of roughly one release every six to eight weeks across the period shown.

Upgrade cost is low in the ordinary case, because the app is installed as a unit and the extensions are registered by the system. The real cost is the one macOS imposes on any extension-based tool: after a major OS upgrade you should confirm the Spotlight and Media Extensions are still enabled and still resolving, since a disabled extension produces exactly the silent partial failure described earlier. Beyond that, the vendored `ffmpeg` and `dav1d` submodules mean codec coverage advances when the project updates them, so keeping reasonably current is how you gain new format support rather than a way to fix something broken.

## Conclusion

Adopt QuickLook Video if you keep MKV, WebM, AVI, WMV or Ogg media on a Mac and want Finder thumbnails and Quick Look previews without converting files first. Skip it if you need Windows or Linux behaviour, since the project is a macOS app built on Spotlight and Media Extensions. Verify before relying on it that your exact codec and container combination appears in the supported list, and read the Getting Started and Troubleshooting wiki pages, because the README itself documents neither the install steps nor a rollback path.

## FAQ

### What is saved from Quick Look?

The Quick Look panel itself does not save anything; it renders a preview of the selected file. QuickLook Video's contribution is that Finder can produce a thumbnail, a preview and a populated Get Info panel for media formats macOS would otherwise not read.

### What is Quick Look on macOS?

Quick Look is the macOS preview feature, triggered by pressing Space with a file selected in Finder. QuickLook Video extends it by supplying Media Extensions that let AVFoundation decode formats such as MKV, WebM and AVI that it does not handle natively.

### How do I use Quick Look with QuickLook Video installed?

Enable the app's Spotlight and Media Extensions, then select a supported file in Finder and press Space to preview it. The README notes that the app contains one Spotlight extension and two Media Extensions, and directs users with problems to its troubleshooting wiki page.

## Sources

- [Issues](https://github.com/Marginal/QuickLookVideo/issues)
- [License: GPL-2.0](https://github.com/Marginal/QuickLookVideo/blob/master/LICENSE)
- [Marginal/QuickLookVideo on GitHub](https://github.com/Marginal/QuickLookVideo)
- [README](https://github.com/Marginal/QuickLookVideo/blob/master/README.md)
- [Releases](https://github.com/Marginal/QuickLookVideo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/marginal-quicklookvideo