From 5cd5d2f9fff4611bfa48cf826f9bf4d37504ca90 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:00:57 -0400 Subject: [PATCH 1/6] reduce seek buffering in range cache --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 45 ++++- Tests/StreamResolverTests.swift | 23 +++ .../2026-05-25-vlc-local-range-cache.html | 160 +++++++++++++++++- 5 files changed, 220 insertions(+), 10 deletions(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 22e71d0..4085860 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -42,3 +42,4 @@ {"id":"int-e339ed64","kind":"field_change","created_at":"2026-05-25T20:22:40.999137Z","actor":"dirtydishes","issue_id":"dreamio-dsp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"implemented local native stream cache proxy with range cache tests and successful simulator build"}} {"id":"int-79713eba","kind":"field_change","created_at":"2026-05-25T21:55:32.323229Z","actor":"dirtydishes","issue_id":"dreamio-6bv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"handled VLC buffering follow-up by supporting HEAD probes, moving fetch work off listener queue, reducing foreground range size, and locking cache access"}} {"id":"int-b2667330","kind":"field_change","created_at":"2026-05-25T23:44:07.439593Z","actor":"dirtydishes","issue_id":"dreamio-9gw","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds."}} +{"id":"int-6ca684f7","kind":"field_change","created_at":"2026-05-26T04:00:46.072019Z","actor":"dirtydishes","issue_id":"dreamio-42s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 808b3f4..370b1cc 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-42s","title":"Reduce VLC range-cache buffering after seeks","description":"Logs show repeated local-cache misses and cancelled prefetch tasks after VLC jumps backward, causing buffering while the cache restarts speculative requests instead of preserving useful adjacent downloads.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T03:58:03Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:00:46Z","started_at":"2026-05-26T03:58:10Z","closed_at":"2026-05-26T04:00:46Z","close_reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-9gw","title":"Cap VLC local range cache memory","description":"Playback can be killed for memory when VLC asks the loopback cache for a very large byte range. The local range cache should answer with bounded partial ranges and trim cached segments to the active window.","status":"closed","priority":1,"issue_type":"bug","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:38:08Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:44:07Z","closed_at":"2026-05-25T23:44:07Z","close_reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-4t0","title":"Fix native external subtitle overlay fallback","description":"Parsed external subtitles are discovered but MobileVLCKit may report no imported subtitle tracks. Make Dreamio's parsed subtitle overlay the reliable fallback and add parser/overlay coverage.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:23:15Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:28:44Z","started_at":"2026-05-25T23:23:18Z","closed_at":"2026-05-25T23:28:44Z","close_reason":"Implemented parsed external subtitle overlay fallback, parser extraction, focused parser tests, and simulator build validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8l9","title":"Fix native external subtitle overlay fallback","description":"External subtitles are parsed and listed, but MobileVLCKit can report no imported subtitle tracks. Make parsed external subtitles the reliable overlay fallback, keep VLC import attempts optional, and add focused parser/cue tests.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:13:35Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:17:40Z","started_at":"2026-05-25T23:13:49Z","closed_at":"2026-05-25T23:17:40Z","close_reason":"Implemented native parsed external subtitle overlay fallback, added SRT parser/cue tests, and validated with parser tests plus iOS Simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index ad514ed..73b7065 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -16,6 +16,10 @@ struct HTTPByteRange: Equatable { func merged(with other: HTTPByteRange) -> HTTPByteRange { HTTPByteRange(start: min(start, other.start), end: max(end, other.end)) } + + func contains(_ offset: Int64) -> Bool { + start <= offset && offset <= end + } } struct HTTPContentRange: Equatable { @@ -254,6 +258,7 @@ final class ProgressiveHTTPRangeCacheSession { private let prefetchChunkSize: Int64 = 1_048_576 private let responseChunkSize: Int64 = 1_048_576 private var prefetchTask: Task? + private var activePrefetchWindow: HTTPByteRange? init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) { self.fetcher = fetcher @@ -288,10 +293,16 @@ final class ProgressiveHTTPRangeCacheSession { } func prefetch(aroundByteOffset offset: Int64) { + if activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false { + return + } + prefetchTask?.cancel() let window = targetWindow(aroundByteOffset: offset) + activePrefetchWindow = window store.evict(keeping: window) guard !store.hasData(for: window) else { + activePrefetchWindow = nil return } @@ -299,9 +310,10 @@ final class ProgressiveHTTPRangeCacheSession { guard let self else { return } - var cursor = window.start - while cursor <= window.end, !Task.isCancelled { - let chunk = HTTPByteRange(start: cursor, end: min(window.end, cursor + prefetchChunkSize - 1)) + for chunk in self.prefetchChunks(in: window, preferredOffset: offset) { + guard !Task.isCancelled else { + return + } if !store.hasData(for: chunk) { do { let data = try await fetcher.fetch(range: chunk) @@ -310,14 +322,17 @@ final class ProgressiveHTTPRangeCacheSession { print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)") #endif } catch { + if Task.isCancelled { + return + } #if DEBUG print("[DreamioRangeCache] prefetch failed range=\(chunk.start)-\(chunk.end) error=\(error)") #endif return } } - cursor = chunk.end + 1 } + self.activePrefetchWindow = nil } } @@ -333,6 +348,28 @@ final class ProgressiveHTTPRangeCacheSession { return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead)) } + func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] { + let boundedOffset = max(window.start, min(window.end, offset)) + let preferredStart = window.start + ((boundedOffset - window.start) / prefetchChunkSize) * prefetchChunkSize + var chunks: [HTTPByteRange] = [] + + var cursor = preferredStart + while cursor <= window.end { + let chunk = HTTPByteRange(start: cursor, end: min(window.end, cursor + prefetchChunkSize - 1)) + chunks.append(chunk) + cursor = chunk.end + 1 + } + + cursor = window.start + while cursor < preferredStart { + let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1)) + chunks.append(chunk) + cursor = chunk.end + 1 + } + + return chunks + } + private func estimatedBytesPerSecond() -> Int64 { let duration = durationProvider() guard duration > 1 else { diff --git a/Tests/StreamResolverTests.swift b/Tests/StreamResolverTests.swift index ec7038d..9a390ec 100644 --- a/Tests/StreamResolverTests.swift +++ b/Tests/StreamResolverTests.swift @@ -36,6 +36,7 @@ struct StreamResolverTests { testSparseRangeStoreEvictsOutsideWindow() testSparseRangeStoreTrimsOverlappingWindow() testRangeCacheSessionCapsResponseRange() + testRangeCachePrefetchPrioritizesSeekOffset() await testRangeProbeFallsBackWhenServerIgnoresRange() await testRangeFetcherPreservesHeaders() print("StreamResolverTests passed") @@ -344,6 +345,28 @@ struct StreamResolverTests { assertEqual(responseRange, HTTPByteRange(start: 0, end: 1_048_575)) } + private static func testRangeCachePrefetchPrioritizesSeekOffset() { + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), + contentLength: 20_000_000, + durationProvider: { 0 } + ) + + let chunks = session.prefetchChunks( + in: HTTPByteRange(start: 0, end: 4_194_303), + preferredOffset: 2_200_000 + ) + + assertEqual(chunks.prefix(2).map { $0 }, [ + HTTPByteRange(start: 2_097_152, end: 3_145_727), + HTTPByteRange(start: 3_145_728, end: 4_194_303) + ]) + assertEqual(chunks.suffix(2).map { $0 }, [ + HTTPByteRange(start: 0, end: 1_048_575), + HTTPByteRange(start: 1_048_576, end: 2_097_151) + ]) + } + private static func testRangeProbeFallsBackWhenServerIgnoresRange() async { MockURLProtocol.handler = { request in if request.httpMethod == "HEAD" { diff --git a/docs/turns/2026-05-25-vlc-local-range-cache.html b/docs/turns/2026-05-25-vlc-local-range-cache.html index 34a1db7..ae398c9 100644 --- a/docs/turns/2026-05-25-vlc-local-range-cache.html +++ b/docs/turns/2026-05-25-vlc-local-range-cache.html @@ -87,7 +87,7 @@
Tests/StreamResolverTests.swift
+12
320 unmodified lines
319
320
320 unmodified lines
        assertEqual(store.cachedRanges, [HTTPByteRange(start: 10, end: 12)])
    }
320 unmodified lines
321
322
323
324
325
326
327
328
329
330
331
332
333
334
320 unmodified lines
        assertEqual(store.cachedRanges, [HTTPByteRange(start: 10, end: 12)])
    }

 
    private static func testSparseRangeStoreTrimsOverlappingWindow() {
        let store = SparseHTTPByteRangeStore()
        store.insert(data: Data([0, 1, 2, 3, 4, 5]), at: 0)
        store.evict(keeping: HTTPByteRange(start: 2, end: 4))
        assertEqual(store.cachedRanges, [HTTPByteRange(start: 2, end: 4)])
    }

 
    private static func testRangeCacheSessionCapsResponseRange() {
        let session = ProgressiveHTTPRangeCacheSession(fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), contentLength: 711_080_522, durationProvider: { 0 })
        assertEqual(session.responseRange(for: HTTPByteRange(start: 0, end: 711_080_521)), HTTPByteRange(start: 0, end: 1_048_575))
    }

Related issues or PRs

Related to Beads issue dreamio-9gw and branch lavender/vlc-local-range-cache.

+

New Changes as of 2026-05-25 23:59 EDT

Summary of changes

Adjusted range-cache prefetching for seek-heavy playback so the cache prioritizes chunks around the post-seek byte offset and avoids cancelling useful in-flight prefetch work when the requested offset remains inside the active window.

Why this change was made

Runtime logs showed VLC entering buffering after a seek while Dreamio repeatedly reported cache misses and cancelled prefetches. The prefetcher was warming from the back edge of a broad window, which could spend bandwidth behind the seek target before fetching the bytes VLC needed next.

Code diffs

Rendered with @pierre/diffs/ssr. The diffs below cover the seek-prefetch changes and focused regression coverage.

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
-4+41
15 unmodified lines
16
17
18
19
20
21
232 unmodified lines
254
255
256
257
258
259
28 unmodified lines
288
289
290
291
292
293
294
295
296
297
1 unmodified line
299
300
301
302
303
304
305
306
307
2 unmodified lines
310
311
312
313
314
315
316
317
318
319
320
321
322
323
9 unmodified lines
333
334
335
336
337
338
15 unmodified lines
    func merged(with other: HTTPByteRange) -> HTTPByteRange {
        HTTPByteRange(start: min(start, other.start), end: max(end, other.end))
    }
}

+
struct HTTPContentRange: Equatable {
232 unmodified lines
    private let prefetchChunkSize: Int64 = 1_048_576
    private let responseChunkSize: Int64 = 1_048_576
    private var prefetchTask: Task<Void, Never>?

+
    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
        self.fetcher = fetcher
28 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        prefetchTask?.cancel()
        let window = targetWindow(aroundByteOffset: offset)
        store.evict(keeping: window)
        guard !store.hasData(for: window) else {
            return
        }

+
1 unmodified line
            guard let self else {
                return
            }
            var cursor = window.start
            while cursor <= window.end, !Task.isCancelled {
                let chunk = HTTPByteRange(start: cursor, end: min(window.end, cursor + prefetchChunkSize - 1))
                if !store.hasData(for: chunk) {
                    do {
                        let data = try await fetcher.fetch(range: chunk)
2 unmodified lines
                        print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)")
#endif
                    } catch {
#if DEBUG
                        print("[DreamioRangeCache] prefetch failed range=\(chunk.start)-\(chunk.end) error=\(error)")
#endif
                        return
                    }
                }
                cursor = chunk.end + 1
            }
        }
    }

+
9 unmodified lines
        return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
    }

+
    private func estimatedBytesPerSecond() -> Int64 {
        let duration = durationProvider()
        guard duration > 1 else {
15 unmodified lines
16
17
18
19
20
21
22
23
24
25
232 unmodified lines
258
259
260
261
262
263
264
28 unmodified lines
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
1 unmodified line
310
311
312
313
314
315
316
317
318
319
2 unmodified lines
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
9 unmodified lines
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
15 unmodified lines
    func merged(with other: HTTPByteRange) -> HTTPByteRange {
        HTTPByteRange(start: min(start, other.start), end: max(end, other.end))
    }

+
    func contains(_ offset: Int64) -> Bool {
        start <= offset && offset <= end
    }
}

+
struct HTTPContentRange: Equatable {
232 unmodified lines
    private let prefetchChunkSize: Int64 = 1_048_576
    private let responseChunkSize: Int64 = 1_048_576
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?

+
    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
        self.fetcher = fetcher
28 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        if activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
            return
        }

+
        prefetchTask?.cancel()
        let window = targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        store.evict(keeping: window)
        guard !store.hasData(for: window) else {
            activePrefetchWindow = nil
            return
        }

+
1 unmodified line
            guard let self else {
                return
            }
            for chunk in self.prefetchChunks(in: window, preferredOffset: offset) {
                guard !Task.isCancelled else {
                    return
                }
                if !store.hasData(for: chunk) {
                    do {
                        let data = try await fetcher.fetch(range: chunk)
2 unmodified lines
                        print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)")
#endif
                    } catch {
                        if Task.isCancelled {
                            return
                        }
#if DEBUG
                        print("[DreamioRangeCache] prefetch failed range=\(chunk.start)-\(chunk.end) error=\(error)")
#endif
                        return
                    }
                }
            }
            self.activePrefetchWindow = nil
        }
    }

+
9 unmodified lines
        return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
    }

+
    func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] {
        let boundedOffset = max(window.start, min(window.end, offset))
        let preferredStart = window.start + ((boundedOffset - window.start) / prefetchChunkSize) * prefetchChunkSize
        var chunks: [HTTPByteRange] = []

+
        var cursor = preferredStart
        while cursor <= window.end {
            let chunk = HTTPByteRange(start: cursor, end: min(window.end, cursor + prefetchChunkSize - 1))
            chunks.append(chunk)
            cursor = chunk.end + 1
        }

+
        cursor = window.start
        while cursor < preferredStart {
            let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1))
            chunks.append(chunk)
            cursor = chunk.end + 1
        }

+
        return chunks
    }

+
    private func estimatedBytesPerSecond() -> Int64 {
        let duration = durationProvider()
        guard duration > 1 else {

Tests/StreamResolverTests.swift

Tests/StreamResolverTests.swift
+23
35 unmodified lines
36
37
38
39
40
41
302 unmodified lines
344
345
346
347
348
349
35 unmodified lines
        testSparseRangeStoreEvictsOutsideWindow()
        testSparseRangeStoreTrimsOverlappingWindow()
        testRangeCacheSessionCapsResponseRange()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
302 unmodified lines
        assertEqual(responseRange, HTTPByteRange(start: 0, end: 1_048_575))
    }

+
    private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
        MockURLProtocol.handler = { request in
            if request.httpMethod == "HEAD" {
35 unmodified lines
36
37
38
39
40
41
42
302 unmodified lines
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
35 unmodified lines
        testSparseRangeStoreEvictsOutsideWindow()
        testSparseRangeStoreTrimsOverlappingWindow()
        testRangeCacheSessionCapsResponseRange()
        testRangeCachePrefetchPrioritizesSeekOffset()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
302 unmodified lines
        assertEqual(responseRange, HTTPByteRange(start: 0, end: 1_048_575))
    }

+
    private static func testRangeCachePrefetchPrioritizesSeekOffset() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
            contentLength: 20_000_000,
            durationProvider: { 0 }
        )

+
        let chunks = session.prefetchChunks(
            in: HTTPByteRange(start: 0, end: 4_194_303),
            preferredOffset: 2_200_000
        )

+
        assertEqual(chunks.prefix(2).map { $0 }, [
            HTTPByteRange(start: 2_097_152, end: 3_145_727),
            HTTPByteRange(start: 3_145_728, end: 4_194_303)
        ])
        assertEqual(chunks.suffix(2).map { $0 }, [
            HTTPByteRange(start: 0, end: 1_048_575),
            HTTPByteRange(start: 1_048_576, end: 2_097_151)
        ])
    }

+
    private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
        MockURLProtocol.handler = { request in
            if request.httpMethod == "HEAD" {

Related issues or PRs

Related to Beads issue dreamio-42s and branch lavender/vlc-local-range-cache.

From 6ac2062822ebee536aaf2b19caae2f5dded6edc5 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:14:30 -0400 Subject: [PATCH 2/6] reprioritize range cache on vlc misses --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 35 +++- Tests/StreamResolverTests.swift | 57 +++++++ .../2026-05-25-vlc-local-range-cache.html | 152 ++++++++++++++++++ 5 files changed, 244 insertions(+), 2 deletions(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 4085860..ce73f0e 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -43,3 +43,4 @@ {"id":"int-79713eba","kind":"field_change","created_at":"2026-05-25T21:55:32.323229Z","actor":"dirtydishes","issue_id":"dreamio-6bv","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"handled VLC buffering follow-up by supporting HEAD probes, moving fetch work off listener queue, reducing foreground range size, and locking cache access"}} {"id":"int-b2667330","kind":"field_change","created_at":"2026-05-25T23:44:07.439593Z","actor":"dirtydishes","issue_id":"dreamio-9gw","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds."}} {"id":"int-6ca684f7","kind":"field_change","created_at":"2026-05-26T04:00:46.072019Z","actor":"dirtydishes","issue_id":"dreamio-42s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild."}} +{"id":"int-176e3ad2","kind":"field_change","created_at":"2026-05-26T04:14:19.812849Z","actor":"dirtydishes","issue_id":"dreamio-meh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 370b1cc..9ddaebb 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-meh","title":"Use VLC range requests to reprioritize seek prefetch","description":"Jump logs show duration-based byteOffset estimates can be far behind VLC's actual post-seek range requests, so prefetch keeps warming stale bytes while VLC buffers on higher cache misses.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:11:38Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:14:20Z","started_at":"2026-05-26T04:11:40Z","closed_at":"2026-05-26T04:14:20Z","close_reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-42s","title":"Reduce VLC range-cache buffering after seeks","description":"Logs show repeated local-cache misses and cancelled prefetch tasks after VLC jumps backward, causing buffering while the cache restarts speculative requests instead of preserving useful adjacent downloads.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T03:58:03Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:00:46Z","started_at":"2026-05-26T03:58:10Z","closed_at":"2026-05-26T04:00:46Z","close_reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-9gw","title":"Cap VLC local range cache memory","description":"Playback can be killed for memory when VLC asks the loopback cache for a very large byte range. The local range cache should answer with bounded partial ranges and trim cached segments to the active window.","status":"closed","priority":1,"issue_type":"bug","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:38:08Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:44:07Z","closed_at":"2026-05-25T23:44:07Z","close_reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-4t0","title":"Fix native external subtitle overlay fallback","description":"Parsed external subtitles are discovered but MobileVLCKit may report no imported subtitle tracks. Make Dreamio's parsed subtitle overlay the reliable fallback and add parser/overlay coverage.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:23:15Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:28:44Z","started_at":"2026-05-25T23:23:18Z","closed_at":"2026-05-25T23:28:44Z","close_reason":"Implemented parsed external subtitle overlay fallback, parser extraction, focused parser tests, and simulator build validation.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index 73b7065..a950b71 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -259,6 +259,7 @@ final class ProgressiveHTTPRangeCacheSession { private let responseChunkSize: Int64 = 1_048_576 private var prefetchTask: Task? private var activePrefetchWindow: HTTPByteRange? + private var activePrefetchPreferredOffset: Int64? init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) { self.fetcher = fetcher @@ -266,6 +267,10 @@ final class ProgressiveHTTPRangeCacheSession { self.durationProvider = durationProvider } + deinit { + cancelPrefetch() + } + func data(for requestedRange: HTTPByteRange) async throws -> Data { let bounded = clamp(requestedRange) if let data = store.data(for: bounded) { @@ -278,9 +283,10 @@ final class ProgressiveHTTPRangeCacheSession { #if DEBUG print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)") #endif + cancelPrefetchIfNeeded(forForegroundRange: bounded) let data = try await fetcher.fetch(range: bounded) store.insert(data: data, at: bounded.start) - prefetch(aroundByteOffset: bounded.end + 1) + prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true) return store.data(for: bounded) ?? data } @@ -293,16 +299,22 @@ final class ProgressiveHTTPRangeCacheSession { } func prefetch(aroundByteOffset offset: Int64) { - if activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false { + prefetch(aroundByteOffset: offset, forceRestart: false) + } + + func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) { + if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false { return } prefetchTask?.cancel() let window = targetWindow(aroundByteOffset: offset) activePrefetchWindow = window + activePrefetchPreferredOffset = offset store.evict(keeping: window) guard !store.hasData(for: window) else { activePrefetchWindow = nil + activePrefetchPreferredOffset = nil return } @@ -333,14 +345,33 @@ final class ProgressiveHTTPRangeCacheSession { } } self.activePrefetchWindow = nil + self.activePrefetchPreferredOffset = nil } } + func cancelPrefetch() { + prefetchTask?.cancel() + activePrefetchWindow = nil + activePrefetchPreferredOffset = nil + } + func byteOffset(for position: Float) -> Int64 { let clamped = max(0, min(1, position)) return Int64(Float(contentLength) * clamped) } + private func cancelPrefetchIfNeeded(forForegroundRange range: HTTPByteRange) { + guard activePrefetchWindow?.contains(range.start) == true, + let preferredOffset = activePrefetchPreferredOffset, + abs(range.start - preferredOffset) >= responseChunkSize else { + return + } +#if DEBUG + print("[DreamioRangeCache] prefetch reprioritize from=\(preferredOffset) to=\(range.start)") +#endif + cancelPrefetch() + } + private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange { let bytesPerSecond = estimatedBytesPerSecond() let behind = max(prefetchChunkSize, bytesPerSecond * 30) diff --git a/Tests/StreamResolverTests.swift b/Tests/StreamResolverTests.swift index 9a390ec..3a00f2c 100644 --- a/Tests/StreamResolverTests.swift +++ b/Tests/StreamResolverTests.swift @@ -37,6 +37,7 @@ struct StreamResolverTests { testSparseRangeStoreTrimsOverlappingWindow() testRangeCacheSessionCapsResponseRange() testRangeCachePrefetchPrioritizesSeekOffset() + await testRangeCacheForegroundMissReprioritizesPrefetch() await testRangeProbeFallsBackWhenServerIgnoresRange() await testRangeFetcherPreservesHeaders() print("StreamResolverTests passed") @@ -367,6 +368,62 @@ struct StreamResolverTests { ]) } + private static func testRangeCacheForegroundMissReprioritizesPrefetch() async { + let queue = DispatchQueue(label: "dreamio.range-cache-test") + var requestedRanges: [String] = [] + MockURLProtocol.handler = { request in + let range = request.value(forHTTPHeaderField: "Range") ?? "" + queue.sync { + requestedRanges.append(range) + } + let byteRange = byteRange(fromHeader: range, contentLength: 80_000_000) + let response = HTTPURLResponse( + url: request.url!, + statusCode: 206, + httpVersion: nil, + headerFields: ["Content-Range": "bytes \(byteRange.start)-\(byteRange.end)/80000000"] + )! + return (Data(repeating: 1, count: Int(byteRange.length)), response) + } + + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher( + url: URL(string: "https://cdn.example.test/movie.mp4")!, + headers: [:], + session: mockSession() + ), + contentLength: 80_000_000, + durationProvider: { 100 } + ) + defer { + session.cancelPrefetch() + } + + session.prefetch(aroundByteOffset: 28_242_716) + _ = try? await session.data(for: HTTPByteRange(start: 51_818_977, end: 52_867_552)) + try? await Task.sleep(nanoseconds: 50_000_000) + + let ranges = queue.sync { requestedRanges } + assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched") + assert(ranges.contains { range in + range.hasPrefix("bytes=51936225-") + }, "Expected prefetch to restart near VLC's foreground range, got \(ranges)") + session.cancelPrefetch() + MockURLProtocol.handler = nil + try? await Task.sleep(nanoseconds: 50_000_000) + } + + 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) + guard pieces.count == 2, + let start = Int64(pieces[0]) else { + return HTTPByteRange(start: 0, end: 0) + } + let end = pieces[1].isEmpty ? contentLength - 1 : (Int64(pieces[1]) ?? contentLength - 1) + return HTTPByteRange(start: start, end: min(end, contentLength - 1)) + } + private static func testRangeProbeFallsBackWhenServerIgnoresRange() async { MockURLProtocol.handler = { request in if request.httpMethod == "HEAD" { diff --git a/docs/turns/2026-05-25-vlc-local-range-cache.html b/docs/turns/2026-05-25-vlc-local-range-cache.html index ae398c9..4071930 100644 --- a/docs/turns/2026-05-25-vlc-local-range-cache.html +++ b/docs/turns/2026-05-25-vlc-local-range-cache.html @@ -575,6 +575,158 @@
let chunks = session.prefetchChunks(
in: HTTPByteRange(start: 0, end: 4_194_303),
preferredOffset: 2_200_000
)
assertEqual(chunks.prefix(2).map { $0 }, [
HTTPByteRange(start: 2_097_152, end: 3_145_727),
HTTPByteRange(start: 3_145_728, end: 4_194_303)
])
assertEqual(chunks.suffix(2).map { $0 }, [
HTTPByteRange(start: 0, end: 1_048_575),
HTTPByteRange(start: 1_048_576, end: 2_097_151)
])
}
private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
MockURLProtocol.handler = { request in
if request.httpMethod == "HEAD" {

Related issues or PRs

Related to Beads issue dreamio-42s and branch lavender/vlc-local-range-cache.

+

New Changes as of 2026-05-26 00:14 EDT

Summary of changes

Changed foreground cache misses from VLC into a stronger prefetch signal. When VLC asks for a real range that is far from the current prefetch cursor, Dreamio now cancels the stale speculative task and restarts prefetching beside VLC's actual requested bytes.

Why this change was made

The jump logs showed duration-based seek estimates could land around 28M while VLC immediately requested ranges around 52M. Because those real ranges were still inside the broad prefetch window, the cache previously kept fetching old chunks and left VLC buffering on repeated misses.

Code diffs

Rendered with @pierre/diffs/ssr. These diffs cover foreground miss reprioritization and the regression test that reproduces the observed jump pattern.

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
-2+33
258 unmodified lines
259
260
261
262
263
264
1 unmodified line
266
267
268
269
270
271
6 unmodified lines
278
279
280
281
282
283
284
285
286
6 unmodified lines
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
24 unmodified lines
333
334
335
336
337
338
339
340
341
342
343
344
345
346
258 unmodified lines
    private let responseChunkSize: Int64 = 1_048_576
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?

+
    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
        self.fetcher = fetcher
1 unmodified line
        self.durationProvider = durationProvider
    }

+
    func data(for requestedRange: HTTPByteRange) async throws -> Data {
        let bounded = clamp(requestedRange)
        if let data = store.data(for: bounded) {
6 unmodified lines
#if DEBUG
        print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)")
#endif
        let data = try await fetcher.fetch(range: bounded)
        store.insert(data: data, at: bounded.start)
        prefetch(aroundByteOffset: bounded.end + 1)
        return store.data(for: bounded) ?? data
    }

+
6 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        if activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
            return
        }

+
        prefetchTask?.cancel()
        let window = targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        store.evict(keeping: window)
        guard !store.hasData(for: window) else {
            activePrefetchWindow = nil
            return
        }

+
24 unmodified lines
                }
            }
            self.activePrefetchWindow = nil
        }
    }

+
    func byteOffset(for position: Float) -> Int64 {
        let clamped = max(0, min(1, position))
        return Int64(Float(contentLength) * clamped)
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        let bytesPerSecond = estimatedBytesPerSecond()
        let behind = max(prefetchChunkSize, bytesPerSecond * 30)
258 unmodified lines
259
260
261
262
263
264
265
1 unmodified line
267
268
269
270
271
272
273
274
275
276
6 unmodified lines
283
284
285
286
287
288
289
290
291
292
6 unmodified lines
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
24 unmodified lines
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
258 unmodified lines
    private let responseChunkSize: Int64 = 1_048_576
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?
    private var activePrefetchPreferredOffset: Int64?

+
    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
        self.fetcher = fetcher
1 unmodified line
        self.durationProvider = durationProvider
    }

+
    deinit {
        cancelPrefetch()
    }

+
    func data(for requestedRange: HTTPByteRange) async throws -> Data {
        let bounded = clamp(requestedRange)
        if let data = store.data(for: bounded) {
6 unmodified lines
#if DEBUG
        print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)")
#endif
        cancelPrefetchIfNeeded(forForegroundRange: bounded)
        let data = try await fetcher.fetch(range: bounded)
        store.insert(data: data, at: bounded.start)
        prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
        return store.data(for: bounded) ?? data
    }

+
6 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        prefetch(aroundByteOffset: offset, forceRestart: false)
    }

+
    func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) {
        if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
            return
        }

+
        prefetchTask?.cancel()
        let window = targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        activePrefetchPreferredOffset = offset
        store.evict(keeping: window)
        guard !store.hasData(for: window) else {
            activePrefetchWindow = nil
            activePrefetchPreferredOffset = nil
            return
        }

+
24 unmodified lines
                }
            }
            self.activePrefetchWindow = nil
            self.activePrefetchPreferredOffset = nil
        }
    }

+
    func cancelPrefetch() {
        prefetchTask?.cancel()
        activePrefetchWindow = nil
        activePrefetchPreferredOffset = nil
    }

+
    func byteOffset(for position: Float) -> Int64 {
        let clamped = max(0, min(1, position))
        return Int64(Float(contentLength) * clamped)
    }

+
    private func cancelPrefetchIfNeeded(forForegroundRange range: HTTPByteRange) {
        guard activePrefetchWindow?.contains(range.start) == true,
              let preferredOffset = activePrefetchPreferredOffset,
              abs(range.start - preferredOffset) >= responseChunkSize else {
            return
        }
#if DEBUG
        print("[DreamioRangeCache] prefetch reprioritize from=\(preferredOffset) to=\(range.start)")
#endif
        cancelPrefetch()
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        let bytesPerSecond = estimatedBytesPerSecond()
        let behind = max(prefetchChunkSize, bytesPerSecond * 30)

Tests/StreamResolverTests.swift

Tests/StreamResolverTests.swift
+57
36 unmodified lines
37
38
39
40
41
42
324 unmodified lines
367
368
369
370
371
372
36 unmodified lines
        testSparseRangeStoreTrimsOverlappingWindow()
        testRangeCacheSessionCapsResponseRange()
        testRangeCachePrefetchPrioritizesSeekOffset()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
324 unmodified lines
        ])
    }

+
    private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
        MockURLProtocol.handler = { request in
            if request.httpMethod == "HEAD" {
36 unmodified lines
37
38
39
40
41
42
43
324 unmodified lines
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
36 unmodified lines
        testSparseRangeStoreTrimsOverlappingWindow()
        testRangeCacheSessionCapsResponseRange()
        testRangeCachePrefetchPrioritizesSeekOffset()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
324 unmodified lines
        ])
    }

+
    private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-test")
        var requestedRanges: [String] = []
        MockURLProtocol.handler = { request in
            let range = request.value(forHTTPHeaderField: "Range") ?? ""
            queue.sync {
                requestedRanges.append(range)
            }
            let byteRange = byteRange(fromHeader: range, contentLength: 80_000_000)
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 206,
                httpVersion: nil,
                headerFields: ["Content-Range": "bytes \(byteRange.start)-\(byteRange.end)/80000000"]
            )!
            return (Data(repeating: 1, count: Int(byteRange.length)), response)
        }

+
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(
                url: URL(string: "https://cdn.example.test/movie.mp4")!,
                headers: [:],
                session: mockSession()
            ),
            contentLength: 80_000_000,
            durationProvider: { 100 }
        )
        defer {
            session.cancelPrefetch()
        }

+
        session.prefetch(aroundByteOffset: 28_242_716)
        _ = try? await session.data(for: HTTPByteRange(start: 51_818_977, end: 52_867_552))
        try? await Task.sleep(nanoseconds: 50_000_000)

+
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
        assert(ranges.contains { range in
            range.hasPrefix("bytes=51936225-")
        }, "Expected prefetch to restart near VLC's foreground range, got \(ranges)")
        session.cancelPrefetch()
        MockURLProtocol.handler = nil
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

+
    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)
        guard pieces.count == 2,
              let start = Int64(pieces[0]) else {
            return HTTPByteRange(start: 0, end: 0)
        }
        let end = pieces[1].isEmpty ? contentLength - 1 : (Int64(pieces[1]) ?? contentLength - 1)
        return HTTPByteRange(start: start, end: min(end, contentLength - 1))
    }

+
    private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
        MockURLProtocol.handler = { request in
            if request.httpMethod == "HEAD" {

Related issues or PRs

Related to Beads issue dreamio-meh and branch lavender/vlc-local-range-cache.

From 365dfb22f9f64581e0a5937c1592f88c90222b33 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:35:52 -0400 Subject: [PATCH 3/6] reduce vlc seek buffering with better cache priming --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 187 ++++++++++- Dreamio/VLCNativePlaybackBackend.swift | 11 +- Tests/StreamResolverTests.swift | 73 ++++- .../2026-05-26-reduce-vlc-seek-buffering.html | 298 ++++++++++++++++++ 6 files changed, 553 insertions(+), 18 deletions(-) create mode 100644 docs/turns/2026-05-26-reduce-vlc-seek-buffering.html diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index ce73f0e..2fabcc5 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -44,3 +44,4 @@ {"id":"int-b2667330","kind":"field_change","created_at":"2026-05-25T23:44:07.439593Z","actor":"dirtydishes","issue_id":"dreamio-9gw","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds."}} {"id":"int-6ca684f7","kind":"field_change","created_at":"2026-05-26T04:00:46.072019Z","actor":"dirtydishes","issue_id":"dreamio-42s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild."}} {"id":"int-176e3ad2","kind":"field_change","created_at":"2026-05-26T04:14:19.812849Z","actor":"dirtydishes","issue_id":"dreamio-meh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch."}} +{"id":"int-56a87fde","kind":"field_change","created_at":"2026-05-26T04:35:35.693504Z","actor":"dirtydishes","issue_id":"dreamio-3pn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 9ddaebb..a549252 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-3pn","title":"reduce vlc seek buffering with range cache priming","description":"Improve VLC local range cache behavior after seek/jump by priming bytes behind the target, using stable global chunk boundaries, retaining useful cached ranges under a byte budget, and adding tests for the observed post-seek request pattern.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:31:46Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:35:36Z","started_at":"2026-05-26T04:31:51Z","closed_at":"2026-05-26T04:35:36Z","close_reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-meh","title":"Use VLC range requests to reprioritize seek prefetch","description":"Jump logs show duration-based byteOffset estimates can be far behind VLC's actual post-seek range requests, so prefetch keeps warming stale bytes while VLC buffers on higher cache misses.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:11:38Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:14:20Z","started_at":"2026-05-26T04:11:40Z","closed_at":"2026-05-26T04:14:20Z","close_reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-42s","title":"Reduce VLC range-cache buffering after seeks","description":"Logs show repeated local-cache misses and cancelled prefetch tasks after VLC jumps backward, causing buffering while the cache restarts speculative requests instead of preserving useful adjacent downloads.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T03:58:03Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:00:46Z","started_at":"2026-05-26T03:58:10Z","closed_at":"2026-05-26T04:00:46Z","close_reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-9gw","title":"Cap VLC local range cache memory","description":"Playback can be killed for memory when VLC asks the loopback cache for a very large byte range. The local range cache should answer with bounded partial ranges and trim cached segments to the active window.","status":"closed","priority":1,"issue_type":"bug","owner":"dishes@dpdrm.com","created_at":"2026-05-25T23:38:08Z","created_by":"dirtydishes","updated_at":"2026-05-25T23:44:07Z","closed_at":"2026-05-25T23:44:07Z","close_reason":"Capped local range-cache responses to 1 MB chunks, trimmed cached overlap windows, added focused tests, and confirmed the iOS simulator build succeeds.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index a950b71..708080f 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -73,6 +73,12 @@ final class SparseHTTPByteRangeStore { } } + var cachedByteCount: Int64 { + lock.withLock { + segments.reduce(0) { $0 + Int64($1.data.count) } + } + } + func insert(data: Data, at start: Int64) { guard !data.isEmpty else { return @@ -117,6 +123,33 @@ final class SparseHTTPByteRangeStore { data(for: range) != nil } + func missingRanges(in range: HTTPByteRange) -> [HTTPByteRange] { + lock.withLock { + var cursor = range.start + var missing: [HTTPByteRange] = [] + + for segment in segments where segment.range.end >= cursor { + guard segment.range.start <= range.end else { + break + } + if segment.range.start > cursor { + missing.append(HTTPByteRange(start: cursor, end: min(range.end, segment.range.start - 1))) + } + if segment.range.end >= cursor { + cursor = max(cursor, segment.range.end + 1) + } + if cursor > range.end { + break + } + } + + if cursor <= range.end { + missing.append(HTTPByteRange(start: cursor, end: range.end)) + } + return missing + } + } + func evict(keeping window: HTTPByteRange) { lock.withLock { segments = segments.compactMap { segment in @@ -135,6 +168,61 @@ final class SparseHTTPByteRangeStore { } } + func evict(toByteBudget byteBudget: Int64, preserving protectedRanges: [HTTPByteRange]) -> [HTTPByteRange] { + lock.withLock { + guard byteBudget > 0 else { + let evicted = segments.map(\.range) + segments.removeAll() + return evicted + } + + var totalBytes = segments.reduce(0) { $0 + Int64($1.data.count) } + guard totalBytes > byteBudget else { + return [] + } + + var evicted: [HTTPByteRange] = [] + while totalBytes > byteBudget, + let index = evictionCandidateIndex(protectedRanges: protectedRanges) { + let removed = segments.remove(at: index) + totalBytes -= Int64(removed.data.count) + evicted.append(removed.range) + } + return evicted + } + } + + private func evictionCandidateIndex(protectedRanges: [HTTPByteRange]) -> Int? { + var bestIndex: Int? + var bestDistance: Int64 = .min + + for (index, segment) in segments.enumerated() { + if protectedRanges.contains(where: { $0.overlapsOrTouches(segment.range) }) { + continue + } + + let distance = protectedRanges + .map { rangeDistance(from: segment.range, to: $0) } + .min() ?? segment.range.start + if distance > bestDistance { + bestDistance = distance + bestIndex = index + } + } + + return bestIndex + } + + private func rangeDistance(from range: HTTPByteRange, to protectedRange: HTTPByteRange) -> Int64 { + if range.overlapsOrTouches(protectedRange) { + return 0 + } + if range.end < protectedRange.start { + return protectedRange.start - range.end + } + return range.start - protectedRange.end + } + private func mergeSegments() { guard !segments.isEmpty else { return @@ -257,14 +345,24 @@ final class ProgressiveHTTPRangeCacheSession { let durationProvider: () -> TimeInterval private let prefetchChunkSize: Int64 = 1_048_576 private let responseChunkSize: Int64 = 1_048_576 + private let seekPrimeBehindBytes: Int64 = 4 * 1_048_576 + private let cacheByteBudget: Int64 private var prefetchTask: Task? private var activePrefetchWindow: HTTPByteRange? private var activePrefetchPreferredOffset: Int64? + private var recentSeekRange: HTTPByteRange? + private var recentForegroundRange: HTTPByteRange? - init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) { + init( + fetcher: HTTPRangeRemoteFetcher, + contentLength: Int64, + durationProvider: @escaping () -> TimeInterval, + cacheByteBudget: Int64 = 64 * 1_048_576 + ) { self.fetcher = fetcher self.contentLength = contentLength self.durationProvider = durationProvider + self.cacheByteBudget = cacheByteBudget } deinit { @@ -273,6 +371,7 @@ final class ProgressiveHTTPRangeCacheSession { func data(for requestedRange: HTTPByteRange) async throws -> Data { let bounded = clamp(requestedRange) + recentForegroundRange = bounded if let data = store.data(for: bounded) { #if DEBUG print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)") @@ -280,14 +379,18 @@ final class ProgressiveHTTPRangeCacheSession { return data } + let missingRanges = store.missingRanges(in: bounded) #if DEBUG - print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)") + let missKind = missingRanges.count == 1 && missingRanges[0] == bounded ? "uncached" : "partial-miss" + print("[DreamioRangeCache] cache=\(missKind) range=\(bounded.start)-\(bounded.end) missing=\(missingRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))") #endif cancelPrefetchIfNeeded(forForegroundRange: bounded) - let data = try await fetcher.fetch(range: bounded) - store.insert(data: data, at: bounded.start) + for missingRange in missingRanges { + let data = try await fetcher.fetch(range: missingRange) + store.insert(data: data, at: missingRange.start) + } prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true) - return store.data(for: bounded) ?? data + return store.data(for: bounded) ?? Data() } func responseRange(for requestedRange: HTTPByteRange) -> HTTPByteRange { @@ -299,30 +402,54 @@ final class ProgressiveHTTPRangeCacheSession { } func prefetch(aroundByteOffset offset: Int64) { - prefetch(aroundByteOffset: offset, forceRestart: false) + prefetch(aroundByteOffset: offset, forceRestart: false, startsAtWindowStart: false) + } + + func prefetchForSeek(aroundByteOffset offset: Int64) { + let window = seekPrimeWindow(aroundByteOffset: offset) + recentSeekRange = window + prefetch( + aroundByteOffset: offset, + forceRestart: true, + explicitWindow: window, + startsAtWindowStart: true + ) + } + + func seekPrimeWindow(aroundByteOffset offset: Int64) -> HTTPByteRange { + targetWindow(aroundByteOffset: offset, minimumBehind: seekPrimeBehindBytes) } func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) { + prefetch(aroundByteOffset: offset, forceRestart: forceRestart, startsAtWindowStart: false) + } + + private func prefetch( + aroundByteOffset offset: Int64, + forceRestart: Bool, + explicitWindow: HTTPByteRange? = nil, + startsAtWindowStart: Bool + ) { if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false { return } prefetchTask?.cancel() - let window = targetWindow(aroundByteOffset: offset) + let window = explicitWindow ?? targetWindow(aroundByteOffset: offset) activePrefetchWindow = window activePrefetchPreferredOffset = offset - store.evict(keeping: window) + evictOverBudget(protecting: window) guard !store.hasData(for: window) else { activePrefetchWindow = nil activePrefetchPreferredOffset = nil return } - prefetchTask = Task { [weak self] in + prefetchTask = Task(priority: startsAtWindowStart ? .userInitiated : .utility) { [weak self] in guard let self else { return } - for chunk in self.prefetchChunks(in: window, preferredOffset: offset) { + for chunk in self.prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: startsAtWindowStart) { guard !Task.isCancelled else { return } @@ -330,6 +457,7 @@ final class ProgressiveHTTPRangeCacheSession { do { let data = try await fetcher.fetch(range: chunk) store.insert(data: data, at: chunk.start) + evictOverBudget(protecting: window) #if DEBUG print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)") #endif @@ -373,15 +501,25 @@ final class ProgressiveHTTPRangeCacheSession { } private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange { + targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize) + } + + private func targetWindow(aroundByteOffset offset: Int64, minimumBehind: Int64) -> HTTPByteRange { let bytesPerSecond = estimatedBytesPerSecond() - let behind = max(prefetchChunkSize, bytesPerSecond * 30) + let behind = max(minimumBehind, bytesPerSecond * 30) let ahead = max(prefetchChunkSize * 2, bytesPerSecond * 60) - return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead)) + let raw = clamp(HTTPByteRange(start: offset - behind, end: offset + ahead)) + return HTTPByteRange(start: alignedChunkStart(for: raw.start), end: alignedChunkEnd(for: raw.end)) } func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] { + prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: false) + } + + func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64, startsAtWindowStart: Bool) -> [HTTPByteRange] { let boundedOffset = max(window.start, min(window.end, offset)) - let preferredStart = window.start + ((boundedOffset - window.start) / prefetchChunkSize) * prefetchChunkSize + let windowStart = alignedChunkStart(for: window.start) + let preferredStart = startsAtWindowStart ? windowStart : alignedChunkStart(for: boundedOffset) var chunks: [HTTPByteRange] = [] var cursor = preferredStart @@ -391,7 +529,7 @@ final class ProgressiveHTTPRangeCacheSession { cursor = chunk.end + 1 } - cursor = window.start + cursor = windowStart while cursor < preferredStart { let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1)) chunks.append(chunk) @@ -401,6 +539,27 @@ final class ProgressiveHTTPRangeCacheSession { return chunks } + private func evictOverBudget(protecting range: HTTPByteRange) { + let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1)) + let tailStart = max(0, contentLength - (4 * prefetchChunkSize)) + let tailRange = HTTPByteRange(start: tailStart, end: contentLength - 1) + let protectedRanges = [range, recentSeekRange, recentForegroundRange, activePrefetchWindow, headerRange, tailRange].compactMap { $0 } + let evicted = store.evict(toByteBudget: cacheByteBudget, preserving: protectedRanges) +#if DEBUG + if !evicted.isEmpty { + print("[DreamioRangeCache] evicted reason=budget ranges=\(evicted.map { "\($0.start)-\($0.end)" }.joined(separator: ",")) protected=\(protectedRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))") + } +#endif + } + + private func alignedChunkStart(for offset: Int64) -> Int64 { + max(0, (offset / prefetchChunkSize) * prefetchChunkSize) + } + + private func alignedChunkEnd(for offset: Int64) -> Int64 { + min(contentLength - 1, alignedChunkStart(for: offset) + prefetchChunkSize - 1) + } + private func estimatedBytesPerSecond() -> Int64 { let duration = durationProvider() guard duration > 1 else { diff --git a/Dreamio/VLCNativePlaybackBackend.swift b/Dreamio/VLCNativePlaybackBackend.swift index 4dcb69a..1bb340a 100644 --- a/Dreamio/VLCNativePlaybackBackend.swift +++ b/Dreamio/VLCNativePlaybackBackend.swift @@ -151,7 +151,7 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend { return } let clamped = max(0, min(1, position)) - rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0) + rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0) #if DEBUG if let byteOffset = rangeCacheSession?.byteOffset(for: clamped) { print("[DreamioVLC] seek targetPosition=\(clamped) byteOffset=\(byteOffset) mode=local-cache") @@ -171,7 +171,7 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend { let nextTime = max(0, min(duration, currentTime + seconds)) if duration > 0 { let nextPosition = Float(nextTime / duration) - rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0) + rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0) #if DEBUG if let byteOffset = rangeCacheSession?.byteOffset(for: nextPosition) { print("[DreamioVLC] jump seconds=\(seconds) target=\(nextTime) byteOffset=\(byteOffset) mode=local-cache") @@ -604,6 +604,13 @@ final class VLCNativePlaybackBackend: NSObject, NativePlaybackBackend { #if canImport(MobileVLCKit) extension VLCNativePlaybackBackend: VLCMediaPlayerDelegate { func mediaPlayerStateChanged(_ aNotification: Notification) { + Task { @MainActor [weak self] in + self?.handleMediaPlayerStateChanged() + } + } + + @MainActor + private func handleMediaPlayerStateChanged() { #if DEBUG logPlaybackStateIfNeeded(stateName(mediaPlayer.state)) #endif diff --git a/Tests/StreamResolverTests.swift b/Tests/StreamResolverTests.swift index 3a00f2c..679675a 100644 --- a/Tests/StreamResolverTests.swift +++ b/Tests/StreamResolverTests.swift @@ -35,8 +35,11 @@ struct StreamResolverTests { testSparseRangeStoreHitPartialHitAndMiss() testSparseRangeStoreEvictsOutsideWindow() testSparseRangeStoreTrimsOverlappingWindow() + testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges() testRangeCacheSessionCapsResponseRange() testRangeCachePrefetchPrioritizesSeekOffset() + testRangeCacheSeekPrimingIncludesObservedVLCStart() + testRangeCachePrefetchUsesGlobalChunkBoundaries() await testRangeCacheForegroundMissReprioritizesPrefetch() await testRangeProbeFallsBackWhenServerIgnoresRange() await testRangeFetcherPreservesHeaders() @@ -334,6 +337,28 @@ struct StreamResolverTests { assert(store.data(for: HTTPByteRange(start: 0, end: 5)) == nil, "Expected trimmed bytes outside the window to be evicted") } + private static func testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges() { + let store = SparseHTTPByteRangeStore() + + store.insert(data: Data(repeating: 1, count: 4), at: 0) + store.insert(data: Data(repeating: 2, count: 4), at: 100) + store.insert(data: Data(repeating: 3, count: 4), at: 200) + + let evicted = store.evict( + toByteBudget: 8, + preserving: [ + HTTPByteRange(start: 0, end: 3), + HTTPByteRange(start: 190, end: 210) + ] + ) + + assertEqual(evicted, [HTTPByteRange(start: 100, end: 103)]) + assertEqual(store.cachedRanges, [ + HTTPByteRange(start: 0, end: 3), + HTTPByteRange(start: 200, end: 203) + ]) + } + private static func testRangeCacheSessionCapsResponseRange() { let session = ProgressiveHTTPRangeCacheSession( fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), @@ -368,6 +393,50 @@ struct StreamResolverTests { ]) } + private static func testRangeCacheSeekPrimingIncludesObservedVLCStart() { + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), + contentLength: 711_080_522, + durationProvider: { 0 } + ) + + let estimatedOffset: Int64 = 213_615_760 + let firstVLCRequest = HTTPByteRange(start: 212_942_432, end: 213_991_007) + let window = session.seekPrimeWindow(aroundByteOffset: estimatedOffset) + let chunks = session.prefetchChunks( + in: window, + preferredOffset: estimatedOffset, + startsAtWindowStart: true + ) + + let chunkContainingVLCStart = chunks.firstIndex { $0.contains(firstVLCRequest.start) } + let chunkContainingEstimatedOffset = chunks.firstIndex { $0.contains(estimatedOffset) } + + assert(chunkContainingVLCStart != nil, "Expected seek priming to include VLC's first request start") + assert(chunkContainingEstimatedOffset != nil, "Expected seek priming to include the estimated offset") + assert( + chunkContainingVLCStart! <= chunkContainingEstimatedOffset!, + "Expected bytes behind the seek target to be primed before ahead chunks" + ) + assertEqual(chunks[chunkContainingVLCStart!], HTTPByteRange(start: 212_860_928, end: 213_909_503)) + } + + private static func testRangeCachePrefetchUsesGlobalChunkBoundaries() { + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), + contentLength: 711_080_522, + durationProvider: { 0 } + ) + + let chunks = session.prefetchChunks( + in: HTTPByteRange(start: 213_278_260, end: 216_000_000), + preferredOffset: 213_615_760 + ) + + assert(chunks.allSatisfy { $0.start % 1_048_576 == 0 }, "Expected prefetch chunk starts to use stable global 1 MB boundaries: \(chunks)") + assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503)) + } + private static func testRangeCacheForegroundMissReprioritizesPrefetch() async { let queue = DispatchQueue(label: "dreamio.range-cache-test") var requestedRanges: [String] = [] @@ -406,8 +475,8 @@ struct StreamResolverTests { let ranges = queue.sync { requestedRanges } assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched") assert(ranges.contains { range in - range.hasPrefix("bytes=51936225-") - }, "Expected prefetch to restart near VLC's foreground range, got \(ranges)") + range.hasPrefix("bytes=52428800-") + }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)") session.cancelPrefetch() MockURLProtocol.handler = nil try? await Task.sleep(nanoseconds: 50_000_000) diff --git a/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html new file mode 100644 index 0000000..5d03339 --- /dev/null +++ b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html @@ -0,0 +1,298 @@ + + + + + +Dreamio Turn: VLC Seek Range Cache Priming + + + +
+
2026-05-26

VLC Seek Range Cache Priming

Dreamio now primes local VLC range-cache seeks from stable 1 MB boundaries behind the estimated target, retains useful nearby bytes under a bounded budget, and logs foreground misses with more precision.

+

Summary

Reduced post-seek buffering risk in native VLC playback by making seek and jump prefetch conservative behind the target instead of only racing ahead from the estimated byte offset.

+

Changes Made

  • Added seek-specific prefetch through prefetchForSeek, with a 4 MB backward prime window and user-initiated task priority for the first chunks.
  • Aligned prefetch chunks to global 1 MB boundaries so repeated VLC requests reuse stable cached ranges.
  • Replaced prefetch-window eviction with a 64 MB bounded cache budget that preserves active playback, recent seek, header, and tail/index ranges.
  • Changed foreground miss handling to fetch only missing subranges and log uncached versus partial-miss.
  • Routed VLC delegate state handling onto the main actor before reading player state or firing UI callbacks.
  • Added tests for the observed VLC request pattern, global chunk alignment, and budget retention.
+

Context

A 15-second skip estimated byte 213615760, while VLC’s first real read started at 212942432. The old prefetch overlapped the request but missed its front edge, then eviction could discard ranges that were still useful during the next VLC probes.

+

Important Implementation Details

  • The observed request and estimated seek offset both fall inside global chunk 212860928-213909503, so seek priming now warms that chunk before later ahead chunks.
  • Normal prefetch still prefers the playhead area, while seek prefetch starts at the backward-biased window start.
  • Cache eviction removes unprotected segments farthest from protected areas until the byte budget is met; protected ranges are not trimmed simply because a new prefetch window appears.
  • Foreground reads cancel or reprioritize normal prefetch when VLC asks outside the expected area.
+

Relevant Diff Snippets

Rendered with @pierre/diffs/ssr.

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
-15+174
72 unmodified lines
73
74
75
76
77
78
38 unmodified lines
117
118
119
120
121
122
12 unmodified lines
135
136
137
138
139
140
116 unmodified lines
257
258
259
260
261
262
263
264
265
266
267
268
269
270
2 unmodified lines
273
274
275
276
277
278
1 unmodified line
280
281
282
283
284
285
286
287
288
289
290
291
292
293
5 unmodified lines
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
1 unmodified line
330
331
332
333
334
335
37 unmodified lines
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
3 unmodified lines
391
392
393
394
395
396
397
3 unmodified lines
401
402
403
404
405
406
72 unmodified lines
        }
    }

+
    func insert(data: Data, at start: Int64) {
        guard !data.isEmpty else {
            return
38 unmodified lines
        data(for: range) != nil
    }

+
    func evict(keeping window: HTTPByteRange) {
        lock.withLock {
            segments = segments.compactMap { segment in
12 unmodified lines
        }
    }

+
    private func mergeSegments() {
        guard !segments.isEmpty else {
            return
116 unmodified lines
    let durationProvider: () -> TimeInterval
    private let prefetchChunkSize: Int64 = 1_048_576
    private let responseChunkSize: Int64 = 1_048_576
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?
    private var activePrefetchPreferredOffset: Int64?

+
    init(fetcher: HTTPRangeRemoteFetcher, contentLength: Int64, durationProvider: @escaping () -> TimeInterval) {
        self.fetcher = fetcher
        self.contentLength = contentLength
        self.durationProvider = durationProvider
    }

+
    deinit {
2 unmodified lines

+
    func data(for requestedRange: HTTPByteRange) async throws -> Data {
        let bounded = clamp(requestedRange)
        if let data = store.data(for: bounded) {
#if DEBUG
            print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)")
1 unmodified line
            return data
        }

+
#if DEBUG
        print("[DreamioRangeCache] cache=miss range=\(bounded.start)-\(bounded.end)")
#endif
        cancelPrefetchIfNeeded(forForegroundRange: bounded)
        let data = try await fetcher.fetch(range: bounded)
        store.insert(data: data, at: bounded.start)
        prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
        return store.data(for: bounded) ?? data
    }

+
    func responseRange(for requestedRange: HTTPByteRange) -> HTTPByteRange {
5 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        prefetch(aroundByteOffset: offset, forceRestart: false)
    }

+
    func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) {
        if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
            return
        }

+
        prefetchTask?.cancel()
        let window = targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        activePrefetchPreferredOffset = offset
        store.evict(keeping: window)
        guard !store.hasData(for: window) else {
            activePrefetchWindow = nil
            activePrefetchPreferredOffset = nil
            return
        }

+
        prefetchTask = Task { [weak self] in
            guard let self else {
                return
            }
            for chunk in self.prefetchChunks(in: window, preferredOffset: offset) {
                guard !Task.isCancelled else {
                    return
                }
1 unmodified line
                    do {
                        let data = try await fetcher.fetch(range: chunk)
                        store.insert(data: data, at: chunk.start)
#if DEBUG
                        print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)")
#endif
37 unmodified lines
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        let bytesPerSecond = estimatedBytesPerSecond()
        let behind = max(prefetchChunkSize, bytesPerSecond * 30)
        let ahead = max(prefetchChunkSize * 2, bytesPerSecond * 60)
        return clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
    }

+
    func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] {
        let boundedOffset = max(window.start, min(window.end, offset))
        let preferredStart = window.start + ((boundedOffset - window.start) / prefetchChunkSize) * prefetchChunkSize
        var chunks: [HTTPByteRange] = []

+
        var cursor = preferredStart
3 unmodified lines
            cursor = chunk.end + 1
        }

+
        cursor = window.start
        while cursor < preferredStart {
            let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1))
            chunks.append(chunk)
3 unmodified lines
        return chunks
    }

+
    private func estimatedBytesPerSecond() -> Int64 {
        let duration = durationProvider()
        guard duration > 1 else {
72 unmodified lines
73
74
75
76
77
78
79
80
81
82
83
84
38 unmodified lines
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
12 unmodified lines
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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
116 unmodified lines
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
2 unmodified lines
371
372
373
374
375
376
377
1 unmodified line
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
5 unmodified lines
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
1 unmodified line
457
458
459
460
461
462
463
37 unmodified lines
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
3 unmodified lines
529
530
531
532
533
534
535
3 unmodified lines
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
72 unmodified lines
        }
    }

+
    var cachedByteCount: Int64 {
        lock.withLock {
            segments.reduce(0) { $0 + Int64($1.data.count) }
        }
    }

+
    func insert(data: Data, at start: Int64) {
        guard !data.isEmpty else {
            return
38 unmodified lines
        data(for: range) != nil
    }

+
    func missingRanges(in range: HTTPByteRange) -> [HTTPByteRange] {
        lock.withLock {
            var cursor = range.start
            var missing: [HTTPByteRange] = []

+
            for segment in segments where segment.range.end >= cursor {
                guard segment.range.start <= range.end else {
                    break
                }
                if segment.range.start > cursor {
                    missing.append(HTTPByteRange(start: cursor, end: min(range.end, segment.range.start - 1)))
                }
                if segment.range.end >= cursor {
                    cursor = max(cursor, segment.range.end + 1)
                }
                if cursor > range.end {
                    break
                }
            }

+
            if cursor <= range.end {
                missing.append(HTTPByteRange(start: cursor, end: range.end))
            }
            return missing
        }
    }

+
    func evict(keeping window: HTTPByteRange) {
        lock.withLock {
            segments = segments.compactMap { segment in
12 unmodified lines
        }
    }

+
    func evict(toByteBudget byteBudget: Int64, preserving protectedRanges: [HTTPByteRange]) -> [HTTPByteRange] {
        lock.withLock {
            guard byteBudget > 0 else {
                let evicted = segments.map(\.range)
                segments.removeAll()
                return evicted
            }

+
            var totalBytes = segments.reduce(0) { $0 + Int64($1.data.count) }
            guard totalBytes > byteBudget else {
                return []
            }

+
            var evicted: [HTTPByteRange] = []
            while totalBytes > byteBudget,
                  let index = evictionCandidateIndex(protectedRanges: protectedRanges) {
                let removed = segments.remove(at: index)
                totalBytes -= Int64(removed.data.count)
                evicted.append(removed.range)
            }
            return evicted
        }
    }

+
    private func evictionCandidateIndex(protectedRanges: [HTTPByteRange]) -> Int? {
        var bestIndex: Int?
        var bestDistance: Int64 = .min

+
        for (index, segment) in segments.enumerated() {
            if protectedRanges.contains(where: { $0.overlapsOrTouches(segment.range) }) {
                continue
            }

+
            let distance = protectedRanges
                .map { rangeDistance(from: segment.range, to: $0) }
                .min() ?? segment.range.start
            if distance > bestDistance {
                bestDistance = distance
                bestIndex = index
            }
        }

+
        return bestIndex
    }

+
    private func rangeDistance(from range: HTTPByteRange, to protectedRange: HTTPByteRange) -> Int64 {
        if range.overlapsOrTouches(protectedRange) {
            return 0
        }
        if range.end < protectedRange.start {
            return protectedRange.start - range.end
        }
        return range.start - protectedRange.end
    }

+
    private func mergeSegments() {
        guard !segments.isEmpty else {
            return
116 unmodified lines
    let durationProvider: () -> TimeInterval
    private let prefetchChunkSize: Int64 = 1_048_576
    private let responseChunkSize: Int64 = 1_048_576
    private let seekPrimeBehindBytes: Int64 = 4 * 1_048_576
    private let cacheByteBudget: Int64
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?
    private var activePrefetchPreferredOffset: Int64?
    private var recentSeekRange: HTTPByteRange?
    private var recentForegroundRange: HTTPByteRange?

+
    init(
        fetcher: HTTPRangeRemoteFetcher,
        contentLength: Int64,
        durationProvider: @escaping () -> TimeInterval,
        cacheByteBudget: Int64 = 64 * 1_048_576
    ) {
        self.fetcher = fetcher
        self.contentLength = contentLength
        self.durationProvider = durationProvider
        self.cacheByteBudget = cacheByteBudget
    }

+
    deinit {
2 unmodified lines

+
    func data(for requestedRange: HTTPByteRange) async throws -> Data {
        let bounded = clamp(requestedRange)
        recentForegroundRange = bounded
        if let data = store.data(for: bounded) {
#if DEBUG
            print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)")
1 unmodified line
            return data
        }

+
        let missingRanges = store.missingRanges(in: bounded)
#if DEBUG
        let missKind = missingRanges.count == 1 && missingRanges[0] == bounded ? "uncached" : "partial-miss"
        print("[DreamioRangeCache] cache=\(missKind) range=\(bounded.start)-\(bounded.end) missing=\(missingRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))")
#endif
        cancelPrefetchIfNeeded(forForegroundRange: bounded)
        for missingRange in missingRanges {
            let data = try await fetcher.fetch(range: missingRange)
            store.insert(data: data, at: missingRange.start)
        }
        prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
        return store.data(for: bounded) ?? Data()
    }

+
    func responseRange(for requestedRange: HTTPByteRange) -> HTTPByteRange {
5 unmodified lines
    }

+
    func prefetch(aroundByteOffset offset: Int64) {
        prefetch(aroundByteOffset: offset, forceRestart: false, startsAtWindowStart: false)
    }

+
    func prefetchForSeek(aroundByteOffset offset: Int64) {
        let window = seekPrimeWindow(aroundByteOffset: offset)
        recentSeekRange = window
        prefetch(
            aroundByteOffset: offset,
            forceRestart: true,
            explicitWindow: window,
            startsAtWindowStart: true
        )
    }

+
    func seekPrimeWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        targetWindow(aroundByteOffset: offset, minimumBehind: seekPrimeBehindBytes)
    }

+
    func prefetch(aroundByteOffset offset: Int64, forceRestart: Bool) {
        prefetch(aroundByteOffset: offset, forceRestart: forceRestart, startsAtWindowStart: false)
    }

+
    private func prefetch(
        aroundByteOffset offset: Int64,
        forceRestart: Bool,
        explicitWindow: HTTPByteRange? = nil,
        startsAtWindowStart: Bool
    ) {
        if !forceRestart, activePrefetchWindow?.contains(offset) == true, prefetchTask?.isCancelled == false {
            return
        }

+
        prefetchTask?.cancel()
        let window = explicitWindow ?? targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        activePrefetchPreferredOffset = offset
        evictOverBudget(protecting: window)
        guard !store.hasData(for: window) else {
            activePrefetchWindow = nil
            activePrefetchPreferredOffset = nil
            return
        }

+
        prefetchTask = Task(priority: startsAtWindowStart ? .userInitiated : .utility) { [weak self] in
            guard let self else {
                return
            }
            for chunk in self.prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: startsAtWindowStart) {
                guard !Task.isCancelled else {
                    return
                }
1 unmodified line
                    do {
                        let data = try await fetcher.fetch(range: chunk)
                        store.insert(data: data, at: chunk.start)
                        evictOverBudget(protecting: window)
#if DEBUG
                        print("[DreamioRangeCache] fetched range=\(chunk.start)-\(chunk.end) bytes=\(data.count)")
#endif
37 unmodified lines
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize)
    }

+
    private func targetWindow(aroundByteOffset offset: Int64, minimumBehind: Int64) -> HTTPByteRange {
        let bytesPerSecond = estimatedBytesPerSecond()
        let behind = max(minimumBehind, bytesPerSecond * 30)
        let ahead = max(prefetchChunkSize * 2, bytesPerSecond * 60)
        let raw = clamp(HTTPByteRange(start: offset - behind, end: offset + ahead))
        return HTTPByteRange(start: alignedChunkStart(for: raw.start), end: alignedChunkEnd(for: raw.end))
    }

+
    func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64) -> [HTTPByteRange] {
        prefetchChunks(in: window, preferredOffset: offset, startsAtWindowStart: false)
    }

+
    func prefetchChunks(in window: HTTPByteRange, preferredOffset offset: Int64, startsAtWindowStart: Bool) -> [HTTPByteRange] {
        let boundedOffset = max(window.start, min(window.end, offset))
        let windowStart = alignedChunkStart(for: window.start)
        let preferredStart = startsAtWindowStart ? windowStart : alignedChunkStart(for: boundedOffset)
        var chunks: [HTTPByteRange] = []

+
        var cursor = preferredStart
3 unmodified lines
            cursor = chunk.end + 1
        }

+
        cursor = windowStart
        while cursor < preferredStart {
            let chunk = HTTPByteRange(start: cursor, end: min(preferredStart - 1, cursor + prefetchChunkSize - 1))
            chunks.append(chunk)
3 unmodified lines
        return chunks
    }

+
    private func evictOverBudget(protecting range: HTTPByteRange) {
        let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1))
        let tailStart = max(0, contentLength - (4 * prefetchChunkSize))
        let tailRange = HTTPByteRange(start: tailStart, end: contentLength - 1)
        let protectedRanges = [range, recentSeekRange, recentForegroundRange, activePrefetchWindow, headerRange, tailRange].compactMap { $0 }
        let evicted = store.evict(toByteBudget: cacheByteBudget, preserving: protectedRanges)
#if DEBUG
        if !evicted.isEmpty {
            print("[DreamioRangeCache] evicted reason=budget ranges=\(evicted.map { "\($0.start)-\($0.end)" }.joined(separator: ",")) protected=\(protectedRanges.map { "\($0.start)-\($0.end)" }.joined(separator: ","))")
        }
#endif
    }

+
    private func alignedChunkStart(for offset: Int64) -> Int64 {
        max(0, (offset / prefetchChunkSize) * prefetchChunkSize)
    }

+
    private func alignedChunkEnd(for offset: Int64) -> Int64 {
        min(contentLength - 1, alignedChunkStart(for: offset) + prefetchChunkSize - 1)
    }

+
    private func estimatedBytesPerSecond() -> Int64 {
        let duration = durationProvider()
        guard duration > 1 else {

Dreamio/VLCNativePlaybackBackend.swift

Dreamio/VLCNativePlaybackBackend.swift
-2+9
150 unmodified lines
151
152
153
154
155
156
157
13 unmodified lines
171
172
173
174
175
176
177
426 unmodified lines
604
605
606
607
608
609
150 unmodified lines
            return
        }
        let clamped = max(0, min(1, position))
        rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0)
#if DEBUG
        if let byteOffset = rangeCacheSession?.byteOffset(for: clamped) {
            print("[DreamioVLC] seek targetPosition=\(clamped) byteOffset=\(byteOffset) mode=local-cache")
13 unmodified lines
        let nextTime = max(0, min(duration, currentTime + seconds))
        if duration > 0 {
            let nextPosition = Float(nextTime / duration)
            rangeCacheSession?.prefetch(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0)
#if DEBUG
            if let byteOffset = rangeCacheSession?.byteOffset(for: nextPosition) {
                print("[DreamioVLC] jump seconds=\(seconds) target=\(nextTime) byteOffset=\(byteOffset) mode=local-cache")
426 unmodified lines
#if canImport(MobileVLCKit)
extension VLCNativePlaybackBackend: VLCMediaPlayerDelegate {
    func mediaPlayerStateChanged(_ aNotification: Notification) {
#if DEBUG
        logPlaybackStateIfNeeded(stateName(mediaPlayer.state))
#endif
150 unmodified lines
151
152
153
154
155
156
157
13 unmodified lines
171
172
173
174
175
176
177
426 unmodified lines
604
605
606
607
608
609
610
611
612
613
614
615
616
150 unmodified lines
            return
        }
        let clamped = max(0, min(1, position))
        rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: clamped) ?? 0)
#if DEBUG
        if let byteOffset = rangeCacheSession?.byteOffset(for: clamped) {
            print("[DreamioVLC] seek targetPosition=\(clamped) byteOffset=\(byteOffset) mode=local-cache")
13 unmodified lines
        let nextTime = max(0, min(duration, currentTime + seconds))
        if duration > 0 {
            let nextPosition = Float(nextTime / duration)
            rangeCacheSession?.prefetchForSeek(aroundByteOffset: rangeCacheSession?.byteOffset(for: nextPosition) ?? 0)
#if DEBUG
            if let byteOffset = rangeCacheSession?.byteOffset(for: nextPosition) {
                print("[DreamioVLC] jump seconds=\(seconds) target=\(nextTime) byteOffset=\(byteOffset) mode=local-cache")
426 unmodified lines
#if canImport(MobileVLCKit)
extension VLCNativePlaybackBackend: VLCMediaPlayerDelegate {
    func mediaPlayerStateChanged(_ aNotification: Notification) {
        Task { @MainActor [weak self] in
            self?.handleMediaPlayerStateChanged()
        }
    }

+
    @MainActor
    private func handleMediaPlayerStateChanged() {
#if DEBUG
        logPlaybackStateIfNeeded(stateName(mediaPlayer.state))
#endif

Tests/StreamResolverTests.swift

Tests/StreamResolverTests.swift
-2+71
34 unmodified lines
35
36
37
38
39
40
41
42
291 unmodified lines
334
335
336
337
338
339
28 unmodified lines
368
369
370
371
372
373
32 unmodified lines
406
407
408
409
410
411
412
413
34 unmodified lines
        testSparseRangeStoreHitPartialHitAndMiss()
        testSparseRangeStoreEvictsOutsideWindow()
        testSparseRangeStoreTrimsOverlappingWindow()
        testRangeCacheSessionCapsResponseRange()
        testRangeCachePrefetchPrioritizesSeekOffset()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
291 unmodified lines
        assert(store.data(for: HTTPByteRange(start: 0, end: 5)) == nil, "Expected trimmed bytes outside the window to be evicted")
    }

+
    private static func testRangeCacheSessionCapsResponseRange() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
28 unmodified lines
        ])
    }

+
    private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-test")
        var requestedRanges: [String] = []
32 unmodified lines
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
        assert(ranges.contains { range in
            range.hasPrefix("bytes=51936225-")
        }, "Expected prefetch to restart near VLC's foreground range, got \(ranges)")
        session.cancelPrefetch()
        MockURLProtocol.handler = nil
        try? await Task.sleep(nanoseconds: 50_000_000)
34 unmodified lines
35
36
37
38
39
40
41
42
43
44
45
291 unmodified lines
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
28 unmodified lines
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
32 unmodified lines
475
476
477
478
479
480
481
482
34 unmodified lines
        testSparseRangeStoreHitPartialHitAndMiss()
        testSparseRangeStoreEvictsOutsideWindow()
        testSparseRangeStoreTrimsOverlappingWindow()
        testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges()
        testRangeCacheSessionCapsResponseRange()
        testRangeCachePrefetchPrioritizesSeekOffset()
        testRangeCacheSeekPrimingIncludesObservedVLCStart()
        testRangeCachePrefetchUsesGlobalChunkBoundaries()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
291 unmodified lines
        assert(store.data(for: HTTPByteRange(start: 0, end: 5)) == nil, "Expected trimmed bytes outside the window to be evicted")
    }

+
    private static func testSparseRangeStoreEvictsByBudgetWhilePreservingUsefulRanges() {
        let store = SparseHTTPByteRangeStore()

+
        store.insert(data: Data(repeating: 1, count: 4), at: 0)
        store.insert(data: Data(repeating: 2, count: 4), at: 100)
        store.insert(data: Data(repeating: 3, count: 4), at: 200)

+
        let evicted = store.evict(
            toByteBudget: 8,
            preserving: [
                HTTPByteRange(start: 0, end: 3),
                HTTPByteRange(start: 190, end: 210)
            ]
        )

+
        assertEqual(evicted, [HTTPByteRange(start: 100, end: 103)])
        assertEqual(store.cachedRanges, [
            HTTPByteRange(start: 0, end: 3),
            HTTPByteRange(start: 200, end: 203)
        ])
    }

+
    private static func testRangeCacheSessionCapsResponseRange() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
28 unmodified lines
        ])
    }

+
    private static func testRangeCacheSeekPrimingIncludesObservedVLCStart() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
            contentLength: 711_080_522,
            durationProvider: { 0 }
        )

+
        let estimatedOffset: Int64 = 213_615_760
        let firstVLCRequest = HTTPByteRange(start: 212_942_432, end: 213_991_007)
        let window = session.seekPrimeWindow(aroundByteOffset: estimatedOffset)
        let chunks = session.prefetchChunks(
            in: window,
            preferredOffset: estimatedOffset,
            startsAtWindowStart: true
        )

+
        let chunkContainingVLCStart = chunks.firstIndex { $0.contains(firstVLCRequest.start) }
        let chunkContainingEstimatedOffset = chunks.firstIndex { $0.contains(estimatedOffset) }

+
        assert(chunkContainingVLCStart != nil, "Expected seek priming to include VLC's first request start")
        assert(chunkContainingEstimatedOffset != nil, "Expected seek priming to include the estimated offset")
        assert(
            chunkContainingVLCStart! <= chunkContainingEstimatedOffset!,
            "Expected bytes behind the seek target to be primed before ahead chunks"
        )
        assertEqual(chunks[chunkContainingVLCStart!], HTTPByteRange(start: 212_860_928, end: 213_909_503))
    }

+
    private static func testRangeCachePrefetchUsesGlobalChunkBoundaries() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
            contentLength: 711_080_522,
            durationProvider: { 0 }
        )

+
        let chunks = session.prefetchChunks(
            in: HTTPByteRange(start: 213_278_260, end: 216_000_000),
            preferredOffset: 213_615_760
        )

+
        assert(chunks.allSatisfy { $0.start % 1_048_576 == 0 }, "Expected prefetch chunk starts to use stable global 1 MB boundaries: \(chunks)")
        assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503))
    }

+
    private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-test")
        var requestedRanges: [String] = []
32 unmodified lines
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
        assert(ranges.contains { range in
            range.hasPrefix("bytes=52428800-")
        }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)")
        session.cancelPrefetch()
        MockURLProtocol.handler = nil
        try? await Task.sleep(nanoseconds: 50_000_000)
+

Expected Impact for End-Users

Short backward or forward skips in MKV/direct-file playback should resume with fewer full foreground misses, especially when VLC asks slightly before Dreamio’s estimated byte position.

+

Validation

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

Issues, Limitations, and Mitigations

  • No device playback check was run in this turn, so real MobileVLCKit timing still needs confirmation on hardware.
  • The cache remains memory-only. The 64 MB budget limits growth while retaining the ranges most likely to matter after seeks and MKV index probes.
  • The existing MobileVLCKit/OpenGLES warning is treated as internal unless it persists after the main-actor cleanup.
+

Follow-up Work

  • Manually test MKV skip behavior on device and compare DEBUG logs for post-seek hit, partial-miss, and uncached reads.
  • Consider exposing cache budget tuning if device memory pressure shows up in longer playback sessions.
  • Track any persistent VLCOpenGLES2VideoView warnings separately with device logs if they continue.
+
+ + \ No newline at end of file From 0f3101ce5cfa2931b46cb085ba853b3c9b9b7ed0 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:40:23 -0400 Subject: [PATCH 4/6] follow vlc foreground reads after seeks --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 34 +++- Tests/StreamResolverTests.swift | 60 ++++++- .../2026-05-26-reduce-vlc-seek-buffering.html | 146 ++++++++++++++++++ 5 files changed, 239 insertions(+), 3 deletions(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index 2fabcc5..f1377d2 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -45,3 +45,4 @@ {"id":"int-6ca684f7","kind":"field_change","created_at":"2026-05-26T04:00:46.072019Z","actor":"dirtydishes","issue_id":"dreamio-42s","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild."}} {"id":"int-176e3ad2","kind":"field_change","created_at":"2026-05-26T04:14:19.812849Z","actor":"dirtydishes","issue_id":"dreamio-meh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch."}} {"id":"int-56a87fde","kind":"field_change","created_at":"2026-05-26T04:35:35.693504Z","actor":"dirtydishes","issue_id":"dreamio-3pn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation."}} +{"id":"int-91b3db21","kind":"field_change","created_at":"2026-05-26T04:40:10.299245Z","actor":"dirtydishes","issue_id":"dreamio-mi1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index a549252..45b452b 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-mi1","title":"adapt vlc prefetch to actual post-seek reads","description":"Use real foreground VLC reads after a seek as a prefetch signal even when they are cache hits, and fetch aligned chunks for partial foreground misses so the cache warms ahead before VLC reaches the edge of retained data.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:38:14Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:40:10Z","started_at":"2026-05-26T04:38:16Z","closed_at":"2026-05-26T04:40:10Z","close_reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-3pn","title":"reduce vlc seek buffering with range cache priming","description":"Improve VLC local range cache behavior after seek/jump by priming bytes behind the target, using stable global chunk boundaries, retaining useful cached ranges under a byte budget, and adding tests for the observed post-seek request pattern.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:31:46Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:35:36Z","started_at":"2026-05-26T04:31:51Z","closed_at":"2026-05-26T04:35:36Z","close_reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-meh","title":"Use VLC range requests to reprioritize seek prefetch","description":"Jump logs show duration-based byteOffset estimates can be far behind VLC's actual post-seek range requests, so prefetch keeps warming stale bytes while VLC buffers on higher cache misses.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:11:38Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:14:20Z","started_at":"2026-05-26T04:11:40Z","closed_at":"2026-05-26T04:14:20Z","close_reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-42s","title":"Reduce VLC range-cache buffering after seeks","description":"Logs show repeated local-cache misses and cancelled prefetch tasks after VLC jumps backward, causing buffering while the cache restarts speculative requests instead of preserving useful adjacent downloads.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T03:58:03Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:00:46Z","started_at":"2026-05-26T03:58:10Z","closed_at":"2026-05-26T04:00:46Z","close_reason":"Fixed seek-time range-cache prefetching to prioritize the post-seek byte offset and avoid cancelling active prefetch work inside the same window; added focused coverage and validated with StreamResolverTests plus xcodebuild.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index 708080f..31d711e 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -376,6 +376,7 @@ final class ProgressiveHTTPRangeCacheSession { #if DEBUG print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)") #endif + prefetchAheadIfForegroundMoved(to: bounded) return data } @@ -386,8 +387,13 @@ final class ProgressiveHTTPRangeCacheSession { #endif cancelPrefetchIfNeeded(forForegroundRange: bounded) for missingRange in missingRanges { - let data = try await fetcher.fetch(range: missingRange) - store.insert(data: data, at: missingRange.start) + for fetchRange in alignedChunks(covering: missingRange) where !store.hasData(for: fetchRange) { + let data = try await fetcher.fetch(range: fetchRange) + store.insert(data: data, at: fetchRange.start) +#if DEBUG + print("[DreamioRangeCache] foreground fetched range=\(fetchRange.start)-\(fetchRange.end) bytes=\(data.count)") +#endif + } } prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true) return store.data(for: bounded) ?? Data() @@ -500,6 +506,18 @@ final class ProgressiveHTTPRangeCacheSession { cancelPrefetch() } + private func prefetchAheadIfForegroundMoved(to range: HTTPByteRange) { + guard activePrefetchWindow?.contains(range.start) == true, + let preferredOffset = activePrefetchPreferredOffset, + abs(range.start - preferredOffset) >= responseChunkSize else { + return + } +#if DEBUG + print("[DreamioRangeCache] prefetch follow-foreground from=\(preferredOffset) to=\(range.end + 1)") +#endif + prefetch(aroundByteOffset: range.end + 1, forceRestart: true) + } + private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange { targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize) } @@ -539,6 +557,18 @@ final class ProgressiveHTTPRangeCacheSession { return chunks } + func alignedChunks(covering range: HTTPByteRange) -> [HTTPByteRange] { + let bounded = clamp(range) + var chunks: [HTTPByteRange] = [] + var cursor = alignedChunkStart(for: bounded.start) + while cursor <= bounded.end { + let chunk = HTTPByteRange(start: cursor, end: min(contentLength - 1, cursor + prefetchChunkSize - 1)) + chunks.append(chunk) + cursor = chunk.end + 1 + } + return chunks + } + private func evictOverBudget(protecting range: HTTPByteRange) { let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1)) let tailStart = max(0, contentLength - (4 * prefetchChunkSize)) diff --git a/Tests/StreamResolverTests.swift b/Tests/StreamResolverTests.swift index 679675a..368e877 100644 --- a/Tests/StreamResolverTests.swift +++ b/Tests/StreamResolverTests.swift @@ -40,7 +40,9 @@ struct StreamResolverTests { testRangeCachePrefetchPrioritizesSeekOffset() testRangeCacheSeekPrimingIncludesObservedVLCStart() testRangeCachePrefetchUsesGlobalChunkBoundaries() + testRangeCacheForegroundMissFetchesAlignedChunks() await testRangeCacheForegroundMissReprioritizesPrefetch() + await testRangeCacheHitFollowsActualPostSeekReadArea() await testRangeProbeFallsBackWhenServerIgnoresRange() await testRangeFetcherPreservesHeaders() print("StreamResolverTests passed") @@ -437,6 +439,18 @@ struct StreamResolverTests { assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503)) } + private static func testRangeCacheForegroundMissFetchesAlignedChunks() { + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]), + contentLength: 711_080_522, + durationProvider: { 0 } + ) + + let chunks = session.alignedChunks(covering: HTTPByteRange(start: 48_234_649, end: 49_185_907)) + + assertEqual(chunks, [HTTPByteRange(start: 48_234_496, end: 49_283_071)]) + } + private static func testRangeCacheForegroundMissReprioritizesPrefetch() async { let queue = DispatchQueue(label: "dreamio.range-cache-test") var requestedRanges: [String] = [] @@ -473,7 +487,7 @@ struct StreamResolverTests { try? await Task.sleep(nanoseconds: 50_000_000) let ranges = queue.sync { requestedRanges } - assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched") + assert(ranges.contains("bytes=51380224-52428799"), "Expected foreground VLC miss to fetch aligned cache chunks") assert(ranges.contains { range in range.hasPrefix("bytes=52428800-") }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)") @@ -482,6 +496,50 @@ struct StreamResolverTests { try? await Task.sleep(nanoseconds: 50_000_000) } + private static func testRangeCacheHitFollowsActualPostSeekReadArea() async { + let queue = DispatchQueue(label: "dreamio.range-cache-hit-follow-test") + var requestedRanges: [String] = [] + MockURLProtocol.handler = { request in + let range = request.value(forHTTPHeaderField: "Range") ?? "" + queue.sync { + requestedRanges.append(range) + } + let byteRange = byteRange(fromHeader: range, contentLength: 80_000_000) + let response = HTTPURLResponse( + url: request.url!, + statusCode: 206, + httpVersion: nil, + headerFields: ["Content-Range": "bytes \(byteRange.start)-\(byteRange.end)/80000000"] + )! + return (Data(repeating: 1, count: Int(byteRange.length)), response) + } + + let session = ProgressiveHTTPRangeCacheSession( + fetcher: HTTPRangeRemoteFetcher( + url: URL(string: "https://cdn.example.test/movie.mp4")!, + headers: [:], + session: mockSession() + ), + contentLength: 80_000_000, + durationProvider: { 100 } + ) + defer { + session.cancelPrefetch() + } + + session.store.insert(data: Data(repeating: 7, count: 1_048_576), at: 27_165_812) + session.prefetchForSeek(aroundByteOffset: 15_936_567) + _ = try? await session.data(for: HTTPByteRange(start: 27_165_812, end: 28_214_387)) + try? await Task.sleep(nanoseconds: 100_000_000) + + let ranges = queue.sync { requestedRanges } + assert(ranges.contains { range in + range.hasPrefix("bytes=27262976-") + }, "Expected a cache hit far from the seek estimate to restart prefetch near VLC's real read area, got \(ranges)") + MockURLProtocol.handler = nil + try? await Task.sleep(nanoseconds: 50_000_000) + } + 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) diff --git a/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html index 5d03339..8c8b0e5 100644 --- a/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html +++ b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html @@ -293,6 +293,152 @@ code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; fo

Validation

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

Issues, Limitations, and Mitigations

  • No device playback check was run in this turn, so real MobileVLCKit timing still needs confirmation on hardware.
  • The cache remains memory-only. The 64 MB budget limits growth while retaining the ranges most likely to matter after seeks and MKV index probes.
  • The existing MobileVLCKit/OpenGLES warning is treated as internal unless it persists after the main-actor cleanup.

Follow-up Work

  • Manually test MKV skip behavior on device and compare DEBUG logs for post-seek hit, partial-miss, and uncached reads.
  • Consider exposing cache budget tuning if device memory pressure shows up in longer playback sessions.
  • Track any persistent VLCOpenGLES2VideoView warnings separately with device logs if they continue.
+

New Changes as of 2026-05-26 00:40 EDT

Summary of changes

Adjusted the cache to follow VLC's actual foreground read area even when those reads are hits, and changed foreground partial misses to fetch stable aligned chunks synchronously.

Why this change was made

Device logs showed a backward jump estimating byte 15936567, while VLC continued reading from about 27165812 through the warmed cache. Because those reads were hits, prefetch stayed near the estimate until VLC reached the cache edge and began partial misses.

Code diffs

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
-2+32
375 unmodified lines
376
377
378
379
380
381
4 unmodified lines
386
387
388
389
390
391
392
393
106 unmodified lines
500
501
502
503
504
505
33 unmodified lines
539
540
541
542
543
544
375 unmodified lines
#if DEBUG
            print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)")
#endif
            return data
        }

+
4 unmodified lines
#endif
        cancelPrefetchIfNeeded(forForegroundRange: bounded)
        for missingRange in missingRanges {
            let data = try await fetcher.fetch(range: missingRange)
            store.insert(data: data, at: missingRange.start)
        }
        prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
        return store.data(for: bounded) ?? Data()
106 unmodified lines
        cancelPrefetch()
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize)
    }
33 unmodified lines
        return chunks
    }

+
    private func evictOverBudget(protecting range: HTTPByteRange) {
        let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1))
        let tailStart = max(0, contentLength - (4 * prefetchChunkSize))
375 unmodified lines
376
377
378
379
380
381
382
4 unmodified lines
387
388
389
390
391
392
393
394
395
396
397
398
399
106 unmodified lines
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
33 unmodified lines
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
375 unmodified lines
#if DEBUG
            print("[DreamioRangeCache] cache=hit range=\(bounded.start)-\(bounded.end)")
#endif
            prefetchAheadIfForegroundMoved(to: bounded)
            return data
        }

+
4 unmodified lines
#endif
        cancelPrefetchIfNeeded(forForegroundRange: bounded)
        for missingRange in missingRanges {
            for fetchRange in alignedChunks(covering: missingRange) where !store.hasData(for: fetchRange) {
                let data = try await fetcher.fetch(range: fetchRange)
                store.insert(data: data, at: fetchRange.start)
#if DEBUG
                print("[DreamioRangeCache] foreground fetched range=\(fetchRange.start)-\(fetchRange.end) bytes=\(data.count)")
#endif
            }
        }
        prefetch(aroundByteOffset: bounded.end + 1, forceRestart: true)
        return store.data(for: bounded) ?? Data()
106 unmodified lines
        cancelPrefetch()
    }

+
    private func prefetchAheadIfForegroundMoved(to range: HTTPByteRange) {
        guard activePrefetchWindow?.contains(range.start) == true,
              let preferredOffset = activePrefetchPreferredOffset,
              abs(range.start - preferredOffset) >= responseChunkSize else {
            return
        }
#if DEBUG
        print("[DreamioRangeCache] prefetch follow-foreground from=\(preferredOffset) to=\(range.end + 1)")
#endif
        prefetch(aroundByteOffset: range.end + 1, forceRestart: true)
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
        targetWindow(aroundByteOffset: offset, minimumBehind: prefetchChunkSize)
    }
33 unmodified lines
        return chunks
    }

+
    func alignedChunks(covering range: HTTPByteRange) -> [HTTPByteRange] {
        let bounded = clamp(range)
        var chunks: [HTTPByteRange] = []
        var cursor = alignedChunkStart(for: bounded.start)
        while cursor <= bounded.end {
            let chunk = HTTPByteRange(start: cursor, end: min(contentLength - 1, cursor + prefetchChunkSize - 1))
            chunks.append(chunk)
            cursor = chunk.end + 1
        }
        return chunks
    }

+
    private func evictOverBudget(protecting range: HTTPByteRange) {
        let headerRange = HTTPByteRange(start: 0, end: min(contentLength - 1, prefetchChunkSize - 1))
        let tailStart = max(0, contentLength - (4 * prefetchChunkSize))

Tests/StreamResolverTests.swift

Tests/StreamResolverTests.swift
-1+59
39 unmodified lines
40
41
42
43
44
45
46
390 unmodified lines
437
438
439
440
441
442
30 unmodified lines
473
474
475
476
477
478
479
2 unmodified lines
482
483
484
485
486
487
39 unmodified lines
        testRangeCachePrefetchPrioritizesSeekOffset()
        testRangeCacheSeekPrimingIncludesObservedVLCStart()
        testRangeCachePrefetchUsesGlobalChunkBoundaries()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
390 unmodified lines
        assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503))
    }

+
    private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-test")
        var requestedRanges: [String] = []
30 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)

+
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
        assert(ranges.contains { range in
            range.hasPrefix("bytes=52428800-")
        }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)")
2 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

+
    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)
39 unmodified lines
40
41
42
43
44
45
46
47
48
390 unmodified lines
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
30 unmodified lines
487
488
489
490
491
492
493
2 unmodified lines
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
39 unmodified lines
        testRangeCachePrefetchPrioritizesSeekOffset()
        testRangeCacheSeekPrimingIncludesObservedVLCStart()
        testRangeCachePrefetchUsesGlobalChunkBoundaries()
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
390 unmodified lines
        assertEqual(chunks[0], HTTPByteRange(start: 212_860_928, end: 213_909_503))
    }

+
    private static func testRangeCacheForegroundMissFetchesAlignedChunks() {
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(url: URL(string: "https://example.test/video.mkv")!, headers: [:]),
            contentLength: 711_080_522,
            durationProvider: { 0 }
        )

+
        let chunks = session.alignedChunks(covering: HTTPByteRange(start: 48_234_649, end: 49_185_907))

+
        assertEqual(chunks, [HTTPByteRange(start: 48_234_496, end: 49_283_071)])
    }

+
    private static func testRangeCacheForegroundMissReprioritizesPrefetch() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-test")
        var requestedRanges: [String] = []
30 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)

+
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains("bytes=51380224-52428799"), "Expected foreground VLC miss to fetch aligned cache chunks")
        assert(ranges.contains { range in
            range.hasPrefix("bytes=52428800-")
        }, "Expected prefetch to restart on a global chunk boundary near VLC's foreground range, got \(ranges)")
2 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

+
    private static func testRangeCacheHitFollowsActualPostSeekReadArea() async {
        let queue = DispatchQueue(label: "dreamio.range-cache-hit-follow-test")
        var requestedRanges: [String] = []
        MockURLProtocol.handler = { request in
            let range = request.value(forHTTPHeaderField: "Range") ?? ""
            queue.sync {
                requestedRanges.append(range)
            }
            let byteRange = byteRange(fromHeader: range, contentLength: 80_000_000)
            let response = HTTPURLResponse(
                url: request.url!,
                statusCode: 206,
                httpVersion: nil,
                headerFields: ["Content-Range": "bytes \(byteRange.start)-\(byteRange.end)/80000000"]
            )!
            return (Data(repeating: 1, count: Int(byteRange.length)), response)
        }

+
        let session = ProgressiveHTTPRangeCacheSession(
            fetcher: HTTPRangeRemoteFetcher(
                url: URL(string: "https://cdn.example.test/movie.mp4")!,
                headers: [:],
                session: mockSession()
            ),
            contentLength: 80_000_000,
            durationProvider: { 100 }
        )
        defer {
            session.cancelPrefetch()
        }

+
        session.store.insert(data: Data(repeating: 7, count: 1_048_576), at: 27_165_812)
        session.prefetchForSeek(aroundByteOffset: 15_936_567)
        _ = try? await session.data(for: HTTPByteRange(start: 27_165_812, end: 28_214_387))
        try? await Task.sleep(nanoseconds: 100_000_000)

+
        let ranges = queue.sync { requestedRanges }
        assert(ranges.contains { range in
            range.hasPrefix("bytes=27262976-")
        }, "Expected a cache hit far from the seek estimate to restart prefetch near VLC's real read area, got \(ranges)")
        MockURLProtocol.handler = nil
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

+
    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-mi1.

\ No newline at end of file From adda8b7b029ce8b99a8709f93e2dc482e5a4756c Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:48:13 -0400 Subject: [PATCH 5/6] fix stale range cache prefetch state --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 16 +++- .../2026-05-26-reduce-vlc-seek-buffering.html | 83 +++++++++++++++++++ 4 files changed, 99 insertions(+), 2 deletions(-) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index f1377d2..afa3c8c 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -46,3 +46,4 @@ {"id":"int-176e3ad2","kind":"field_change","created_at":"2026-05-26T04:14:19.812849Z","actor":"dirtydishes","issue_id":"dreamio-meh","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch."}} {"id":"int-56a87fde","kind":"field_change","created_at":"2026-05-26T04:35:35.693504Z","actor":"dirtydishes","issue_id":"dreamio-3pn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation."}} {"id":"int-91b3db21","kind":"field_change","created_at":"2026-05-26T04:40:10.299245Z","actor":"dirtydishes","issue_id":"dreamio-mi1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document."}} +{"id":"int-ff0aeb09","kind":"field_change","created_at":"2026-05-26T04:47:44.48931Z","actor":"dirtydishes","issue_id":"dreamio-2hw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed stale local range-cache prefetch state after cached seek reads and documented the validation."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 45b452b..4249ce3 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-2hw","title":"Fix range cache prefetch cursor after cached seek reads","description":"Skipping after the local range cache has warmed can leave prefetch following an older foreground cursor instead of the post-seek cached read position. Update the cache so cached foreground reads can reset the follow cursor and add regression coverage.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:45:44Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:47:44Z","started_at":"2026-05-26T04:46:36Z","closed_at":"2026-05-26T04:47:44Z","close_reason":"Fixed stale local range-cache prefetch state after cached seek reads and documented the validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-mi1","title":"adapt vlc prefetch to actual post-seek reads","description":"Use real foreground VLC reads after a seek as a prefetch signal even when they are cache hits, and fetch aligned chunks for partial foreground misses so the cache warms ahead before VLC reaches the edge of retained data.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:38:14Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:40:10Z","started_at":"2026-05-26T04:38:16Z","closed_at":"2026-05-26T04:40:10Z","close_reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-3pn","title":"reduce vlc seek buffering with range cache priming","description":"Improve VLC local range cache behavior after seek/jump by priming bytes behind the target, using stable global chunk boundaries, retaining useful cached ranges under a byte budget, and adding tests for the observed post-seek request pattern.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:31:46Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:35:36Z","started_at":"2026-05-26T04:31:51Z","closed_at":"2026-05-26T04:35:36Z","close_reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-meh","title":"Use VLC range requests to reprioritize seek prefetch","description":"Jump logs show duration-based byteOffset estimates can be far behind VLC's actual post-seek range requests, so prefetch keeps warming stale bytes while VLC buffers on higher cache misses.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:11:38Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:14:20Z","started_at":"2026-05-26T04:11:40Z","closed_at":"2026-05-26T04:14:20Z","close_reason":"Fixed range-cache prefetch reprioritization so foreground VLC misses cancel stale speculative work and restart around VLC's actual requested byte range; added regression coverage for the observed jump mismatch.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index 31d711e..fffdbc4 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -350,6 +350,7 @@ final class ProgressiveHTTPRangeCacheSession { private var prefetchTask: Task? private var activePrefetchWindow: HTTPByteRange? private var activePrefetchPreferredOffset: Int64? + private var prefetchGeneration: UInt64 = 0 private var recentSeekRange: HTTPByteRange? private var recentForegroundRange: HTTPByteRange? @@ -441,6 +442,8 @@ final class ProgressiveHTTPRangeCacheSession { } prefetchTask?.cancel() + prefetchGeneration += 1 + let generation = prefetchGeneration let window = explicitWindow ?? targetWindow(aroundByteOffset: offset) activePrefetchWindow = window activePrefetchPreferredOffset = offset @@ -462,6 +465,9 @@ final class ProgressiveHTTPRangeCacheSession { if !store.hasData(for: chunk) { do { let data = try await fetcher.fetch(range: chunk) + guard !Task.isCancelled else { + return + } store.insert(data: data, at: chunk.start) evictOverBudget(protecting: window) #if DEBUG @@ -478,6 +484,9 @@ final class ProgressiveHTTPRangeCacheSession { } } } + guard self.prefetchGeneration == generation else { + return + } self.activePrefetchWindow = nil self.activePrefetchPreferredOffset = nil } @@ -485,6 +494,7 @@ final class ProgressiveHTTPRangeCacheSession { func cancelPrefetch() { prefetchTask?.cancel() + prefetchGeneration += 1 activePrefetchWindow = nil activePrefetchPreferredOffset = nil } @@ -512,10 +522,12 @@ final class ProgressiveHTTPRangeCacheSession { abs(range.start - preferredOffset) >= responseChunkSize else { return } + let nextOffset = range.end + 1 #if DEBUG - print("[DreamioRangeCache] prefetch follow-foreground from=\(preferredOffset) to=\(range.end + 1)") + let reason = nextOffset < preferredOffset ? "reanchor-foreground" : "follow-foreground" + print("[DreamioRangeCache] prefetch \(reason) from=\(preferredOffset) to=\(nextOffset)") #endif - prefetch(aroundByteOffset: range.end + 1, forceRestart: true) + prefetch(aroundByteOffset: nextOffset, forceRestart: true) } private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange { diff --git a/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html index 8c8b0e5..0e313b0 100644 --- a/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html +++ b/docs/turns/2026-05-26-reduce-vlc-seek-buffering.html @@ -439,6 +439,89 @@ code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; fo
session.store.insert(data: Data(repeating: 7, count: 1_048_576), at: 27_165_812)
session.prefetchForSeek(aroundByteOffset: 15_936_567)
_ = try? await session.data(for: HTTPByteRange(start: 27_165_812, end: 28_214_387))
try? await Task.sleep(nanoseconds: 100_000_000)
let ranges = queue.sync { requestedRanges }
assert(ranges.contains { range in
range.hasPrefix("bytes=27262976-")
}, "Expected a cache hit far from the seek estimate to restart prefetch near VLC's real read area, got \(ranges)")
MockURLProtocol.handler = nil
try? await Task.sleep(nanoseconds: 50_000_000)
}
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-mi1.

+
+

New Changes as of May 26, 2026 at 10:52 AM EDT

+

Summary of changes

+

Updated the local HTTP range cache prefetch bookkeeping after reviewing fresh device logs from normal playback and a warmed-cache 15 second skip. Normal cold-cache misses are expected, but the warmed-cache skip showed the foreground read moving behind the active prefetch cursor while older prefetch state could still finish and mutate session state.

+

Why this change was made

+

The cache should follow the bytes VLC is actually reading after a skip, not keep stale prefetch state alive after a newer foreground read has reoriented the cache. This update makes canceled prefetch workers stop before inserting fetched bytes after cancellation and prevents stale workers from clearing newer active prefetch state.

+

Code diffs

+

Rendered with @pierre/diffs/ssr.

+

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
-2+14
349 unmodified lines
350
351
352
353
354
355
85 unmodified lines
441
442
443
444
445
446
15 unmodified lines
462
463
464
465
466
467
10 unmodified lines
478
479
480
481
482
483
1 unmodified line
485
486
487
488
489
490
21 unmodified lines
512
513
514
515
516
517
518
519
520
521
349 unmodified lines
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?
    private var activePrefetchPreferredOffset: Int64?
    private var recentSeekRange: HTTPByteRange?
    private var recentForegroundRange: HTTPByteRange?

+
85 unmodified lines
        }

+
        prefetchTask?.cancel()
        let window = explicitWindow ?? targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        activePrefetchPreferredOffset = offset
15 unmodified lines
                if !store.hasData(for: chunk) {
                    do {
                        let data = try await fetcher.fetch(range: chunk)
                        store.insert(data: data, at: chunk.start)
                        evictOverBudget(protecting: window)
#if DEBUG
10 unmodified lines
                    }
                }
            }
            self.activePrefetchWindow = nil
            self.activePrefetchPreferredOffset = nil
        }
1 unmodified line

+
    func cancelPrefetch() {
        prefetchTask?.cancel()
        activePrefetchWindow = nil
        activePrefetchPreferredOffset = nil
    }
21 unmodified lines
              abs(range.start - preferredOffset) >= responseChunkSize else {
            return
        }
#if DEBUG
        print("[DreamioRangeCache] prefetch follow-foreground from=\(preferredOffset) to=\(range.end + 1)")
#endif
        prefetch(aroundByteOffset: range.end + 1, forceRestart: true)
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
349 unmodified lines
350
351
352
353
354
355
356
85 unmodified lines
442
443
444
445
446
447
448
449
15 unmodified lines
465
466
467
468
469
470
471
472
473
10 unmodified lines
484
485
486
487
488
489
490
491
492
1 unmodified line
494
495
496
497
498
499
500
21 unmodified lines
522
523
524
525
526
527
528
529
530
531
532
533
349 unmodified lines
    private var prefetchTask: Task<Void, Never>?
    private var activePrefetchWindow: HTTPByteRange?
    private var activePrefetchPreferredOffset: Int64?
    private var prefetchGeneration: UInt64 = 0
    private var recentSeekRange: HTTPByteRange?
    private var recentForegroundRange: HTTPByteRange?

+
85 unmodified lines
        }

+
        prefetchTask?.cancel()
        prefetchGeneration += 1
        let generation = prefetchGeneration
        let window = explicitWindow ?? targetWindow(aroundByteOffset: offset)
        activePrefetchWindow = window
        activePrefetchPreferredOffset = offset
15 unmodified lines
                if !store.hasData(for: chunk) {
                    do {
                        let data = try await fetcher.fetch(range: chunk)
                        guard !Task.isCancelled else {
                            return
                        }
                        store.insert(data: data, at: chunk.start)
                        evictOverBudget(protecting: window)
#if DEBUG
10 unmodified lines
                    }
                }
            }
            guard self.prefetchGeneration == generation else {
                return
            }
            self.activePrefetchWindow = nil
            self.activePrefetchPreferredOffset = nil
        }
1 unmodified line

+
    func cancelPrefetch() {
        prefetchTask?.cancel()
        prefetchGeneration += 1
        activePrefetchWindow = nil
        activePrefetchPreferredOffset = nil
    }
21 unmodified lines
              abs(range.start - preferredOffset) >= responseChunkSize else {
            return
        }
        let nextOffset = range.end + 1
#if DEBUG
        let reason = nextOffset < preferredOffset ? "reanchor-foreground" : "follow-foreground"
        print("[DreamioRangeCache] prefetch \(reason) from=\(preferredOffset) to=\(nextOffset)")
#endif
        prefetch(aroundByteOffset: nextOffset, forceRestart: true)
    }

+
    private func targetWindow(aroundByteOffset offset: Int64) -> HTTPByteRange {
+

Related issues or PRs

+

Beads issue dreamio-2hw.

+
+ \ No newline at end of file From 46a52b533f9b9f5b87a9756de41ba29cf2db253c Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Tue, 26 May 2026 00:56:24 -0400 Subject: [PATCH 6/6] bypass range cache for mkv playback --- .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 1 + Dreamio/ProgressiveHTTPRangeCache.swift | 8 + Tests/StreamResolverTests.swift | 27 ++++ .../2026-05-25-vlc-local-range-cache.html | 148 ++++++++++++++++++ 5 files changed, 185 insertions(+) diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl index afa3c8c..6ce3541 100644 --- a/.beads/interactions.jsonl +++ b/.beads/interactions.jsonl @@ -47,3 +47,4 @@ {"id":"int-56a87fde","kind":"field_change","created_at":"2026-05-26T04:35:35.693504Z","actor":"dirtydishes","issue_id":"dreamio-3pn","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation."}} {"id":"int-91b3db21","kind":"field_change","created_at":"2026-05-26T04:40:10.299245Z","actor":"dirtydishes","issue_id":"dreamio-mi1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document."}} {"id":"int-ff0aeb09","kind":"field_change","created_at":"2026-05-26T04:47:44.48931Z","actor":"dirtydishes","issue_id":"dreamio-2hw","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Fixed stale local range-cache prefetch state after cached seek reads and documented the validation."}} +{"id":"int-204223f5","kind":"field_change","created_at":"2026-05-26T04:56:13.920284Z","actor":"dirtydishes","issue_id":"dreamio-816","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Bypassed the local range cache for Matroska-family tail-index containers and added a regression test confirming MKV probes fall back to direct VLC playback without issuing cache probe requests."}} diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 4249ce3..a9fbbae 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,5 +1,6 @@ {"_type":"issue","id":"dreamio-mun","title":"fix vlc cache loopback port startup","description":"Device logs showed local-cache playback opening http://127.0.0.1:0, because the NWListener ephemeral port was read before the listener reached ready. Wait for the real assigned port before returning the local cache URL.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T22:32:41Z","created_by":"dirtydishes","updated_at":"2026-05-25T22:33:15Z","started_at":"2026-05-25T22:33:14Z","closed_at":"2026-05-25T22:33:15Z","close_reason":"Wait for NWListener ready state before returning the local cache URL; verified tests and simulator build.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-8cz","title":"fix stremio external subtitle loading regression","description":"After adding late subtitle forwarding for native playback, Stremio external subtitle loading is failing. Investigate the injected bridge and native subtitle forwarding path, then adjust behavior so Stremio can still load external subtitles while native playback receives late candidates.","status":"closed","priority":0,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-25T11:05:42Z","created_by":"dirtydishes","updated_at":"2026-05-25T11:07:35Z","started_at":"2026-05-25T11:05:55Z","closed_at":"2026-05-25T11:07:35Z","close_reason":"Hardened subtitle bridge network observers so non-text Stremio subtitle loads are not touched, and made parser traversal deterministic for metadata preservation.","dependency_count":0,"dependent_count":0,"comment_count":0} +{"_type":"issue","id":"dreamio-816","title":"Fix local range cache playback buffering","description":"Normal VLC playback can stay in buffering after the local progressive HTTP range cache is enabled. Logs show VLC repeatedly probes header/tail MKV ranges through the loopback server while the cache foreground fetch path serializes 1 MB remote requests. Investigate and adjust the cache path so normal direct-file playback can start reliably.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:54:13Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:56:14Z","started_at":"2026-05-26T04:54:17Z","closed_at":"2026-05-26T04:56:14Z","close_reason":"Bypassed the local range cache for Matroska-family tail-index containers and added a regression test confirming MKV probes fall back to direct VLC playback without issuing cache probe requests.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-2hw","title":"Fix range cache prefetch cursor after cached seek reads","description":"Skipping after the local range cache has warmed can leave prefetch following an older foreground cursor instead of the post-seek cached read position. Update the cache so cached foreground reads can reset the follow cursor and add regression coverage.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:45:44Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:47:44Z","started_at":"2026-05-26T04:46:36Z","closed_at":"2026-05-26T04:47:44Z","close_reason":"Fixed stale local range-cache prefetch state after cached seek reads and documented the validation.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-mi1","title":"adapt vlc prefetch to actual post-seek reads","description":"Use real foreground VLC reads after a seek as a prefetch signal even when they are cache hits, and fetch aligned chunks for partial foreground misses so the cache warms ahead before VLC reaches the edge of retained data.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:38:14Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:40:10Z","started_at":"2026-05-26T04:38:16Z","closed_at":"2026-05-26T04:40:10Z","close_reason":"Used actual foreground VLC reads as prefetch follow signals on hits and changed foreground misses to fetch aligned chunks; added regression tests and updated the turn document.","dependency_count":0,"dependent_count":0,"comment_count":0} {"_type":"issue","id":"dreamio-3pn","title":"reduce vlc seek buffering with range cache priming","description":"Improve VLC local range cache behavior after seek/jump by priming bytes behind the target, using stable global chunk boundaries, retaining useful cached ranges under a byte budget, and adding tests for the observed post-seek request pattern.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-26T04:31:46Z","created_by":"dirtydishes","updated_at":"2026-05-26T04:35:36Z","started_at":"2026-05-26T04:31:51Z","closed_at":"2026-05-26T04:35:36Z","close_reason":"Implemented backward-biased seek priming, global 1 MB range-cache chunk alignment, bounded protected eviction, partial foreground miss fetching/logging, main-actor VLC delegate handling, tests, and turn documentation.","dependency_count":0,"dependent_count":0,"comment_count":0} diff --git a/Dreamio/ProgressiveHTTPRangeCache.swift b/Dreamio/ProgressiveHTTPRangeCache.swift index fffdbc4..776789c 100644 --- a/Dreamio/ProgressiveHTTPRangeCache.swift +++ b/Dreamio/ProgressiveHTTPRangeCache.swift @@ -272,6 +272,9 @@ final class HTTPRangeRemoteFetcher { 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) { @@ -330,6 +333,11 @@ final class HTTPRangeRemoteFetcher { private func header(_ name: String, in response: HTTPURLResponse) -> String? { 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 { diff --git a/Tests/StreamResolverTests.swift b/Tests/StreamResolverTests.swift index 368e877..8f3dab7 100644 --- a/Tests/StreamResolverTests.swift +++ b/Tests/StreamResolverTests.swift @@ -43,6 +43,7 @@ struct StreamResolverTests { testRangeCacheForegroundMissFetchesAlignedChunks() await testRangeCacheForegroundMissReprioritizesPrefetch() await testRangeCacheHitFollowsActualPostSeekReadArea() + await testRangeProbeBypassesTailIndexContainers() await testRangeProbeFallsBackWhenServerIgnoresRange() await testRangeFetcherPreservesHeaders() print("StreamResolverTests passed") @@ -540,6 +541,32 @@ struct StreamResolverTests { 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( + url: URL(string: "https://cdn.example.test/show.mkv?token=secret")!, + headers: [:], + session: mockSession() + ) + let probe = await fetcher.probe() + + assertEqual(probe.isCacheable, false) + assertEqual(probe.fallbackReason, "tail-index-container") + assertEqual(requestCount, 0) + 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) diff --git a/docs/turns/2026-05-25-vlc-local-range-cache.html b/docs/turns/2026-05-25-vlc-local-range-cache.html index 4071930..1aa73c2 100644 --- a/docs/turns/2026-05-25-vlc-local-range-cache.html +++ b/docs/turns/2026-05-25-vlc-local-range-cache.html @@ -727,6 +727,154 @@
let ranges = queue.sync { requestedRanges }
assert(ranges.contains("bytes=51818977-52867552"), "Expected foreground VLC range to be fetched")
assert(ranges.contains { range in
range.hasPrefix("bytes=51936225-")
}, "Expected prefetch to restart near VLC's foreground range, got \(ranges)")
session.cancelPrefetch()
MockURLProtocol.handler = nil
try? await Task.sleep(nanoseconds: 50_000_000)
}
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)
guard pieces.count == 2,
let start = Int64(pieces[0]) else {
return HTTPByteRange(start: 0, end: 0)
}
let end = pieces[1].isEmpty ? contentLength - 1 : (Int64(pieces[1]) ?? contentLength - 1)
return HTTPByteRange(start: start, end: min(end, contentLength - 1))
}
private static func testRangeProbeFallsBackWhenServerIgnoresRange() async {
MockURLProtocol.handler = { request in
if request.httpMethod == "HEAD" {

Related issues or PRs

Related to Beads issue dreamio-meh and branch lavender/vlc-local-range-cache.

+
+

New Changes as of May 26, 2026 at 12:00 PM EDT

+

Summary of changes

+

Matroska-family streams now bypass the local progressive range cache and open through direct MobileVLCKit playback. This targets a startup buffering regression seen with Torrentio Real-Debrid .mkv streams, where VLC asked the loopback cache for both header bytes and far-tail index bytes before normal playback could settle.

+

Why this change was made

+

The runtime log showed opening mode=local-cache for an .mkv, followed by repeated range-cache fetches around byte zero and near the file tail. Matroska containers often need tail index reads during startup, so the current 1 MB loopback cache behavior can add latency to the exact probes VLC uses to identify tracks and begin playback. Direct VLC playback was the known stable path for these streams.

+

Code diffs

+

Rendered with @pierre/diffs/ssr. The patch is intentionally small: one cache eligibility guard and one regression test.

+

Dreamio/ProgressiveHTTPRangeCache.swift

Dreamio/ProgressiveHTTPRangeCache.swift
+8
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) {
52 unmodified lines
    private func header(_ name: String, in response: HTTPURLResponse) -> String? {
        response.value(forHTTPHeaderField: name)
    }
}

+
enum HTTPRangeCacheError: Error {
271 unmodified lines
272
273
274
275
276
277
278
279
280
52 unmodified lines
333
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) {
52 unmodified lines
    private func header(_ name: String, in response: HTTPURLResponse) -> String? {
        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 {
+

Tests/StreamResolverTests.swift

Tests/StreamResolverTests.swift
+27
42 unmodified lines
43
44
45
46
47
48
491 unmodified lines
540
541
542
543
544
545
42 unmodified lines
        testRangeCacheForegroundMissFetchesAlignedChunks()
        await testRangeCacheForegroundMissReprioritizesPrefetch()
        await testRangeCacheHitFollowsActualPostSeekReadArea()
        await testRangeProbeFallsBackWhenServerIgnoresRange()
        await testRangeFetcherPreservesHeaders()
        print("StreamResolverTests passed")
491 unmodified lines
        try? await Task.sleep(nanoseconds: 50_000_000)
    }

+
    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)
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
562
563
564
565
566
567
568
569
570
571
572
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(
            url: URL(string: "https://cdn.example.test/show.mkv?token=secret")!,
            headers: [:],
            session: mockSession()
        )
        let probe = await fetcher.probe()

+
        assertEqual(probe.isCacheable, false)
        assertEqual(probe.fallbackReason, "tail-index-container")
        assertEqual(requestCount, 0)
        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

+

Related to Beads issue dreamio-816 and branch lavender/vlc-local-range-cache.

+
+