Add opus audio preview support

Add owned .opus metadata to the host app and extension so Finder can route audio-only Opus files through MKVQuickLook. Introduce an audio-only preview mode that keeps playback controls visible without showing an empty video surface, and add tests for the new metadata and UI behavior. Also stop the previous player before replacing it when Finder switches to another file, preventing stale audio from continuing in the background. Update the README with a prominent Gatekeeper note and document the new audio-only support, and record the change in the changelog.

Author: rowild

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Added owned `.opus` audio support in the app and extension metadata.
+- Added an audio-only Quick Look mode that keeps playback controls visible without showing an empty video frame.
+
+### Fixed
+
+- Switching to another file while a preview is already open now stops the previous player before the new one is attached, preventing stray audio from continuing in the background.
+
+### Notes
+
+- `.opus` is audio-only support, not video support hidden behind another extension.
+
 ## 0.1.3 - 2026-04-09
 
 ### Changed

MKVQuickLook.xcodeproj/project.pbxproj

@@ -8,6 +8,7 @@
 
 /* Begin PBXBuildFile section */
 		0185A1E4CAD0F2536931685A /* VLCVideoLayerHostView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 21ACF4081841AC895F797878 /* VLCVideoLayerHostView.swift */; };
+		04AD3364848C6C9F1181F5D9 /* MediaPreviewPlayerSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = E70C1B6AEE09C5CEE98DA7B2 /* MediaPreviewPlayerSession.swift */; };
 		05ED2B3AB06CF53FBE41C024 /* VLCKitMediaPreviewPlayer.swift in Sources */ = {isa = PBXBuildFile; fileRef = B4C0D0E7E3433A3474B1CA13 /* VLCKitMediaPreviewPlayer.swift */; };
 		09D842054D1327F0CDE6FC1D /* VLCKit.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 26CCAD556DF88A26642D0486 /* VLCKit.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; };
 		1BADCE5D6CF31C5D0C3EA530 /* VLCVideoLayerHostView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 21ACF4081841AC895F797878 /* VLCVideoLayerHostView.swift */; };
@@ -22,6 +23,7 @@
 		3A5AC45C4441D15E3D0021C5 /* PreviewViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = BA9165C63B0A4167A6AFEAA0 /* PreviewViewController.swift */; };
 		3C2B58691ED0D8F1CEFD730F /* VideoToolbox.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 8E1EE6E8B183958E809ED768 /* VideoToolbox.framework */; };
 		3DA12CC066C56B61251996AB /* VideoLayout.swift in Sources */ = {isa = PBXBuildFile; fileRef = 82538038139633F4454BF3B8 /* VideoLayout.swift */; };
+		3E4C4A83A07B01771B7AF288 /* MediaPreviewPlayerSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = E70C1B6AEE09C5CEE98DA7B2 /* MediaPreviewPlayerSession.swift */; };
 		4F70B1768253CC6D0CC94E8B /* MainWindowView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5C6820EDD7105300E0B3C6FE /* MainWindowView.swift */; };
 		509B4B27E2803EB4E4308002 /* AVFoundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 71B770A4F3058220E670AE4D /* AVFoundation.framework */; };
 		5309DF9B48353020DDF8B815 /* Quartz.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 40C73021684F36F46E4F3AE6 /* Quartz.framework */; };
@@ -53,6 +55,7 @@
 		C97CB0AA2C6918F5835F1B7B /* MediaPreviewPlayer.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9555F7EA3CD226932F56DAAE /* MediaPreviewPlayer.swift */; };
 		CAB6B7393F69C8566D3F07B1 /* QuartzCore.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1884C5B428369DD10604A5FC /* QuartzCore.framework */; };
 		CB5E07E8C6A42B9D1D2956A5 /* PlaybackDiagnostics.swift in Sources */ = {isa = PBXBuildFile; fileRef = CED5357DF3752411CC0A8B1E /* PlaybackDiagnostics.swift */; };
+		D483E2EB8422615968CDFAAA /* MediaPreviewPlayerSession.swift in Sources */ = {isa = PBXBuildFile; fileRef = E70C1B6AEE09C5CEE98DA7B2 /* MediaPreviewPlayerSession.swift */; };
 		E020F82932673E6AAAEF9802 /* VideoLayout.swift in Sources */ = {isa = PBXBuildFile; fileRef = 82538038139633F4454BF3B8 /* VideoLayout.swift */; };
 		E41C8BF1F4FACA82DDD6B11D /* PreviewMetadata.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8EBFF00EB96786F2F91B23B6 /* PreviewMetadata.swift */; };
 		E58CE0689863AA40D25FF392 /* VLCVideoLayerHostView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 21ACF4081841AC895F797878 /* VLCVideoLayerHostView.swift */; };
@@ -154,6 +157,7 @@
 		CED5357DF3752411CC0A8B1E /* PlaybackDiagnostics.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PlaybackDiagnostics.swift; sourceTree = "<group>"; };
 		D74DAEB38D6766046DE5347E /* libbz2.tbd */ = {isa = PBXFileReference; lastKnownFileType = "sourcecode.text-based-dylib-definition"; name = libbz2.tbd; path = usr/lib/libbz2.tbd; sourceTree = SDKROOT; };
 		E3D0BF10236F4D4666B61CC1 /* MKVQuickLookPreviewExtension.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = MKVQuickLookPreviewExtension.appex; sourceTree = BUILT_PRODUCTS_DIR; };
+		E70C1B6AEE09C5CEE98DA7B2 /* MediaPreviewPlayerSession.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MediaPreviewPlayerSession.swift; sourceTree = "<group>"; };
 		E78A20ACD8AECE98CB1DFA53 /* AppStatusViewModel.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AppStatusViewModel.swift; sourceTree = "<group>"; };
 		F9D991977061BA25D21BFB70 /* Security.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Security.framework; path = System/Library/Frameworks/Security.framework; sourceTree = SDKROOT; };
 /* End PBXFileReference section */
@@ -215,6 +219,7 @@
 			isa = PBXGroup;
 			children = (
 				9555F7EA3CD226932F56DAAE /* MediaPreviewPlayer.swift */,
+				E70C1B6AEE09C5CEE98DA7B2 /* MediaPreviewPlayerSession.swift */,
 				B4C0D0E7E3433A3474B1CA13 /* VLCKitMediaPreviewPlayer.swift */,
 				21ACF4081841AC895F797878 /* VLCVideoLayerHostView.swift */,
 			);
@@ -424,6 +429,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				C97CB0AA2C6918F5835F1B7B /* MediaPreviewPlayer.swift in Sources */,
+				D483E2EB8422615968CDFAAA /* MediaPreviewPlayerSession.swift in Sources */,
 				C6DD68259D9A89D903E9238C /* PlaybackDiagnostics.swift in Sources */,
 				EC0DB67FA2FA5419279BD272 /* PreviewContentView.swift in Sources */,
 				E41C8BF1F4FACA82DDD6B11D /* PreviewMetadata.swift in Sources */,
@@ -440,6 +446,7 @@
 			files = (
 				EBDBACD66302E999D1234CA4 /* BundleMetadataTests.swift in Sources */,
 				904DAA5E391982B8C176884E /* MediaPreviewPlayer.swift in Sources */,
+				04AD3364848C6C9F1181F5D9 /* MediaPreviewPlayerSession.swift in Sources */,
 				CB5E07E8C6A42B9D1D2956A5 /* PlaybackDiagnostics.swift in Sources */,
 				2B88CFF90BCF0FB3170CED64 /* PreviewContentView.swift in Sources */,
 				EF7ADB30C280537CC95076AB /* PreviewMetadata.swift in Sources */,
@@ -458,6 +465,7 @@
 				1F289B33F3D8F5093D940555 /* MKVQuickLookApp.swift in Sources */,
 				4F70B1768253CC6D0CC94E8B /* MainWindowView.swift in Sources */,
 				9E318696532BB1FD7D431823 /* MediaPreviewPlayer.swift in Sources */,
+				3E4C4A83A07B01771B7AF288 /* MediaPreviewPlayerSession.swift in Sources */,
 				AB22A85B3CECA21C04A68B5F /* PlaybackDiagnostics.swift in Sources */,
 				2E90D1CC045B923E1911504B /* PlaybackLabViewController.swift in Sources */,
 				578CD529E1ABB780CD20B7BF /* PlaybackLabWindowView.swift in Sources */,

MKVQuickLookApp/Resources/Info.plist

@@ -74,6 +74,18 @@
 				<string>com.robertwildling.mkvquicklook.avi</string>
 			</array>
 		</dict>
+		<dict>
+			<key>CFBundleTypeName</key>
+			<string>Opus Audio</string>
+			<key>CFBundleTypeRole</key>
+			<string>Viewer</string>
+			<key>LSHandlerRank</key>
+			<string>Owner</string>
+			<key>LSItemContentTypes</key>
+			<array>
+				<string>com.robertwildling.mkvquicklook.opus</string>
+			</array>
+		</dict>
 	</array>
 	<key>UTExportedTypeDeclarations</key>
 	<array>
@@ -172,6 +184,31 @@
 				</array>
 			</dict>
 		</dict>
+		<dict>
+			<key>UTTypeConformsTo</key>
+			<array>
+				<string>public.audio</string>
+				<string>public.audiovisual-content</string>
+				<string>public.data</string>
+			</array>
+			<key>UTTypeDescription</key>
+			<string>Opus Audio</string>
+			<key>UTTypeIdentifier</key>
+			<string>com.robertwildling.mkvquicklook.opus</string>
+			<key>UTTypeTagSpecification</key>
+			<dict>
+				<key>public.filename-extension</key>
+				<array>
+					<string>opus</string>
+				</array>
+				<key>public.mime-type</key>
+				<array>
+					<string>audio/opus</string>
+					<string>audio/ogg</string>
+					<string>application/ogg</string>
+				</array>
+			</dict>
+		</dict>
 	</array>
 </dict>
 </plist>

MKVQuickLookPreviewExtension/Resources/Info.plist

@@ -35,11 +35,13 @@
 				<string>org.xiph.ogv</string>
 				<string>org.videolan.ogg-audio</string>
 				<string>org.xiph.ogg.vorbis</string>
+				<string>org.xiph.opus</string>
 				<string>public.avi</string>
 				<string>com.robertwildling.mkvquicklook.mkv</string>
 				<string>com.robertwildling.mkvquicklook.webm</string>
 				<string>com.robertwildling.mkvquicklook.ogg-video</string>
 				<string>com.robertwildling.mkvquicklook.avi</string>
+				<string>com.robertwildling.mkvquicklook.opus</string>
 			</array>
 			<key>QLSupportsSearchableItems</key>
 			<false/>

MKVQuickLookPreviewExtension/Sources/PreviewViewController.swift

@@ -74,14 +74,15 @@ final class PreviewViewController: NSViewController, QLPreviewingController {
                 self?.previewContentView.setVideoOutputVisible(isVisible)
             }
 
+            self.player = MediaPreviewPlayerSession.replace(current: self.player, with: player)
+
             await MainActor.run {
                 title = metadata.displayName
                 previewContentView.apply(metadata: metadata)
                 previewContentView.attachRenderView(player.renderView)
             }
 
             currentFileURL = url
-            self.player = player
             isMediaLoaded = false
             updatePresentationModeAndPlayback()
         } catch {

README.md

@@ -7,18 +7,28 @@ macOS host app plus Quick Look Preview Extension scaffold for:
 - `mkv`
 - `webm`
 - `ogg` / `ogv`
+- `opus` (audio-only)
 - `avi` (best-effort)
 
 `MKVQuickLook` provides a Finder Quick Look preview for these formats on macOS by shipping a small host app with a bundled Quick Look Preview Extension and embedded `VLCKit` playback backend.
 
 ![MKVQuickLook screenshot](screenshot.png)
 
+## Gatekeeper
+
+This app is currently distributed as an ad hoc signed DMG build and is **not notarized**.
+
+- macOS Gatekeeper may warn when users open it for the first time.
+- That is expected for the current release process.
+- Users may need to open it via Finder context menu or allow it in System Settings after the first launch attempt.
+
 Current status:
 
 - host app with main window, settings/help UI, and playback lab
 - Quick Look Preview Extension registered for owned target file types
 - `VLCKit 3.7.2` fetched into `Vendor/` by a bootstrap script
 - direct VLCKit-backed playback path for supported files
+- audio-only `.opus` files use the same VLCKit backend with an audio preview UI instead of a video frame
 - Finder registration and Launch Services ownership wired into the app bundle metadata
 - playback defaults to paused in Quick Look
 - renderer, metadata, and UI regressions covered by automated tests
@@ -207,6 +217,7 @@ Suggested local contents:
 
 - one or more `.mkv` files, including at least one problematic real-world sample
 - one `.webm` file
+- one `.opus` audio-only sample
 - one `.ogv` or Theora-in-Ogg sample if Ogg video support is being tested
 - one `.avi` sample if AVI behavior is being checked
 

Shared/Sources/Player/MediaPreviewPlayerSession.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+@MainActor
+enum MediaPreviewPlayerSession {
+    static func replace(current: MediaPreviewPlayer?, with next: MediaPreviewPlayer?) -> MediaPreviewPlayer? {
+        if let current, current !== next {
+            current.stop()
+        }
+        return next
+    }
+}

Shared/Sources/PreviewContentView.swift

@@ -94,6 +94,7 @@ final class PreviewContentView: NSView {
     private var currentSeekInteractionID: PlaybackDiagnostics.InteractionID?
     private var currentPlaybackState: MediaPreviewPlaybackState = .idle
     private var isVideoOutputVisible = false
+    private var mediaKind: PreviewMediaKind = .video
 
     var isPlaceholderVisibleForTesting: Bool {
         !placeholderLabel.isHidden
@@ -107,6 +108,14 @@ final class PreviewContentView: NSView {
         playbackButton.isEnabled
     }
 
+    var isVideoFrameHiddenForTesting: Bool {
+        videoFrameView.isHidden
+    }
+
+    var isControlsRowHiddenForTesting: Bool {
+        controlsRow.isHidden
+    }
+
     override init(frame frameRect: NSRect) {
         super.init(frame: frameRect)
         configureView()
@@ -124,21 +133,32 @@ final class PreviewContentView: NSView {
     }
 
     func apply(metadata: PreviewMetadata) {
+        setMediaKind(metadata.mediaKind)
         iconView.image = metadata.icon
         titleLabel.stringValue = metadata.displayName
         subtitleLabel.stringValue = "\(metadata.typeDescription) • .\(metadata.fileExtension)"
-        compactHintLabel.stringValue = "Column preview stays paused. Press Space for the full Quick Look player."
+        compactHintLabel.stringValue = metadata.mediaKind == .audioOnly
+            ? "Column preview stays paused. Press Space for the full Quick Look audio preview."
+            : "Column preview stays paused. Press Space for the full Quick Look player."
         detailsLabel.stringValue = """
         Path: \(metadata.fileURL.path)
         Size: \(metadata.fileSizeDescription)
         Modified: \(metadata.modifiedDateDescription)
         """
-        statusLabel.stringValue = "Opening with VLCKit..."
+        statusLabel.stringValue = metadata.mediaKind == .audioOnly
+            ? "Opening audio with VLCKit..."
+            : "Opening with VLCKit..."
         playbackButton.isEnabled = true
         seekSlider.isEnabled = false
         volumeSlider.isEnabled = true
     }
 
+    func setMediaKind(_ mediaKind: PreviewMediaKind) {
+        self.mediaKind = mediaKind
+        refreshLayoutForCurrentMode()
+        refreshPlaceholderVisibility()
+    }
+
     func applyPlaceholder(title: String, subtitle: String, details: String, status: String, symbolName: String = "play.rectangle") {
         iconView.image = NSImage(systemSymbolName: symbolName, accessibilityDescription: nil)
         titleLabel.stringValue = title
@@ -241,6 +261,8 @@ final class PreviewContentView: NSView {
             stackTopConstraint?.constant = 24
             stackBottomConstraint?.constant = -24
         }
+
+        refreshLayoutForCurrentMode()
     }
 
     func updatePlaybackMetrics(_ metrics: MediaPreviewPlaybackMetrics) {
@@ -267,7 +289,7 @@ final class PreviewContentView: NSView {
             playbackButton.isEnabled = true
             placeholderLabel.stringValue = "Ready to play"
         case .opening:
-            statusLabel.stringValue = "Opening media..."
+            statusLabel.stringValue = mediaKind == .audioOnly ? "Opening audio..." : "Opening media..."
             playbackButton.title = "Pause"
             playbackButton.isEnabled = true
             placeholderLabel.stringValue = "Preparing video surface..."
@@ -277,7 +299,9 @@ final class PreviewContentView: NSView {
             playbackButton.isEnabled = true
             placeholderLabel.stringValue = "Buffering..."
         case .playing:
-            statusLabel.stringValue = "Playing original file directly through VLCKit."
+            statusLabel.stringValue = mediaKind == .audioOnly
+                ? "Playing original audio file directly through VLCKit."
+                : "Playing original file directly through VLCKit."
             playbackButton.title = "Pause"
             playbackButton.isEnabled = true
         case .paused:
@@ -506,7 +530,22 @@ final class PreviewContentView: NSView {
         videoCanvasView.frame = VideoLayout.fittedRect(contentSize: videoPresentationSize, in: safeBounds).integral
     }
 
+    private func refreshLayoutForCurrentMode() {
+        let isExpanded = compactHintLabel.isHidden
+
+        if isExpanded {
+            let shouldHideVideoFrame = mediaKind == .audioOnly
+            videoFrameView.isHidden = shouldHideVideoFrame
+            badgeLabel.isHidden = shouldHideVideoFrame
+        }
+    }
+
     private func refreshPlaceholderVisibility() {
+        guard mediaKind == .video else {
+            placeholderLabel.isHidden = true
+            return
+        }
+
         let shouldHidePlaceholder: Bool
 
         switch currentPlaybackState {

Shared/Sources/PreviewMetadata.swift

@@ -1,10 +1,16 @@
 import AppKit
 import Foundation
 
+enum PreviewMediaKind: Equatable {
+    case video
+    case audioOnly
+}
+
 struct PreviewMetadata {
     let fileURL: URL
     let displayName: String
     let fileExtension: String
+    let mediaKind: PreviewMediaKind
     let typeDescription: String
     let fileSizeDescription: String
     let modifiedDateDescription: String
@@ -21,12 +27,22 @@ struct PreviewMetadata {
         self.fileURL = fileURL
         displayName = resourceValues.name ?? fileURL.lastPathComponent
         fileExtension = fileURL.pathExtension.lowercased()
+        mediaKind = Self.mediaKind(for: fileExtension)
         typeDescription = Self.typeDescription(for: fileExtension, contentTypeDescription: resourceValues.contentType?.localizedDescription)
         fileSizeDescription = Self.fileSizeDescription(bytes: resourceValues.fileSize)
         modifiedDateDescription = Self.modifiedDateDescription(resourceValues.contentModificationDate)
         icon = NSWorkspace.shared.icon(forFile: fileURL.path)
     }
 
+    static func mediaKind(for fileExtension: String) -> PreviewMediaKind {
+        switch fileExtension {
+        case "opus":
+            return .audioOnly
+        default:
+            return .video
+        }
+    }
+
     static func typeDescription(for fileExtension: String, contentTypeDescription: String?) -> String {
         if let contentTypeDescription, !contentTypeDescription.isEmpty {
             return contentTypeDescription
@@ -41,6 +57,8 @@ struct PreviewMetadata {
             return "Ogg Video"
         case "avi":
             return "AVI Video"
+        case "opus":
+            return "Opus Audio"
         default:
             return "Media File"
         }