mirror of
https://github.com/tapframe/NuvioStreaming.git
synced 2026-05-19 08:22:00 +00:00
97 lines
4.7 KiB
Markdown
97 lines
4.7 KiB
Markdown
# 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
|