Note (2025-12-15): This README documents the legacy Backbone.js codebase. The app has been completely rewritten to Svelte 5. See CURRENT-STATUS.md for the current architecture and status.
A modern, mobile-first streaming app built with Capacitor and native torrent support.
Status: Phase 10.4 - Production Testing Version: 2.0.0 (Svelte 5 Rewrite) Last Updated: 2025-12-15
📖 Complete Documentation Index - Navigate all 14 docs + 6 automation scripts
- 🎬 Stream movies, TV shows, anime, and educational content
- ⚡ Native P2P torrent streaming via jlibtorrent
- 📁 Library folder picker with SAF (Storage Access Framework)
- 🎵 Automatic subtitle detection (.srt, .vtt, .sub, .ass, .ssa)
- 📼 Multi-file torrent sequence playback with auto-next
- ⭐ File-level favorites for multi-file torrents
- 🔄 Video switching bug fixes with request tracking
- 📚 Torrent Collections with cloud sync (Phase 13)
- ☁️ Cloud Sync for favorites, settings, and collections (Phase 12B)
- 🎯 Picture-in-Picture mode
- 🔗 Deep linking support (magnet:// URIs)
- 📱 Mobile-first responsive design with Tailwind CSS
- 🌙 Dark mode with theme persistence
- 🎨 Modern component-based styling (35.10 kB CSS, 6.17 kB gzipped)
- 👆 Touch-friendly (44x44px minimum tap targets)
- 📐 Safe area insets for notch/rounded corner support
- 💫 Smooth animations and pull-to-refresh
- ✅ TypeScript strict mode (ZERO errors)
- 🎯 Full type safety throughout codebase
- 🚀 89.8% bundle reduction (697KB → 71KB main bundle, Phase 12A)
- ⚡ 15+ code chunks with lazy loading and dynamic imports
- 🔌 15 Capacitor plugins integrated (Network, Share, Filesystem, etc.)
- 🔗 Deep linking support (flixcapacitor://, magnet://)
- 🧹 Proper cleanup on app exit/pause
- 📊 Production monitoring (Sentry crash reporting)
- 🔒 ProGuard optimization for release builds
Current Stack (v2.0.0 - Svelte 5):
- Framework: Svelte 5 with Runes ($state, $derived, $effect)
- Router: SvelteKit with static adapter
- UI Library: Konsta UI (iOS/Material Design)
- CSS Framework: Tailwind CSS 3.x
- Build Tool: Vite 6.x
- Platform: Capacitor 7.x (web → native Android)
- Torrent Engine: jlibtorrent 2.0.11 (native Android via custom plugin)
- Database: SQLite (via @capacitor-community/sqlite)
- HTTP Streaming: NanoHTTPD server with dynamic port allocation
- Runtime: Android 11+ (API level 30+)
- Node.js 18+
- Android SDK
- Java 17
- Gradle 8.x
# Install dependencies
npm install
# Build and install APK (recommended - handles web build, sync, and installation)
./build-and-install.sh
# Or clean build
./build-and-install.sh cleanNote: The build-and-install.sh script handles the complete build pipeline:
- Web asset build (
npm run build) - Capacitor sync (
npx cap sync android) - Gradle build with custom ARM64 AAPT2
- Multi-tier APK installation (termux-open → ADB wireless → manual copy)
Manual build (if needed):
npm run build
npx cap sync android
cd android && ./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk# Start dev server
npm run dev
# Type checking (TypeScript strict mode)
npm run typecheck
# Build for production
npm run build
# Preview production build
npm run previewcapacitor-plugin-torrent-streamer: Custom Capacitor plugin wrapping jlibtorrentTorrentStreamingService: Background Android service managing torrent lifecycleStreamingServer: Local HTTP server (NanoHTTPD) with dynamic port allocation- Stream URL format:
http://127.0.0.1:<dynamic-port>/video(e.g.,http://127.0.0.1:52413/video) - Each server instance gets OS-assigned ephemeral port (49152-65535)
- Torrents:
/sdcard/Android/data/app.flixcapacitor.mobile/files/Movies/FlixCapacitor/ - Logs:
/sdcard/Android/data/app.flixcapacitor.mobile/files/Documents/FlixCapacitor/log.txt - Uses Android scoped storage (no special permissions required)
- Automatic fallback if in-app HTML5 player fails
- Supports VLC, MX Player, and any video player app
- Uses Android
Intent.ACTION_VIEWwith chooser dialog - Stream continues in background
src/app/lib/mobile-ui.js: Main UI controllersrc/app/lib/mobile-ui-views.js: Video player and loading screenssrc/app/lib/native-torrent-client.js: Native plugin wrapper
capacitor-plugin-torrent-streamer/android/: Native Kotlin/Java codeTorrentSession.kt: Torrent lifecycle managementTorrentStreamingService.kt: Background service + HTTP serverLogHelper.kt: Centralized logging utility
- Feature: Organize torrents into custom collections with cloud sync
- Implementation: 3,775 lines of code across 10 commits
- Components:
- TorrentsService (12 methods, torrent persistence)
- CollectionsService (15 methods, CRUD operations)
- CollectionSyncService (10 methods, Last Write Wins conflict resolution)
- Collection list view with grid layout
- Collection detail view with torrent reordering
- "Add to Collection" integration in movie detail view
- Network-aware auto-sync (@capacitor/network plugin)
- UI: Blue theme for collections (distinguishes from favorites)
- Status: 100% complete (5 days, Phase 1 MVP + Phase 2 Integration)
- Status: 98% complete - All autonomous work done (Session 8: UI fixes + GitHub Pages)
- Completed:
- Release build config: Keystore (RSA 2048-bit, valid until 2053), ProGuard (232 lines), signing
- Play Store assets: App icon (512x512px, 39K), feature graphic (1024x500px, 47K)
- Play Store listing complete (title, description, metadata - PLAY-STORE-LISTING.md)
- Legal compliance: Privacy Policy + Terms HTML hosted (privacy.html 25K, terms.html 23K)
- Hosting infrastructure: 4 deployment options (GitHub Pages recommended, 5 min)
- Beta testing framework: 3-phase plan (874 lines), 80+ test cases
- Rollout strategy: 5-stage plan (924 lines), 3-week timeline
- Production monitoring: Sentry crash reporting + analytics configured
- Complete documentation: ~6,500+ lines across 15+ guides
- Pending: 8 phone screenshots (manual device work, 1-2 hours), release build testing
- Documentation: PHASE-12E-COMPLETION-SUMMARY.md (692 lines)
- Achievement: 89.8% bundle size reduction (697KB → 71KB main bundle)
- Techniques: Dynamic imports, lazy loading, code splitting
- Result: 15+ separate chunks, 50.2% gzipped transfer reduction
- Impact: Initial load reduced from 697KB to 315KB (main + vendor)
- Backend: Supabase cloud sync (optional, opt-in)
- Features: Favorites sync, settings backup, collection sharing
- Authentication: Email, Google, Apple (via Supabase Auth)
- Conflict Resolution: Last Write Wins (LWW) strategy
- Architecture: Offline-first, sync on network restore
- Volume: 10,850+ lines of comprehensive documentation
- Files: API.md, ARCHITECTURE.md, USER-GUIDE.md, CONTRIBUTING.md
- Coverage: All services, features, and development workflows
- Fixed "plugin is not implemented on android" error in Library tab
- Changed to lazy initialization using Kotlin's
by lazydelegate - Ensures Capacitor bridge is ready before plugin registration
- Automated testing: APK installed, app launched, no errors in logcat
- Fixed file picker timing issue causing wrong video to play
- Added request tracking to prevent race conditions during rapid switching
- Restructured multi-file flow: start→metadata→stop→pick→select→restart
- File picker now shows BEFORE playback begins
- Converted entire codebase to TypeScript strict mode
- ZERO TypeScript errors across all 50+ source files
- Full type safety for mobile UI, video player, torrent client, and all providers
- Enhanced code quality and maintainability
- Migrated from custom CSS to Tailwind CSS utility classes
- Production bundle: 35.10 kB (6.17 kB gzipped) - 30% under 50KB target
- Mobile-first responsive design with dark mode
- Touch-friendly tap targets (44x44px minimum)
- Seamless fallback to VLC/MX Player when HTML5 player fails
- Green button UI with clear error messaging
- Stream URL display for manual copying
- Problem: Hardcoded port 8888 caused
BindExceptioncrashes on app restart - Solution: Dynamic port allocation using port 0 parameter (OS-assigned ephemeral ports)
- Benefits: No restart crashes, supports multiple simultaneous servers, zero configuration
- Implementation:
NanoHTTPD("127.0.0.1", 0)→ OS assigns unique port automatically - Identified by: Gemini 2.5 Pro code review
- Test Coverage: 26 passing JUnit tests validate both CRITICAL bug fixes
- See:
NATIVE-TORRENT-STREAMING.mdv1.1.0 for complete technical details
- Architectural solution: never store
TorrentHandle - Store
Sha1Hashand fetch fresh handles from SessionManager - Prevents all JNI staleness crashes
- Symptom: "Timeout: Failed to receive torrent metadata after 90 seconds"
- Causes: Mobile carrier blocking torrent traffic, firewall, or no seeds
- Solutions: Use WiFi, try popular torrents, check firewall, or use VPN
-
Screenshot Capture (1-2 hours)
- Capture 8 phone screenshots on Android device
- URLs and guide available in
SCREENSHOT-URLS.md - Dev server running at
http://localhost:3000/
-
Release Build Testing (4-6 hours)
- Build release APK with ProGuard
- Test all features on physical device
- Verify ProGuard doesn't break functionality
-
Play Store Submission (1-2 hours)
- Upload all assets to Play Console
- Preview listing and submit for review
- Manual QA testing (7-10 days)
- Multi-device cloud sync testing
- Accessibility audit (TalkBack)
- Beta testing (10-20 users)
- Staged rollout (10% → 25% → 50% → 100%)
Current Production Readiness: 98%
For comprehensive guides, see:
- PROJECT-STATUS.md - Overall project status and metrics
- PLAY-STORE-LISTING.md - Complete Play Store listing
- PLAY-STORE-ASSETS.md - Asset specifications
- BUILD-RELEASE.md - Release build instructions
- docs/ - 10,850+ lines of comprehensive documentation
This is a personal project. Feel free to fork and modify.
ISC
Built on top of open-source technologies: