NuvioStreaming/docs/IOS_TORRENT_ENGINE_PATH.md

iOS Torrent Engine Path (Native, Not Desktop Service Port)

Goal

Enable native torrent playback on iOS/iPadOS/tvOS with the same JS contract already used on Android:

• prepareStream({ magnetUri, streamTitle, fileIndex, trackers, networkMbps })
• stopStream(streamId)
• stopAllStreams()

The player receives a local playback URL such as http://127.0.0.1:<port>/torrent/<streamId>.

Why Not Port Desktop Stremio Service

• stremio-shell is a desktop shell that starts a separate streaming server process in production.
• stremio-service packaging targets desktop distributions (macOS dmg, Windows exe, Linux deb/rpm/flatpak).
• iOS needs an embedded native engine lifecycle (memory/background constraints), not a desktop-style sidecar service process.

Research Snapshot (2026-02-19)

Torrent Core Candidates

• arvidn/libtorrent: mature BitTorrent core, highly active, strongest long-term choice.
• frostwire/frostwire-jlibtorrent: excellent for Android/JVM, but not a native Swift/iOS API surface.

iOS Client/Engine References

• XITRIX/iTorrent: active iOS torrent app; uses libtorrent-rasterbar and local HTTP playback bridging.
• XITRIX/LibTorrent-Swift: active Swift wrapper project used by iTorrent.
• danylokos/SwiftyTorrent: useful reference implementation, but older push cadence and Carthage-era stack.
• siuying/peerflix-ios: archived and stale for modern production use.

Local HTTP Bridge Candidates

• swisspol/GCDWebServer: historically common, but archived.
• swhitty/FlyingFox: active, modern Swift Concurrency HTTP server with range request support.

Requested Check: VLC BitTorrent

• johang/vlc-bittorrent is a VLC plugin (C/C++ plugin target), useful as concept/reference, but not a direct iOS-native app integration path for Nuvio’s React Native architecture.

Decision

Use:

1. libtorrent-rasterbar as the iOS/tvOS torrent core.
2. A thin Swift bridge layer (TorrentStreamingModule) exposing Nuvio’s existing JS API.
3. A local HTTP range bridge based on FlyingFox (preferred) or a custom equivalent if tighter control is needed.

Avoid:

• Desktop stremio-service process porting.
• Archived HTTP server dependencies as primary infrastructure.
• iOS torrent clients as direct code imports; use them as implementation references only.

Target iOS Architecture

1. TorrentSessionActor

• Owns libtorrent session lifecycle, torrent handles, and shutdown.

2. TorrentStreamCoordinator

• File selection, piece windowing, and seek-aware reprioritization.
• Network-aware prefetch profile (slow/medium/fast/ultra), matching Android strategy.

3. LocalPlaybackServer

• Serves /torrent/{streamId} with full Range support (206, Content-Range, Accept-Ranges).
• Keeps buffered reads aggressive during play/pause up to cache policy limits.

4. TorrentStreamingModule (RN bridge)

• prepareStream, stopStream, stopAllStreams.
• Returns { streamId, playbackUrl, infoHash, fileName, fileSize, mimeType }.

Buffering/Robustness Rules

• Keep forward prefetch active during pause (subject to thermal/memory policy).
• Maintain high-priority piece window around playback pointer and seek target.
• Keep a wider low-priority prefetch window for smoother long-form playback.
• Resume quickly after app foreground/background transitions.
• Treat near-tail transient I/O failures as graceful completion when safe.

Disk/Cache Policy

• Configurable base cache directory (default app container cache).
• Per-infohash subfolders.
• LRU cleanup and max cache budget.
• Optional “keep completed file” mode off by default.

Integration Status In This Branch

• JS service already supports native torrent module discovery on Android/iOS.
• Stream selection now uses capability checks instead of Android-only assumptions.
• KSPlayerCore carries torrentStreamId and performs stop on close/unmount/switch.
• Android torrent prefetch is now network-tuned (very-slow to ultra-fast profiles).

Remaining iOS Work

1. Implement and register TorrentStreamingModule on iOS.
2. Integrate libtorrent-rasterbar (XCFramework/static linkage path).
3. Implement local HTTP range bridge and seek-aware scheduler.
4. Add settings UI for cache path + cache budget.
5. Validate on real devices: pause buffering, seek storms, tokenized links, EOS behavior.

Primary References

• https://github.com/Stremio/stremio-shell
• https://github.com/Stremio/stremio-service
• https://github.com/arvidn/libtorrent
• https://github.com/XITRIX/iTorrent
• https://github.com/XITRIX/LibTorrent-Swift
• https://github.com/danylokos/SwiftyTorrent
• https://github.com/siuying/peerflix-ios
• https://github.com/swhitty/FlyingFox
• https://github.com/swisspol/GCDWebServer
• https://github.com/johang/vlc-bittorrent