Local Seek Buffer for VLC Playback

Summary

Dreamio now starts a per-playback loopback proxy before handing a direct HTTP stream to VLC. VLC receives a localhost URL, while the proxy forwards authenticated byte-range requests upstream, stores bounded temporary chunks, serves complete range hits locally, and cleans up the cache when the native player dismisses.

Changes Made

• Added NativeStreamCacheProxy, NativeStreamCacheProxy.Session, CachedRangeStore, and HTTPRange.
• Started the proxy from NativePlayerViewController before backend.play(request:) and replaced only playbackURL with the local stream URL.
• Kept subtitle candidates and subtitle attachment untouched, so existing external subtitle URLs still flow directly to VLC.
• Added NativePlaybackRequest.withPlaybackURL(_:) to derive the VLC-facing request without rebuilding headers or metadata by hand.
• Added test coverage for range parsing, content range formatting, chunk lookup, eviction, forwarded headers, and fallback status behavior.
• Registered the new Swift source file in the Xcode project.

Context

VLC was previously opened directly on debrid or direct-file URLs. That means small seeks depended entirely on VLC and the upstream server. The new proxy gives Dreamio a narrow local buffer for HTTP/HTTPS direct-file streams without changing Stremio interception or subtitle discovery contracts.

Important Implementation Details

• The proxy listens on 127.0.0.1 using NWListener and exposes /stream/<session id>.
• Upstream requests preserve Referer, User-Agent, and all request headers from NativePlaybackRequest, plus the VLC-requested Range.
• Successful upstream 206 responses are stored as temp chunk files under FileManager.default.temporaryDirectory/DreamioNativeStreamCache/<session id>.
• Complete cache hits return 206 Partial Content with Content-Range, Content-Length, and Accept-Ranges.
• If upstream returns a non-range status such as 200, the proxy passes that body/status back and logs that instant nearby seek cannot be guaranteed.
• The current v1 uses a conservative byte budget fallback and fixed range windows. Bitrate-derived sizing is scaffolded through the session but not yet estimated from media metadata.

Relevant Diff Snippets

10 unmodified lines
11
12
13
14
15
16
120 unmodified lines
137
138
139
140
141
142
143
48 unmodified lines
192
193
194
195
196
197
198
199
200
10 unmodified lines
    private var attachedSubtitleURLs: Set<URL>
    private var audioMenuSignature: String?
    private var captionsMenuSignature: String?
    var onDismiss: (() -> Void)?

    private let loadingView: UIActivityIndicatorView = {
120 unmodified lines
        configureBackend()
        configureLayout()
        startStartupTimer()
        backend.play(request: request)
        addSubtitleCandidates(request.subtitleCandidates)
    }

48 unmodified lines
        controlsTimer?.invalidate()
        progressTimer?.invalidate()
        backend.stop()
        onDismiss?()
    }

    private func resolveSubtitleCandidates(_ candidates: [SubtitleCandidate]) async -> [SubtitleCandidate] {
        var resolved: [SubtitleCandidate] = []
        for candidate in candidates {
10 unmodified lines
11
12
13
14
15
16
17
120 unmodified lines
138
139
140
141
142
143
144
145
48 unmodified lines
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
10 unmodified lines
    private var attachedSubtitleURLs: Set<URL>
    private var audioMenuSignature: String?
    private var captionsMenuSignature: String?
    private var streamCacheProxy: NativeStreamCacheProxy?
    var onDismiss: (() -> Void)?

    private let loadingView: UIActivityIndicatorView = {
120 unmodified lines
        configureBackend()
        configureLayout()
        startStartupTimer()
        let playbackRequest = startProxyPlaybackRequest(for: request)
        backend.play(request: playbackRequest)
        addSubtitleCandidates(request.subtitleCandidates)
    }

48 unmodified lines
        controlsTimer?.invalidate()
        progressTimer?.invalidate()
        backend.stop()
        streamCacheProxy?.stop()
        streamCacheProxy = nil
        onDismiss?()
    }

    private func startProxyPlaybackRequest(for request: NativePlaybackRequest) -> NativePlaybackRequest {
        guard request.playbackURL.scheme?.lowercased().hasPrefix("http") == true else {
            return request
        }
        let proxy = NativeStreamCacheProxy(session: NativeStreamCacheProxy.Session(request: request))
        do {
            let proxyURL = try proxy.start()
            streamCacheProxy = proxy
            return request.withPlaybackURL(proxyURL)
        } catch {
#if DEBUG
            print("[DreamioStreamProxy] start-failed error=\(error.localizedDescription)")
#endif
            return request
        }
    }

    private func resolveSubtitleCandidates(_ candidates: [SubtitleCandidate]) async -> [SubtitleCandidate] {
        var resolved: [SubtitleCandidate] = []
        for candidate in candidates {

26 unmodified lines
27
28
29
30
31
32
26 unmodified lines
    let headers: [String: String]
    let classification: StreamClassification
    let subtitleCandidates: [SubtitleCandidate]
}

struct SubtitleCandidate: Equatable {
26 unmodified lines
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
26 unmodified lines
    let headers: [String: String]
    let classification: StreamClassification
    let subtitleCandidates: [SubtitleCandidate]

    func withPlaybackURL(_ playbackURL: URL) -> NativePlaybackRequest {
        NativePlaybackRequest(
            playbackURL: playbackURL,
            observedURL: observedURL,
            resolverURL: resolverURL,
            pageURL: pageURL,
            userAgent: userAgent,
            referer: referer,
            headers: headers,
            classification: classification,
            subtitleCandidates: subtitleCandidates
        )
    }
}

struct SubtitleCandidate: Equatable {

23 unmodified lines
24
25
26
27
28
29
10 unmodified lines
40
41
42
43
44
45
23 unmodified lines
        testSubtitleDisplayNameNormalization()
        testSubtitleDisplayNameUsesPreservedNamesForGenericVLCTracks()
        testSubtitleOptionMappingIncludesNone()
        print("StreamResolverTests passed")
    }

10 unmodified lines
        assertEqual(request.headers["User-Agent"], "DreamioTest/1")
    }

    private static func testResolverSelectsUnsupportedDirectURLAndHeaders() {
        let payload: [String: Any] = [
            "streams": [
23 unmodified lines
24
25
26
27
28
29
30
31
32
33
34
35
10 unmodified lines
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
23 unmodified lines
        testSubtitleDisplayNameNormalization()
        testSubtitleDisplayNameUsesPreservedNamesForGenericVLCTracks()
        testSubtitleOptionMappingIncludesNone()
        testHTTPRangeParsing()
        testContentRangeFormatting()
        testCacheLookupAcrossChunkBoundaries()
        testCacheEvictionOutsideByteBudget()
        testProxyForwardsUpstreamHeaders()
        testProxyPassThroughFallbackStatus()
        print("StreamResolverTests passed")
    }

10 unmodified lines
        assertEqual(request.headers["User-Agent"], "DreamioTest/1")
    }

    private static func testHTTPRangeParsing() {
        assertEqual(HTTPRange.parse("bytes=10-20"), HTTPRange(start: 10, end: 20))
        assertEqual(HTTPRange.parse("bytes=10-"), HTTPRange(start: 10, end: nil))
        assert(HTTPRange.parse("items=10-20") == nil, "Expected non-byte range to be rejected")
        assert(HTTPRange.parse("bytes=-20") == nil, "Expected suffix ranges to be rejected for v1")
        assert(HTTPRange.parse("bytes=20-10") == nil, "Expected inverted ranges to be rejected")
        assert(HTTPRange.parse("bytes=1-2,3-4") == nil, "Expected multipart ranges to be rejected")
    }

    private static func testContentRangeFormatting() {
        assertEqual(HTTPRange.contentRange(start: 10, end: 20, totalLength: 100), "bytes 10-20/100")
        assertEqual(HTTPRange.contentRange(start: 10, end: 20, totalLength: nil), "bytes 10-20/*")
    }

    private static func testCacheLookupAcrossChunkBoundaries() {
        let store = CachedRangeStore(sessionID: "test-\(UUID().uuidString)", byteBudget: 1024)
        defer { store.removeAll() }
        store.store(data: Data("abc".utf8), start: 0)
        store.store(data: Data("def".utf8), start: 3)

        let lookup = store.lookup(range: HTTPRange(start: 0, end: 5), maximumLength: 6)

        assertEqual(String(data: lookup?.data ?? Data(), encoding: .utf8), "abcdef")
        assertEqual(lookup?.isComplete, true)
    }

    private static func testCacheEvictionOutsideByteBudget() {
        let store = CachedRangeStore(sessionID: "test-\(UUID().uuidString)", byteBudget: 6)
        defer { store.removeAll() }
        store.store(data: Data("abcdef".utf8), start: 0)
        store.store(data: Data("ghijkl".utf8), start: 6)

        let oldLookup = store.lookup(range: HTTPRange(start: 0, end: 5), maximumLength: 6)
        let newLookup = store.lookup(range: HTTPRange(start: 6, end: 11), maximumLength: 6)

        assert(oldLookup == nil, "Expected old chunk to be evicted outside the byte budget")
        assertEqual(String(data: newLookup?.data ?? Data(), encoding: .utf8), "ghijkl")
    }

    private static func testProxyForwardsUpstreamHeaders() {
        let proxy = NativeStreamCacheProxy(session: NativeStreamCacheProxy.Session(request: proxyTestRequest()))
        let upstreamRequest = proxy.upstreamRequest(for: HTTPRange(start: 12, end: 34))

        assertEqual(upstreamRequest.value(forHTTPHeaderField: "Range"), "bytes=12-34")
        assertEqual(upstreamRequest.value(forHTTPHeaderField: "Referer"), "https://resolver.example.test/")
        assertEqual(upstreamRequest.value(forHTTPHeaderField: "User-Agent"), "DreamioTest/1")
        assertEqual(upstreamRequest.value(forHTTPHeaderField: "Authorization"), "Bearer secret")
    }

    private static func testProxyPassThroughFallbackStatus() {
        assertEqual(NativeStreamCacheProxy.responseStatusForUpstreamStatus(206), 206)
        assertEqual(NativeStreamCacheProxy.responseStatusForUpstreamStatus(200), 200)
    }

    private static func proxyTestRequest() -> NativePlaybackRequest {
        NativePlaybackRequest(
            playbackURL: URL(string: "https://cdn.example.test/movie.mkv")!,
            observedURL: URL(string: "https://cdn.example.test/movie.mkv")!,
            resolverURL: URL(string: "https://resolver.example.test/play")!,
            pageURL: nil,
            userAgent: "DreamioTest/1",
            referer: "https://resolver.example.test/",
            headers: [
                "Referer": "https://resolver.example.test/",
                "User-Agent": "DreamioTest/1",
                "Authorization": "Bearer secret"
            ],
            classification: StreamClassification(
                sourceKind: .directFile,
                containerGuess: .mkv,
                reason: "test",
                shouldIntercept: true,
                sanitizedObservedURL: "https://cdn.example.test/movie.mkv",
                sanitizedResolverURL: nil
            ),
            subtitleCandidates: []
        )
    }

    private static func testResolverSelectsUnsupportedDirectURLAndHeaders() {
        let payload: [String: Any] = [
            "streams": [

14 unmodified lines
15
16
17
18
19
20
21
7 unmodified lines
29
30
31
32
33
34
4 unmodified lines
39
40
41
42
43
44
46 unmodified lines
91
92
93
94
95
96
140 unmodified lines
237
238
239
240
241
242
14 unmodified lines
		6F2A2B442C00100100DREAMIO /* VLCNativePlaybackBackend.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */; };
		6F2A2B452C00100100DREAMIO /* NativePlayerViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */; };
		6F2A2B502C00100100DREAMIO /* StreamResolver.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B512C00100100DREAMIO /* StreamResolver.swift */; };
		BA013CEC876B829A86AE8DCB /* Pods_Dreamio.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 908FA15B08AB341C116BAB46 /* Pods_Dreamio.framework */; };
/* End PBXBuildFile section */
/* Begin PBXFileReference section */
7 unmodified lines
		6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VLCNativePlaybackBackend.swift; sourceTree = "<group>"; };
		6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativePlayerViewController.swift; sourceTree = "<group>"; };
		6F2A2B512C00100100DREAMIO /* StreamResolver.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StreamResolver.swift; sourceTree = "<group>"; };
		701702B9C2BFBEDE36E7F0A3 /* Pods-Dreamio.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Dreamio.release.xcconfig"; path = "Target Support Files/Pods-Dreamio/Pods-Dreamio.release.xcconfig"; sourceTree = "<group>"; };
		908FA15B08AB341C116BAB46 /* Pods_Dreamio.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Dreamio.framework; sourceTree = BUILT_PRODUCTS_DIR; };
		BF0A4D5BAC9400AEEF3B0181 /* Pods-Dreamio.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Dreamio.debug.xcconfig"; path = "Target Support Files/Pods-Dreamio/Pods-Dreamio.debug.xcconfig"; sourceTree = "<group>"; };
4 unmodified lines
			isa = PBXFrameworksBuildPhase;
			buildActionMask = 2147483647;
			files = (
			);
			runOnlyForDeploymentPostprocessing = 0;
		};
46 unmodified lines
				6F2A2B512C00100100DREAMIO /* StreamResolver.swift */,
				6F2A2B472C00100100DREAMIO /* NativePlaybackBackend.swift */,
				6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */,
				6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */,
				6F2A2B392C00100100DREAMIO /* Info.plist */,
			);
140 unmodified lines
				6F2A2B502C00100100DREAMIO /* StreamResolver.swift in Sources */,
				6F2A2B432C00100100DREAMIO /* NativePlaybackBackend.swift in Sources */,
				6F2A2B442C00100100DREAMIO /* VLCNativePlaybackBackend.swift in Sources */,
				6F2A2B452C00100100DREAMIO /* NativePlayerViewController.swift in Sources */,
			);
			runOnlyForDeploymentPostprocessing = 0;
14 unmodified lines
15
16
17
18
19
20
21
22
7 unmodified lines
30
31
32
33
34
35
36
4 unmodified lines
41
42
43
44
45
46
47
46 unmodified lines
94
95
96
97
98
99
100
140 unmodified lines
241
242
243
244
245
246
247
14 unmodified lines
		6F2A2B442C00100100DREAMIO /* VLCNativePlaybackBackend.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */; };
		6F2A2B452C00100100DREAMIO /* NativePlayerViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */; };
		6F2A2B502C00100100DREAMIO /* StreamResolver.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B512C00100100DREAMIO /* StreamResolver.swift */; };
		6F2A2B522C00100100DREAMIO /* NativeStreamCacheProxy.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6F2A2B532C00100100DREAMIO /* NativeStreamCacheProxy.swift */; };
		B6C42C187A771A50D200AD84 /* Pods_Dreamio.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 908FA15B08AB341C116BAB46 /* Pods_Dreamio.framework */; };
/* End PBXBuildFile section */
/* Begin PBXFileReference section */
7 unmodified lines
		6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VLCNativePlaybackBackend.swift; sourceTree = "<group>"; };
		6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativePlayerViewController.swift; sourceTree = "<group>"; };
		6F2A2B512C00100100DREAMIO /* StreamResolver.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StreamResolver.swift; sourceTree = "<group>"; };
		6F2A2B532C00100100DREAMIO /* NativeStreamCacheProxy.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = NativeStreamCacheProxy.swift; sourceTree = "<group>"; };
		701702B9C2BFBEDE36E7F0A3 /* Pods-Dreamio.release.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Dreamio.release.xcconfig"; path = "Target Support Files/Pods-Dreamio/Pods-Dreamio.release.xcconfig"; sourceTree = "<group>"; };
		908FA15B08AB341C116BAB46 /* Pods_Dreamio.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = Pods_Dreamio.framework; sourceTree = BUILT_PRODUCTS_DIR; };
		BF0A4D5BAC9400AEEF3B0181 /* Pods-Dreamio.debug.xcconfig */ = {isa = PBXFileReference; includeInIndex = 1; lastKnownFileType = text.xcconfig; name = "Pods-Dreamio.debug.xcconfig"; path = "Target Support Files/Pods-Dreamio/Pods-Dreamio.debug.xcconfig"; sourceTree = "<group>"; };
4 unmodified lines
			isa = PBXFrameworksBuildPhase;
			buildActionMask = 2147483647;
			files = (
				B6C42C187A771A50D200AD84 /* Pods_Dreamio.framework in Frameworks */,
			);
			runOnlyForDeploymentPostprocessing = 0;
		};
46 unmodified lines
				6F2A2B512C00100100DREAMIO /* StreamResolver.swift */,
				6F2A2B472C00100100DREAMIO /* NativePlaybackBackend.swift */,
				6F2A2B482C00100100DREAMIO /* VLCNativePlaybackBackend.swift */,
				6F2A2B532C00100100DREAMIO /* NativeStreamCacheProxy.swift */,
				6F2A2B492C00100100DREAMIO /* NativePlayerViewController.swift */,
				6F2A2B392C00100100DREAMIO /* Info.plist */,
			);
140 unmodified lines
				6F2A2B502C00100100DREAMIO /* StreamResolver.swift in Sources */,
				6F2A2B432C00100100DREAMIO /* NativePlaybackBackend.swift in Sources */,
				6F2A2B442C00100100DREAMIO /* VLCNativePlaybackBackend.swift in Sources */,
				6F2A2B522C00100100DREAMIO /* NativeStreamCacheProxy.swift in Sources */,
				6F2A2B452C00100100DREAMIO /* NativePlayerViewController.swift in Sources */,
			);
			runOnlyForDeploymentPostprocessing = 0;

Expected Impact for End-Users

Short backward jumps should be more likely to resume quickly once playback has warmed the rolling cache. Short forward jumps can benefit from read-ahead when upstream speed allows. Seeking outside the retained window still falls back to upstream range fetching instead of wedging the player.

Validation

• Passed: swiftc -parse-as-library Dreamio/StreamCandidate.swift Dreamio/StreamResolver.swift Dreamio/NativeStreamCacheProxy.swift Tests/StreamResolverTests.swift -o /tmp/dreamio-stream-resolver-tests && /tmp/dreamio-stream-resolver-tests.
• Passed after dependency setup: DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -workspace Dreamio.xcworkspace -scheme Dreamio -configuration Debug -sdk iphonesimulator build.
• Setup note: the first build failed because local CocoaPods support files were missing. I ran pod install, which restored untracked local Pods/ contents without changing tracked project files, then reran the build successfully.
• Not performed: manual device validation with a real debrid stream was not available in this environment.

Issues, Limitations, and Mitigations

• v1 targets direct-file HTTP/HTTPS streams, not HLS playlists.
• The proxy only guarantees bytes it has actually fetched and retained. It cannot instantly serve unwatched earlier offsets.
• Forward read-ahead is best effort and bounded; slow upstream servers can still buffer.
• Upstream servers that ignore byte ranges fall back to pass-through, with debug logging to explain why local seeks are not guaranteed.
• The current listener implementation is intentionally small and should be stress-tested on device before widening the cache window or range concurrency.

Follow-up Work

• Create a device validation issue for real debrid MKV/MP4 seek behavior across short back, short forward, and far seeks.
• Estimate bitrate from duration/content length when available so the default cache window can more closely mean 30 seconds of media.
• Stream upstream range responses incrementally instead of buffering the whole fetched slice before replying.
• Add structured DEBUG counters for hit ratio, evictions, and upstream range latency.