Fix VLC Range Cache for MKV Streams

Summary

Dreamio was refusing to range-cache MKV streams before checking the server. That made Torrentio and Real-Debrid MKV playback open in direct mode, so seek prefetch could not run. The cache probe now lets normal HTTP range capability decide whether the local cache should be used.

Changes Made

• Removed the hard-coded cache bypass for .mkv, .mk3d, .mka, .mks, and .webm URLs.
• Kept the existing non-HTTP and HLS playlist fallbacks intact.
• Updated the range probe regression test so MKV URLs are cacheable when the server returns Accept-Ranges: bytes and a valid Content-Length.

Context

The diagnostic logs showed [DreamioVLC] cache fallback reason=tail-index-container, followed by opening mode=direct and direct-mode seek logs. That fallback came from an extension check, not a failed HTTP range probe. Because many debrid MKV streams do support byte ranges, the app was leaving useful buffering behavior on the table.

Important Implementation Details

• The probe still requires either a HEAD response with byte-range support and content length, or a successful GET Range: bytes=0-0 response.
• If an MKV origin ignores range requests, Dreamio still falls back to direct playback through the existing range-probe-status-... path.
• The expected debug signal for a compatible MKV is now [DreamioVLC] opening mode=local-cache, and seeks should include byteOffset=....

Relevant Diff Snippets

271 unmodified lines
272
273
274
275
276
277
278
279
280
281
52 unmodified lines
334
335
336
337
338
339
340
341
342
343
271 unmodified lines
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        guard !Self.shouldBypassCache(for: url) else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "tail-index-container")
        }

        if let head = try? await response(for: request(method: "HEAD")),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
52 unmodified lines
        response.value(forHTTPHeaderField: name)
    }

    private static func shouldBypassCache(for url: URL) -> Bool {
        let extensionName = url.pathExtension.lowercased()
        return ["mkv", "mk3d", "mka", "mks", "webm"].contains(extensionName)
    }
}

enum HTTPRangeCacheError: Error {
271 unmodified lines
272
273
274
275
276
277
52 unmodified lines
330
331
332
333
334
335
271 unmodified lines
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        if let head = try? await response(for: request(method: "HEAD")),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
52 unmodified lines
        response.value(forHTTPHeaderField: name)
    }

}

enum HTTPRangeCacheError: Error {

42 unmodified lines
43
44
45
46
47
48
49
491 unmodified lines
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
3 unmodified lines
561
562
563
564
565
566
567
568
569
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeBypassesTailIndexContainers()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
491 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeProbeBypassesTailIndexContainers() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in
            requestCount += 1
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 206,
                httpVersion: nil,
                headerFields: ["Content-Range": "bytes 0-0/20"]
            )!
            return (Data([1]), response)
        }

        let fetcher = HTTPRangeRemoteFetcher(
3 unmodified lines
        )
        let probe = await fetcher.probe()

        assertEqual(probe.isCacheable, false)
        assertEqual(probe.fallbackReason, "tail-index-container")
        assertEqual(requestCount, 0)
        MockURLProtocol.handler = nil
    }

42 unmodified lines
43
44
45
46
47
48
49
491 unmodified lines
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
3 unmodified lines
565
566
567
568
569
570
571
572
573
574
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
491 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in
            requestCount += 1
            assertEqual(request.httpMethod, "HEAD")
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 200,
                httpVersion: nil,
                headerFields: [
                    "Accept-Ranges": "bytes",
                    "Content-Length": "20"
                ]
            )!
            return (Data(), response)
        }

        let fetcher = HTTPRangeRemoteFetcher(
3 unmodified lines
        )
        let probe = await fetcher.probe()

        assertEqual(probe.isCacheable, true)
        assertEqual(probe.contentLength, 20)
        assertEqual(probe.fallbackReason, nil)
        assertEqual(requestCount, 1)
        MockURLProtocol.handler = nil
    }

Expected Impact for End-Users

Compatible MKV direct-file streams should start through Dreamio's local range cache instead of direct VLC mode. Backward and forward skips can now prime nearby bytes, which should reduce stalls after seeking on supported servers.

Validation

• Passed swiftc Dreamio/StreamCandidate.swift Dreamio/StreamResolver.swift Dreamio/ProgressiveHTTPRangeCache.swift Dreamio/ExternalSubtitleTrackParser.swift Tests/StreamResolverTests.swift -o /tmp/StreamResolverTests && /tmp/StreamResolverTests
• Passed DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -workspace Dreamio.xcworkspace -scheme Dreamio -configuration Debug -sdk iphonesimulator build

Issues, Limitations, and Mitigations

Follow-up Work

• Test the original Torrentio/Real-Debrid South Park stream on device and confirm logs show opening mode=local-cache.
• If startup is slower on some MKV sources, consider measuring HEAD latency and falling back to the tiny range probe sooner.
• Improve external subtitle auto-selection so English does not lose to the first parsed subtitle track.

New Changes as of May 26, 2026 at 8:16 AM

Summary of changes

Added a short timeout to the range-cache probe path so a slow HEAD or tiny range request cannot prevent native playback from starting.

Why this change was made

Device logs showed the MKV stream reached [DreamioVLC] cache-probe but never logged either opening mode=local-cache or opening mode=direct before the native-player startup timeout. The cache probe was waiting too long before any VLC media was opened.

Code diffs

264 unmodified lines
265
266
267
268
269
270
271
272
273
274
275
276
277
278
2 unmodified lines
281
282
283
284
285
286
287
29 unmodified lines
317
318
319
320
321
322
323
324
325
264 unmodified lines
        self.session = session
    }

    func probe() async -> HTTPRangeProbeResult {
        guard ["http", "https"].contains(url.scheme?.lowercased() ?? "") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "non-http-url")
        }
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        if let head = try? await response(for: request(method: "HEAD")),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
            let length = header("Content-Length", in: head).flatMap(Int64.init)
2 unmodified lines
            }
        }

        var tinyRequest = request(method: "GET")
        tinyRequest.setValue("bytes=0-0", forHTTPHeaderField: "Range")
        do {
            let (data, response) = try await session.data(for: tinyRequest)
29 unmodified lines
        return response as? HTTPURLResponse
    }

    private func request(method: String) -> URLRequest {
        var request = URLRequest(url: url)
        request.httpMethod = method
        headers.forEach { key, value in
            request.setValue(value, forHTTPHeaderField: key)
        }
264 unmodified lines
265
266
267
268
269
270
271
272
273
274
275
276
277
278
2 unmodified lines
281
282
283
284
285
286
287
29 unmodified lines
317
318
319
320
321
322
323
324
325
326
327
328
264 unmodified lines
        self.session = session
    }

    func probe(timeoutInterval: TimeInterval = 3) async -> HTTPRangeProbeResult {
        guard ["http", "https"].contains(url.scheme?.lowercased() ?? "") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "non-http-url")
        }
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "hls-playlist")
        }
        if let head = try? await response(for: request(method: "HEAD", timeoutInterval: timeoutInterval)),
           (200..<400).contains(head.statusCode) {
            let acceptsRanges = header("Accept-Ranges", in: head)?.lowercased().contains("bytes") == true
            let length = header("Content-Length", in: head).flatMap(Int64.init)
2 unmodified lines
            }
        }

        var tinyRequest = request(method: "GET", timeoutInterval: timeoutInterval)
        tinyRequest.setValue("bytes=0-0", forHTTPHeaderField: "Range")
        do {
            let (data, response) = try await session.data(for: tinyRequest)
29 unmodified lines
        return response as? HTTPURLResponse
    }

    private func request(method: String, timeoutInterval: TimeInterval? = nil) -> URLRequest {
        var request = URLRequest(url: url)
        request.httpMethod = method
        if let timeoutInterval {
            request.timeoutInterval = timeoutInterval
        }
        headers.forEach { key, value in
            request.setValue(value, forHTTPHeaderField: key)
        }

77 unmodified lines
78
79
80
81
82
83
84
77 unmodified lines
                return
            }
            let fetcher = HTTPRangeRemoteFetcher(url: request.playbackURL, headers: request.headers)
            let probe = await fetcher.probe()
            guard !Task.isCancelled else {
                return
            }
77 unmodified lines
78
79
80
81
82
83
84
77 unmodified lines
                return
            }
            let fetcher = HTTPRangeRemoteFetcher(url: request.playbackURL, headers: request.headers)
            let probe = await fetcher.probe(timeoutInterval: 1.5)
            guard !Task.isCancelled else {
                return
            }

43 unmodified lines
44
45
46
47
48
49
522 unmodified lines
572
573
574
575
576
577
43 unmodified lines
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
522 unmodified lines
        MockURLProtocol.handler = nil
    }

    private static func byteRange(fromHeader header: String, contentLength: Int64) -> HTTPByteRange {
        let value = header.replacingOccurrences(of: "bytes=", with: "")
        let pieces = value.split(separator: "-", maxSplits: 1).map(String.init)
43 unmodified lines
44
45
46
47
48
49
50
522 unmodified lines
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
43 unmodified lines
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeAppliesRequestTimeout()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
522 unmodified lines
        MockURLProtocol.handler = nil
    }

    private static func testRangeProbeAppliesRequestTimeout() async {
        MockURLProtocol.handler = { request in
            assertEqual(request.timeoutInterval, 1.5)
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 200,
                httpVersion: nil,
                headerFields: [
                    "Accept-Ranges": "bytes",
                    "Content-Length": "20"
                ]
            )!
            return (Data(), response)
        }

        let fetcher = HTTPRangeRemoteFetcher(
            url: URL(string: "https://cdn.example.test/show.mkv")!,
            headers: [:],
            session: mockSession()
        )
        let probe = await fetcher.probe(timeoutInterval: 1.5)

        assertEqual(probe.isCacheable, true)
        MockURLProtocol.handler = nil
    }

    private static func byteRange(fromHeader header: String, contentLength: Int64) -> HTTPByteRange {
        let value = header.replacingOccurrences(of: "bytes=", with: "")
        let pieces = value.split(separator: "-", maxSplits: 1).map(String.init)

Related issues or PRs

Beads issue: dreamio-btc. This follows the earlier dreamio-3sw MKV cache enablement work.

Validation

• Passed swiftc Dreamio/StreamCandidate.swift Dreamio/StreamResolver.swift Dreamio/ProgressiveHTTPRangeCache.swift Dreamio/ExternalSubtitleTrackParser.swift Tests/StreamResolverTests.swift -o /tmp/StreamResolverTests && /tmp/StreamResolverTests
• Passed DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -workspace Dreamio.xcworkspace -scheme Dreamio -configuration Debug -sdk iphonesimulator build

New Changes as of May 26, 2026 at 9:01 AM

Summary of changes

Changed VLC startup to open direct playback immediately instead of waiting for the range-cache probe.

Why this change was made

Device logs showed the probe request timing out and the native player still failing to start before the startup watchdog. The reliable behavior is to start VLC first, then revisit cache probing as a non-blocking optimization later.

Code diffs

70 unmodified lines
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
70 unmodified lines
        lastLoggedState = nil
        lastBufferingLogTime = nil
#if DEBUG
        print("[DreamioVLC] cache-probe url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
        playbackStartupTask = Task { [weak self] in
            guard let self else {
                return
            }
            let fetcher = HTTPRangeRemoteFetcher(url: request.playbackURL, headers: request.headers)
            let probe = await fetcher.probe(timeoutInterval: 1.5)
            guard !Task.isCancelled else {
                return
            }

            if probe.isCacheable, let contentLength = probe.contentLength, contentLength > 0 {
                do {
                    let session = ProgressiveHTTPRangeCacheSession(
                        fetcher: fetcher,
                        contentLength: contentLength,
                        durationProvider: { [weak self] in self?.duration ?? 0 }
                    )
                    let localURL = try await ProgressiveHTTPRangeCacheServer.shared.localURL(for: session)
                    await MainActor.run {
                        self.rangeCacheSession = session
                        session.prefetch(aroundByteOffset: 0)
                        self.startVLCMedia(
                            url: localURL,
                            request: request,
                            playbackMode: "local-cache",
                            cachingMilliseconds: 500,
                            includeRemoteHTTPOptions: false
                        )
                    }
                    return
                } catch {
#if DEBUG
                    print("[DreamioVLC] cache fallback reason=local-server-error-\(error)")
#endif
                }
            } else {
#if DEBUG
                print("[DreamioVLC] cache fallback reason=\(probe.fallbackReason ?? "unknown")")
#endif
            }

            await MainActor.run {
                self.startVLCMedia(
                    url: request.playbackURL,
                    request: request,
                    playbackMode: "direct",
                    cachingMilliseconds: 2500,
                    includeRemoteHTTPOptions: true
                )
            }
        }
#else
        onFailure?(NativePlaybackError.backendUnavailable)
#endif
70 unmodified lines
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
70 unmodified lines
        lastLoggedState = nil
        lastBufferingLogTime = nil
#if DEBUG
        print("[DreamioVLC] cache fallback reason=startup-direct-preferred url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
        startVLCMedia(
            url: request.playbackURL,
            request: request,
            playbackMode: "direct",
            cachingMilliseconds: 2500,
            includeRemoteHTTPOptions: true
        )
#else
        onFailure?(NativePlaybackError.backendUnavailable)
#endif

Related issues or PRs

Beads issue: dreamio-dd7. This supersedes the blocking startup probe behavior from the earlier MKV range-cache experiment.

Validation

• Passed swiftc Dreamio/StreamCandidate.swift Dreamio/StreamResolver.swift Dreamio/ProgressiveHTTPRangeCache.swift Dreamio/ExternalSubtitleTrackParser.swift Tests/StreamResolverTests.swift -o /tmp/StreamResolverTests && /tmp/StreamResolverTests
• Passed DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -workspace Dreamio.xcworkspace -scheme Dreamio -configuration Debug -sdk iphonesimulator build

New Changes as of May 26, 2026 at 8:42 PM EDT

Summary of changes

Changed VLC startup from a blanket direct-mode bypass to a bounded, non-blocking cache-preparation path. Dreamio now gives the local range cache a very short opportunity to prove it is safe and ready, then starts direct playback immediately if probing or server setup is slow, failed, or inconclusive.

Why this change was made

Recent MKV logs showed the previous cache probe could block native playback startup long enough for Native playback did not start before the timeout. The fix keeps native startup reliable while still allowing mode=local-cache when HTTP range support and the local server are ready inside the startup budget.

Code diffs

57 unmodified lines
58
59
60
61
62
63
57 unmodified lines
    let fallbackReason: String?
}

final class SparseHTTPByteRangeStore {
    private struct Segment {
        var range: HTTPByteRange
57 unmodified lines
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
57 unmodified lines
    let fallbackReason: String?
}

enum HTTPRangeCacheStartupDecision: Equatable {
    case useLocalCache
    case skip(reason: String)
}

enum HTTPRangeCacheStartupPolicy {
    static let preparationTimeout: TimeInterval = 0.25
    static let probeTimeout: TimeInterval = 0.2

    static func immediateSkipReason(for url: URL) -> String? {
        guard ["http", "https"].contains(url.scheme?.lowercased() ?? "") else {
            return "non-http-url"
        }
        guard !url.path.lowercased().hasSuffix(".m3u8") else {
            return "hls-playlist"
        }
        return nil
    }

    static func decision(for probe: HTTPRangeProbeResult) -> HTTPRangeCacheStartupDecision {
        guard probe.isCacheable, probe.contentLength != nil else {
            return .skip(reason: probe.fallbackReason ?? "range-probe-inconclusive")
        }
        return .useLocalCache
    }
}

final class SparseHTTPByteRangeStore {
    private struct Segment {
        var range: HTTPByteRange

24 unmodified lines
25
26
27
28
29
30
25 unmodified lines
56
57
58
59
60
61
8 unmodified lines
70
71
72
73
74
75
76
77
2 unmodified lines
80
81
82
83
84
85
86
87
88
89
103 unmodified lines
193
194
195
196
197
198
24 unmodified lines
#endif
    private var rangeCacheSession: ProgressiveHTTPRangeCacheSession?
    private var playbackStartupTask: Task<Void, Never>?
    private var lastLoggedState: String?
    private var lastBufferingLogTime: Date?
    private var attachedSubtitleURLs = Set<URL>()
25 unmodified lines
    func play(request: NativePlaybackRequest) {
#if canImport(MobileVLCKit)
        playbackStartupTask?.cancel()
        attachedSubtitleURLs.removeAll()
        pendingSubtitleCandidates.removeAll()
        pendingSubtitleURLs.removeAll()
8 unmodified lines
        rangeCacheSession = nil
        lastLoggedState = nil
        lastBufferingLogTime = nil
#if DEBUG
        print("[DreamioVLC] cache fallback reason=startup-direct-preferred url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
        startVLCMedia(
            url: request.playbackURL,
2 unmodified lines
            cachingMilliseconds: 2500,
            includeRemoteHTTPOptions: true
        )
#else
        onFailure?(NativePlaybackError.backendUnavailable)
#endif
    }

    func play() {
#if canImport(MobileVLCKit)
103 unmodified lines
    func stop() {
#if canImport(MobileVLCKit)
        playbackStartupTask?.cancel()
        rangeCacheSession = nil
        mediaPlayer.stop()
        mediaPlayer.drawable = nil
24 unmodified lines
25
26
27
28
29
30
31
32
25 unmodified lines
58
59
60
61
62
63
64
8 unmodified lines
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
2 unmodified lines
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
103 unmodified lines
315
316
317
318
319
320
321
322
24 unmodified lines
#endif
    private var rangeCacheSession: ProgressiveHTTPRangeCacheSession?
    private var playbackStartupTask: Task<Void, Never>?
    private var rangeCachePreparationTask: Task<Void, Never>?
    private var playbackStartupID: UUID?
    private var lastLoggedState: String?
    private var lastBufferingLogTime: Date?
    private var attachedSubtitleURLs = Set<URL>()
25 unmodified lines
    func play(request: NativePlaybackRequest) {
#if canImport(MobileVLCKit)
        playbackStartupTask?.cancel()
        rangeCachePreparationTask?.cancel()
        attachedSubtitleURLs.removeAll()
        pendingSubtitleCandidates.removeAll()
        pendingSubtitleURLs.removeAll()
8 unmodified lines
        rangeCacheSession = nil
        lastLoggedState = nil
        lastBufferingLogTime = nil
        startWithNonBlockingRangeCache(request: request)
#else
        onFailure?(NativePlaybackError.backendUnavailable)
#endif
    }

#if canImport(MobileVLCKit)
    private func startWithNonBlockingRangeCache(request: NativePlaybackRequest) {
        if let skipReason = HTTPRangeCacheStartupPolicy.immediateSkipReason(for: request.playbackURL) {
#if DEBUG
            print("[DreamioVLC] cache skipped reason=\(skipReason) url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
            startDirectPlayback(request: request, fallbackReason: skipReason)
            return
        }

        let startupID = UUID()
        playbackStartupID = startupID

        playbackStartupTask = Task { [weak self] in
            guard let self else {
                return
            }
            do {
                let timeoutNanoseconds = UInt64(HTTPRangeCacheStartupPolicy.preparationTimeout * 1_000_000_000)
                try await Task.sleep(nanoseconds: timeoutNanoseconds)
            } catch {
                return
            }
            await MainActor.run {
                guard self.canStartPlayback(for: startupID) else {
                    return
                }
#if DEBUG
                print("[DreamioVLC] cache probe timed out timeoutMs=\(Int(HTTPRangeCacheStartupPolicy.preparationTimeout * 1000)) url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
                self.rangeCachePreparationTask?.cancel()
                self.startDirectPlayback(request: request, fallbackReason: "startup-direct-preferred")
            }
        }

        rangeCachePreparationTask = Task { [weak self] in
            guard let self else {
                return
            }
            let result = await self.prepareRangeCache(for: request)
            guard !Task.isCancelled else {
                return
            }
            await MainActor.run {
                guard self.canStartPlayback(for: startupID) else {
                    return
                }
                self.playbackStartupTask?.cancel()
                switch result {
                case .success(let prepared):
#if DEBUG
                    print("[DreamioVLC] cache used mode=local-cache url=\(URLRedactor.redactedURLString(prepared.localURL.absoluteString))")
#endif
                    self.rangeCacheSession = prepared.session
                    self.startVLCMedia(
                        url: prepared.localURL,
                        request: request,
                        playbackMode: "local-cache",
                        cachingMilliseconds: 1000,
                        includeRemoteHTTPOptions: false
                    )
                case .failure(let failure):
                    self.startDirectPlayback(request: request, fallbackReason: failure.reason)
                }
            }
        }
    }

    private func canStartPlayback(for startupID: UUID) -> Bool {
        playbackStartupID == startupID && !hasStartedMedia
    }

    private struct RangeCacheStartupFailure: Error {
        let reason: String
    }

    private func startDirectPlayback(request: NativePlaybackRequest, fallbackReason: String) {
#if DEBUG
        print("[DreamioVLC] direct fallback started reason=\(fallbackReason) url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
        startVLCMedia(
            url: request.playbackURL,
2 unmodified lines
            cachingMilliseconds: 2500,
            includeRemoteHTTPOptions: true
        )
    }

    private struct PreparedRangeCache {
        let session: ProgressiveHTTPRangeCacheSession
        let localURL: URL
    }

    private func prepareRangeCache(for request: NativePlaybackRequest) async -> Result<PreparedRangeCache, RangeCacheStartupFailure> {
        let fetcher = HTTPRangeRemoteFetcher(url: request.playbackURL, headers: request.headers)
        let probe = await fetcher.probe(timeoutInterval: HTTPRangeCacheStartupPolicy.probeTimeout)
        switch HTTPRangeCacheStartupPolicy.decision(for: probe) {
        case .skip(let reason):
#if DEBUG
            print("[DreamioVLC] cache skipped reason=\(reason) url=\(URLRedactor.redactedURLString(request.playbackURL.absoluteString))")
#endif
            return .failure(RangeCacheStartupFailure(reason: reason))
        case .useLocalCache:
            break
        }

        guard let contentLength = probe.contentLength else {
            return .failure(RangeCacheStartupFailure(reason: "range-probe-inconclusive"))
        }
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: fetcher,
            contentLength: contentLength,
            durationProvider: { [weak self] in self?.duration ?? 0 }
        )
        do {
            let localURL = try await ProgressiveHTTPRangeCacheServer.shared.localURL(for: session)
            return .success(PreparedRangeCache(session: session, localURL: localURL))
        } catch {
#if DEBUG
            print("[DreamioVLC] local cache server failed error=\(error)")
#endif
            return .failure(RangeCacheStartupFailure(reason: "local-cache-server-failed"))
        }
    }
#else
#endif

    func play() {
#if canImport(MobileVLCKit)
103 unmodified lines
    func stop() {
#if canImport(MobileVLCKit)
        playbackStartupTask?.cancel()
        rangeCachePreparationTask?.cancel()
        playbackStartupID = nil
        rangeCacheSession = nil
        mediaPlayer.stop()
        mediaPlayer.drawable = nil

42 unmodified lines
43
44
45
46
47
48
493 unmodified lines
542
543
544
545
546
547
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeAppliesRequestTimeout()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
493 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in
42 unmodified lines
43
44
45
46
47
48
49
50
51
493 unmodified lines
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        testRangeCacheStartupPolicySkipsHLSAndNonHTTPImmediately()
        testRangeCacheStartupPolicyUsesCacheOnlyForConclusiveProbe()
        testRangeCacheStartupPolicySkipsInconclusiveProbe()
        await testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges()
        await testRangeProbeAppliesRequestTimeout()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
493 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

    private static func testRangeCacheStartupPolicySkipsHLSAndNonHTTPImmediately() {
        assertEqual(
            HTTPRangeCacheStartupPolicy.immediateSkipReason(for: URL(string: "https://cdn.example.test/live.m3u8")!),
            "hls-playlist"
        )
        assertEqual(
            HTTPRangeCacheStartupPolicy.immediateSkipReason(for: URL(string: "file:///tmp/movie.mkv")!),
            "non-http-url"
        )
        assertEqual(
            HTTPRangeCacheStartupPolicy.immediateSkipReason(for: URL(string: "https://cdn.example.test/movie.mkv")!),
            nil
        )
    }

    private static func testRangeCacheStartupPolicyUsesCacheOnlyForConclusiveProbe() {
        let decision = HTTPRangeCacheStartupPolicy.decision(
            for: HTTPRangeProbeResult(isCacheable: true, contentLength: 20, fallbackReason: nil)
        )

        assertEqual(decision, .useLocalCache)
    }

    private static func testRangeCacheStartupPolicySkipsInconclusiveProbe() {
        let rejectedDecision = HTTPRangeCacheStartupPolicy.decision(
            for: HTTPRangeProbeResult(isCacheable: false, contentLength: nil, fallbackReason: "range-probe-status-200")
        )
        let missingLengthDecision = HTTPRangeCacheStartupPolicy.decision(
            for: HTTPRangeProbeResult(isCacheable: true, contentLength: nil, fallbackReason: nil)
        )

        assertEqual(rejectedDecision, .skip(reason: "range-probe-status-200"))
        assertEqual(missingLengthDecision, .skip(reason: "range-probe-inconclusive"))
    }

    private static func testRangeProbeAllowsRangeCacheForMKVWhenServerSupportsRanges() async {
        var requestCount = 0
        MockURLProtocol.handler = { request in

Related issues or PRs

• Beads issue: dreamio-5cz.
• No pull request was opened in this turn.