PlayTorrio V3

PlayTorrio V3 is a Flutter-powered universal media hub that aggregates streaming content from the open web, torrent networks, and Stremio-compatible addons into a single, beautifully designed interface. Browse catalogs from community addons. Stream movies and TV shows via direct VOD links or native BitTorrent with libtorrent. Read manga chapter-by-chapter with progress tracking. Listen to audiobooks streamed from torrents or nine independent sources. Play music through the Octave streaming API with full playlist and library management. Download subtitles on-demand from Subdl. From the hero carousel to the final credits — one app, every format, zero subscriptions.

9 VOD Scrapers  ·  Torrent Streaming Engine  ·  Stremio Addon Protocol  ·  9 Audiobook Sources  ·  Manga Reader  ·  Music Streaming
Subtitle Download  ·  Glassmorphism UI  ·  5-Platform Support  ·  Responsive Layout  ·  Progress Persistence

Movies: Stremio addon catalogs >> 9 VOD scrapers + torrent streaming >> subtitle download.
Manga: WeebCentral browsing >> chapter reader with zoom >> persistent progress.
Audiobooks: 9-source aggregation >> torrent or direct stream >> sleep timer.
Music: Octave API >> full library management >> playlist + queue system.

Who Is This For?  ·  Quick Start  ·  Architecture  ·  Movie & TV  ·  VOD Scrapers  ·  Torrent Engine  ·  Addon System  ·  Manga  ·  Audiobooks  ·  Music  ·  Subtitles  ·  UI & Design  ·  Platforms  ·  Structure  ·  Configuration  ·  Maintainers

LEGAL DISCLAIMER: PlayTorrio V3 is an aggregator and media player. It does not host, store, or distribute copyrighted content. All content is sourced from publicly available third-party services, community addons, and user-provided sources. Users are solely responsible for ensuring they have the legal right to access content in their jurisdiction. This software is provided for educational and research purposes. The developers do not endorse piracy or copyright infringement.

git clone https://github.com/ayman708-UX/PlayTorrioV3.git
cd PlayTorrioV3
flutter pub get
flutter run

On first launch, the app automatically installs the default Cinemeta addon and initializes the torrent streaming engine. No additional configuration is required to start browsing.

graph TB
    subgraph "UI Layer — pages/"
        HOME[HomePage<br/>Hero + Sections]
        DETAILS[DetailsPage<br/>Metadata + Episodes]
        WATCH[WatchScreen<br/>Stream Selection]
        PLAYER[PlayerScreen<br/>Video Playback]
        SEARCH[SearchPage<br/>Debounced Search]
        CATALOG[CatalogPage<br/>Infinite Scroll]
        SETTINGS[SettingsPage<br/>Addons + Glass Toggle]
    end
    subgraph "Content Domains"
        MANGA_UI[MangaPage<br/>Discovery + Continue Reading]
        MANGA_READER[MangaReaderPage<br/>Horizontal/Vertical + Zoom]
        AUDIOBOOK_UI[AudiobooksPage<br/>Search + Continue Listening]
        AUDIOBOOK_PLAYER[AudiobookPlayerScreen<br/>Torrent/Direct + Timer]
        MUSIC_UI[MusicPage<br/>Home/Search/Browse/Library]
    end
    subgraph "Service Layer — services/"
        ADDON[AddonManager<br/>Singleton Orchestrator]
        STREAM[StreamService<br/>Aggregates All Sources]
        TORRENT[TorrentStreamService<br/>libtorrent Engine]
        SCRAPER[ScraperManager<br/>9 Pluggable Scrapers]
        METADATA[MetadataService<br/>Stremio HTTP Client]
        MANGA_SVC[MangaService<br/>WeebCentral Scraper]
        AUDIO_SVC[AudiobookScraperService<br/>9-Source Aggregator]
        MUSIC_SVC[OctaveMusicService<br/>Streaming API]
        SUBTITLE[SubtitleService<br/>Subdl Provider]
        BEST[BestSimilarScraper<br/>Recommendations]
    end
    subgraph "External"
        STREMIO[Stremio Addons<br/>Community Catalogs]
        VOD[VOD Sources<br/>VidSrc, FlyStream, etc.]
        DHT[BitTorrent DHT<br/>Peer-to-Peer]
        OCTAVE[Octave API<br/>Music Streaming]
        WEEB[WeebCentral<br/>Manga Database]
        WP[WordPress Sites<br/>Audiobook Hosts]
        ABBAY[AudiobookBay<br/>Torrent Index]
    end
    HOME --> DETAILS --> WATCH --> PLAYER
    HOME --> SEARCH & CATALOG & SETTINGS
    HOME --> MANGA_UI --> MANGA_READER
    HOME --> AUDIOBOOK_UI --> AUDIOBOOK_PLAYER
    HOME --> MUSIC_UI
    ADDON --> METADATA --> STREMIO
    STREAM --> SCRAPER & ADDON
    SCRAPER --> VOD
    TORRENT --> DHT
    MANGA_SVC --> WEEB
    AUDIO_SVC --> WP & ABBAY
    MUSIC_SVC --> OCTAVE
    SUBTITLE --> SUBTITLE
    BEST --> BEST

The app is organized into three layers: UI pages that render content, a service layer that orchestrates data flow, and external sources that provide the actual media. Services are singletons — initialized once at startup, accessible anywhere. The scraper system uses a plugin architecture: each scraper extends StreamScraper and registers with the ScraperManager, which runs all scrapers concurrently and deduplicates results.

Stremio Addon Catalogs  ·  Genre Browsing  ·  Infinite Scroll  ·  Season/Episode Navigation  ·  9 VOD Scrapers  ·  Torrent Streaming  ·  "More Like This"

The movie and TV pipeline is the heart of PlayTorrio. Content discovery flows from community addon catalogs through metadata enrichment to multi-source stream aggregation — all happening concurrently so the user sees results as soon as they arrive.

Addon Catalog >> Metadata Enrichment >> Stream Aggregation >> Playback
     |                  |                       |
  Cinemeta          BestSimilar           9 Scrapers
  Community         Recommendations       Torrent DHT
  Custom URLs       Cast + Genres         Subtitle Fetch

The landing page features a hero carousel showcasing featured titles pulled from all installed addons, with intelligent deduplication to ensure visual diversity. Below the hero, horizontally scrollable sections stream in progressively as each addon returns its catalogs. Every section is labeled with catalog name, content type, and source addon. Pull-to-refresh reloads everything. A glass-bottom navigation dock provides one-tap access to Manga, Audiobooks, and Music sections.

Tapping any poster navigates to a full detail page with:

• Backdrop image with gradient overlay for readability
• Metadata header — title, year, IMDb rating, runtime, director, cast
• Expandable synopsis with animated height transition
• Genre tags rendered as tappable chips
• Cast row with horizontal scrolling
• Season selector with episode grid and quick-scroll buttons
• "More Like This" section powered by the BestSimilar recommendation engine
• Links section for external trailers, IMDb pages, and related content

The Watch Screen queries all available sources in parallel — nine built-in VOD scrapers plus every installed Stremio addon. Results stream in progressively, batched at 60ms intervals to avoid UI jank. Each stream source displays:

• Quality badge — 4K, 1080p, 720p, or 480p detected from title metadata
• Codec tag — HEVC, H.264, AV1
• HDR indicator — Dolby Vision, HDR10+, HDR
• File size — parsed and formatted from torrent metadata
• Source label — which scraper or addon provided the stream
• Type indicator — direct VOD URL or torrent magnet link

Streams are sorted by quality rank (4K > 1080p > 720p > 480p) with same-quality ties broken alphabetically. An addon filter dropdown lets users focus on specific sources. Desktop and mobile layouts adapt responsively. Tapping a stream navigates to the full-screen player via a cinematic slide transition.

The player screen is immersive and landscape-oriented. Built on video_player with fvp (FFmpeg Video Player) for broad codec support. Features include:

• Auto-hiding controls — tap to reveal, auto-dismiss after inactivity
• Subtitle overlay — load external SRT/VTT with adjustable delay and scale
• Playback speed — variable rate control
• Video fit toggle — cover, contain, fill modes
• Volume control with mute toggle
• Torrent health display — active peers, download speed, cache percentage

For torrent streams, the player shows real-time libtorrent statistics so users can monitor swarm health during playback.

9 Scrapers  ·  Plugin Architecture  ·  Concurrent Execution  ·  Automatic Deduplication  ·  Dual Providers

Each scraper is an independent module that implements a common interface. The ScraperManager runs all nine concurrently, collects results, and deduplicates by info-hash. Adding a new source is a matter of extending one abstract class and registering it.

abstract class StreamScraper {
  String get name;
  Future<List<StreamSource>> scrape({
    required String type,        // 'movie' or 'series'
    required String title,       // Exact title for matching
    required int? year,          // Release year for disambiguation
    required int? season,        // TV season number
    required int? episode,       // TV episode number
    required String? imdbId,     // IMDb ID for TMDB lookup
  });
}

Each scraper implements this interface. The ScraperManager singleton maintains a registry, runs all scrapers via Future.wait, and deduplicates results by info-hash. A TMDB helper utility resolves IMDb IDs to TMDB IDs for scrapers that need them. Results are cached with LRU eviction. Failed scrapers are silently skipped — one broken source never blocks the others.

Providers:

• PlayTorrioHTTP — Direct VOD scrapers that return HTTP/HTTPS stream URLs (m3u8, mp4)
• PlayTorrio — Torrent scrapers that return magnet links and info-hashes, which feed into the torrent streaming engine

Native libtorrent  ·  Selective File Download  ·  Intelligent File Selection  ·  Real-Time Stats  ·  HTTP Stream Output

PlayTorrio embeds a full BitTorrent client via libtorrent_flutter — native C++ libtorrent bindings compiled for each platform. Torrents are streamed sequentially: the engine prioritizes pieces needed for immediate playback while continuing to download the rest in the background.

When a multi-file torrent is loaded (common for TV season packs), the engine applies a smart selection strategy:

1. Parse all filenames using the ParseTorrentTitle utility — extract season, episode, resolution, codec, and audio metadata from raw torrent filenames
2. Match by season/episode if the user requested a specific episode — filters to files whose parsed metadata matches the target season and episode numbers
3. Filter by media extension — only considers files with video extensions: .mp4, .mkv, .avi, .webm, .mov, .wmv, .flv, .ts, .m2ts
4. Fallback to largest file — if no episode match is found, selects the largest media file by byte size (typically the full movie)
5. Return file index — passes the selected file's index to libtorrent for prioritized piece download

The engine exposes a statsStream that emits TorrentStats updates during playback:

initialize() >> start() >> streamTorrent(magnet) >> [playback] >> cleanup()
                  |              |                        |
            Configures       Adds magnet,           Removes torrent,
            libtorrent       waits metadata,        frees resources
            settings         selects file,
                             starts HTTP stream

The engine is a singleton. Multiple torrents can be active simultaneously — each keyed by its info-hash. Disposed torrent IDs are tracked to prevent double-dispose crashes. The engine properly shuts down on app termination.

Community Catalogs  ·  Metadata Enrichment  ·  Concurrent Search  ·  Relevance Scoring  ·  Progressive Loading

PlayTorrio is a fully functional Stremio client. It speaks the Stremio addon protocol natively — fetching manifests, browsing catalogs, searching content, and loading metadata from any community addon URL. The addon manager is the central orchestrator for all movie and TV content discovery.

The AddonManager is the first service initialized at startup and the backbone of content discovery:

User installs addon URL
        |
        v
AddonManager fetches /manifest.json
        |
        v
Parses AddonManifest (id, name, version, resources, catalogs, types)
        |
        v
Stores InstalledAddon (baseUrl + manifest + enabled flag)
        |
        v
On home screen load: AddonManager.fetchAllHomeSections()
        |
        v
For each addon catalog: MetadataService.fetchCatalog()
        |
        v
HTTP GET {baseUrl}/catalog/{type}/{catalogId}.json
        |
        v
Parse response into List<Movie> with poster, year, type metadata
        |
        v
Wrap in MovieSection (title, subtitle, contentType, addon source)
        |
        v
Stream to UI — each section renders as it arrives

Searches execute concurrently across all enabled addons. Each addon's results are scored by the RelevanceScorer using exact-match-first ranking:

Query: "Breaking Bad"
        |
        v
Addon 1 search >> [{title: "Breaking Bad", score: 10000}, ...]
Addon 2 search >> [{title: "Better Call Saul", score: 5000}, ...]
Addon 3 search >> [{title: "Breaking Bad S05", score: 10000}, ...]
        |
        v
Merge + Sort by score descending
        |
        v
Display sectioned by addon source

The relevance scorer strips leading articles ("the", "a", "an"), normalizes to lowercase alphanumeric, and applies tiered bonuses: exact match (10,000), substring match (5,000), prefix match (3,000). Multi-word queries are capped if not all tokens match.

The Cinemeta addon is pre-configured and installed automatically on first launch. It provides the baseline movie and series catalog. Users can add any Stremio-compatible community addon — Torrentio, Orion, KnightCrawler, self-hosted servers, or private instances — by pasting the manifest URL in Settings.

WeebCentral Integration  ·  Horizontal & Vertical Modes  ·  Pinch-to-Zoom  ·  Reading Progress  ·  Chapter Search  ·  Adult Content Toggle

A full-featured manga reading experience built on WeebCentral's web catalog. Browse, search, read, and track progress — all within the app, all persisted across sessions.

The manga page offers two browsing modes:

• Browse — infinite-scroll grid of manga covers with genre tag filtering. Content loads in pages, with smooth loading indicators between fetches.
• Search — debounced text search across WeebCentral's catalog with paginated results.

A "Continue Reading" section at the top shows your reading history — the manga you've started, sorted by most recently read, with progress indicators on each card. This section persists via SharedPreferences and survives app restarts.

Each manga has a detail page displaying:

• Hero cover image with gradient overlay transitioning to the metadata section
• Metadata — title, type (Manga/Manhwa/Manhua), status (Ongoing/Completed), year, author, tags
• Synopsis — full description parsed from WeebCentral's left sidebar layout
• Chapter list — paginated at 50 chapters per page, with page navigation controls
• Chapter search — filter chapters by number or name
• Reading progress — which chapter you last read, displayed with a visual indicator

The reader page is the core manga experience. Images load from WeebCentral's CDN (temp.compsci88.com) with caching for offline-like performance:

Reading progress is tracked with ValueNotifier<int> for reactive UI updates. Each manga's current chapter and page are stored in SharedPreferences via the MangaService. The history is capped to prevent bloat. The static cache on the manga discovery page preserves state across tab navigations — switching to Movies and back keeps your scroll position and loaded content.

9 Independent Sources  ·  Torrent & Direct Streaming  ·  Variable Speed  ·  Sleep Timer  ·  Progress Persistence  ·  Chapter Navigation

Nine audiobook sources searched in parallel, with results merged and relevance-ranked. Stream directly from WordPress-hosted audio files or torrent the full audiobook with selective chapter downloading. Every listening session is tracked and resumed exactly where you left off.

All nine sources are queried simultaneously with a 5-second timeout per source. Results are merged and sorted by relevance score:

The audiobooks page defaults to a "Harry Potter" search on first load — demonstrating the aggregation capabilities immediately. Features include:

• Search — debounced text search with relevance-scored results from all nine sources
• "Continue Listening" — horizontal carousel of in-progress audiobooks sorted by last listened timestamp
• Results grid — audiobook cards with cover art, title, source badge, and tap-to-detail navigation

Each audiobook has:

• Backdrop blur cover image with ambient background glow
• Source badge — torrent (magnet icon) or stream (play icon)
• Metadata — title, author, source information
• Chapter list — all chapters with tap-to-play. Source-specific chapter extraction (each WordPress site has unique HTML structure; AudiobookBay returns torrent file lists).

The audiobook player handles two fundamentally different streaming modes:

Direct Stream:

• Standard HTTP audio streaming from WordPress sites
• Chapter-by-chapter playback with URL-based navigation
• No download required — plays immediately

Torrent Stream:

• Magnet link resolved through the torrent engine
• Selective file downloading — the engine identifies audio files (.mp3, .m4b, .m4a, .ogg, .flac) from the torrent file list
• Chapters map to individual torrent files via file index
• Sequential streaming with piece prioritization

Player Features:

Audiobook progress is stored as a JSON-encoded list in SharedPreferences, limited to 20 entries to prevent storage bloat. Each entry records: audiobook UUID, current chapter index, playback position in seconds, and timestamp of last listen. Entries are sorted by last listened — the most recent is always at the top of "Continue Listening."

Octave Streaming API  ·  Search & Browse  ·  Library Management  ·  Playlists  ·  Quality Switching  ·  Keyboard Shortcuts  ·  Queue System

A complete music streaming experience powered by the Octave API. Browse curated sections, search across tracks/artists/albums, build playlists, like tracks, and manage a personal library — all with a persistent mini-player and full-screen playback view.

The music page uses four tabs:

The MusicPlayerController singleton manages all playback state:

The OctaveLibraryService (also a singleton ChangeNotifier) persists liked tracks and custom playlists to SharedPreferences as JSON. Operations include: toggle like, create/delete playlist, add/remove track from playlist. The library survives app restarts and is reactive — any UI listening to the service updates automatically when tracks are liked or playlists are modified.

A persistent mini-player bar sits at the bottom of the music page showing current track art, title, artist, and play/pause button. Tapping it expands to the full-screen player with:

• Album art with dominant color extraction for background ambiance
• Track info — title, artist, album
• Seek bar with elapsed/remaining time
• Transport controls — previous, play/pause, next, shuffle, repeat, like
• Queue drawer — slide-up panel showing upcoming tracks with drag-to-reorder
• Lyrics drawer — synced lyrics display (when available from Octave)
• Quality indicator — current streaming bitrate

Subdl Provider  ·  Multi-Language  ·  TV Season/Episode Matching  ·  ZIP Extraction  ·  SRT/VTT Parsing  ·  Pluggable Providers

Subtitles are fetched on-demand when entering the video player. The subtitle service queries all registered providers concurrently, groups results by language, and downloads/extracts the selected subtitle file to a local temp directory for the video player to render.

Player Screen opens
        |
        v
SubtitleService.fetchAllSubtitles(movieName, imdbId?, season?, episode?)
        |
        v
All providers queried concurrently
        |
        v
Results grouped by language >> List<SubtitleLanguageGroup>
        |
        v
User selects variant >> SubtitleService.downloadSubtitle(variant)
        |
        v
SubtitleExtractor downloads ZIP >> extracts SRT/VTT >> returns local path
        |
        v
Player loads subtitle file with delay/scale adjustment

The Subdl provider searches for subtitles by movie name and optionally filters by IMDb ID for precision. For TV shows, it matches season and episode numbers against Subdl's structured metadata. Downloaded subtitles arrive as ZIP archives and are extracted to a temporary directory. Both SRT and VTT formats are supported.

abstract class SubtitleProvider {
  Future<List<SubtitleVariant>> search({
    required String movieName,
    String? imdbId,
    int? season,
    int? episode,
  });
  
  Future<String> download(SubtitleVariant variant);
}

New subtitle providers can be added by implementing this interface and registering with the SubtitleService. The service handles concurrent queries, language grouping, and deduplication automatically.

In the video player, users can:

• Select subtitle language from the grouped list of available subtitles
• Adjust subtitle delay — shift timing forward or backward in 100ms increments
• Adjust subtitle scale — larger or smaller text rendering
• Toggle subtitles on/off during playback

Subtitles render via the native video player's text track support with the selected delay and scale applied.

Glassmorphism  ·  Liquid Glass Effects  ·  Performance Toggle  ·  Custom Route Transitions  ·  Responsive Layout  ·  macOS-Style Dock

The visual identity of PlayTorrio is built on a custom glassmorphism design system with GPU-accelerated shader effects. Every surface has depth. Every transition is deliberate. And for devices that need it, a single toggle disables the expensive effects while preserving the aesthetic.

The app uses the liquid_glass_easy package which applies real-time GPU shader effects including:

• Frosted glass — backdrop blur with dynamic intensity
• Refraction simulation — content appears to bend behind glass surfaces
• Jelly deformation — subtle elastic response to scroll and touch
• Optical borders — light-edge highlights that simulate physical glass thickness
• Hover lensing — magnification and distortion under the cursor on desktop

The GlassSettings service controls a global ValueNotifier<bool> toggle — "Full Liquid Glass." When enabled, all GPU shader effects are active for the premium experience. When disabled, the app falls back to lightweight gradient and blur approximations that preserve the visual intent without the GPU cost. Users can toggle this in Settings at any time. The toggle persists via SharedPreferences.

Key performance optimizations:

• RepaintBoundary — widget subtrees that don't need shader recomputation are isolated
• Shader pre-warming — a sweep animation on the dock pre-compiles GPU shaders before user interaction
• PerformanceLiquidLens — optimized shader presets for common patterns (dock, sheet, menu button, menu)
• Fallback gradients — when glass is disabled, styled gradients maintain the frosted look without shader overhead

A macOS-style animated dock sits at the bottom of the home screen providing navigation to Manga, Audiobooks, and Music sections. Dock icons scale up with proximity to the cursor — a lens magnification effect. Arrow buttons appear when dock items overflow the available width. The dock pre-warms GPU shaders during its initial build to eliminate first-interaction jank.

Movie and manga cards adapt to screen width through factory sizing classes:

Screen Width < 600px  >> Card width: 138px  (compact mobile)
Screen Width 600-900  >> Card width: ~155px (tablet)
Screen Width 900-1200 >> Card width: ~175px (small desktop)
Screen Width > 1200px >> Card width: 205px  (large desktop)

Cards feature hover animations — subtle lift with shadow expansion on mouse enter, return on exit. A shimmer loading skeleton (PosterSkeleton) displays while cover art loads. Missing posters fall back to an icon placeholder.

A glass-styled scrollbar with:

• Drag-to-scroll thumb
• Arrow buttons at each end for incremental scroll
• Magnetic snap — thumb gravitates toward nearest position
• Animated opacity — visible on hover, fades when idle
• Dual orientation — vertical and horizontal variants

• SectionHeader — Title + optional subtitle + "See All" link that navigates to full catalog
• MovieSliderSection — Horizontal scrollable row with animated slide-in arrow buttons. Arrows appear on hover (desktop) or are always visible (mobile). Scrolls 80% of viewport width per arrow press.
• SliderArrow — Glass circle button with hover/press state animations

Background: #080A0F (deep near-black with blue undertone)
Seed Color:  #7C5CFF (vibrant purple — used for accents, buttons, focus rings)
Surface:     Glass with 10-20% opacity over background
Text:        White primary, 70% opacity secondary
Brightness:  Dark (forced — no light mode)
Material:    Material 3 (latest Material Design spec)

Scroll overscroll effects are disabled globally for a clean, native-feeling scroll experience. The debug banner is suppressed. The app runs in immersive sticky mode — system UI (status bar, navigation bar) auto-hides for full-screen content consumption.

PlayTorrioV3/
├── lib/
│   ├── main.dart                          # App entry point — engine init, addon boot, theme
│   ├── models/
│   │   ├── addon/addon.dart               # AddonManifest, InstalledAddon
│   │   ├── movie/movie.dart               # Movie catalog item
│   │   ├── movie/movie_detail.dart        # Full metadata (cast, genres, rating, runtime)
│   │   ├── movie/video.dart               # Episode/season video
│   │   ├── movie/link.dart                # External links (IMDb, trailers)
│   │   ├── movie/movie_section.dart       # Grouped catalog section
│   │   ├── stream/stream_model.dart       # Playable stream source with quality detection
│   │   ├── subtitle/subtitle_model.dart   # SubtitleVariant, SubtitleLanguageGroup
│   │   ├── manga/manga.dart               # Manga metadata
│   │   ├── manga/manga_chapter.dart       # Chapter with number parsing
│   │   ├── audiobook/audiobook_model.dart # Audiobook + AudiobookChapter
│   │   └── music/music_track.dart         # MusicTrack, MusicArtist, MusicAlbum, Playlist
│   ├── services/
│   │   ├── glass_settings.dart            # Global glass effects toggle (ValueNotifier + SharedPreferences)
│   │   ├── addon/addon_manager.dart       # Central orchestrator — install, search, catalog aggregation
│   │   ├── metadata/metadata_service.dart # Stremio HTTP client (manifest, catalog, search, meta)
│   │   ├── metadata/bestsimilar_scraper.dart  # "More Like This" recommendation engine
│   │   ├── stream/stream_service.dart     # Aggregates streams from scrapers + addons
│   │   ├── stream/torrent_stream_service.dart # Native libtorrent engine — magnet >> HTTP stream
│   │   ├── scraper/stream_scraper.dart    # Abstract base class + ScraperManager registry
│   │   ├── scraper/sites/
│   │   │   ├── flystream.dart             # FlyStream VOD scraper
│   │   │   ├── videasy.dart               # Videasy multi-CDN scraper (encrypted API)
│   │   │   ├── vidsrc.dart                # VidSrc dual-strategy scraper
│   │   │   ├── multiembed.dart            # MultiEmbed (2embed.cc) scraper
│   │   │   ├── vidcore.dart               # VidCore multi-server scraper
│   │   │   ├── fourkhdhub.dart            # 4KHDHub scraper (obfuscated redirects)
│   │   │   ├── xdownloader.dart           # XDownloader (Films365) scraper
│   │   │   ├── knaben.dart                # Knaben torrent meta-search scraper
│   │   │   ├── torrent_galaxy.dart        # TorrentGalaxy search scraper
│   │   │   └── tmdb_helper.dart           # IMDb >> TMDB ID resolution with caching
│   │   ├── subtitles/subtitle_service.dart    # Multi-provider subtitle aggregation
│   │   ├── subtitles/subtitle_provider.dart   # Abstract provider interface
│   │   ├── subtitles/subtitle_extractor.dart  # ZIP download + extraction
│   │   ├── subtitles/providers/subdl_provider.dart # Subdl.com implementation
│   │   ├── manga/manga_service.dart       # WeebCentral scraper — browse, search, read, progress
│   │   ├── audiobook/audiobook_scraper_service.dart # 9-source aggregator with parallel search
│   │   ├── audiobook/audiobookbay_scraper.dart      # AudiobookBay torrent parser
│   │   ├── audiobook/audiobook_progress_service.dart # Listening position persistence
│   │   ├── music/music_service.dart       # Octave API client
│   │   ├── music/octave_library_service.dart  # User library — likes, playlists (ChangeNotifier)
│   │   └── music/music_player_controller.dart  # Playback state machine (singleton ChangeNotifier)
│   ├── pages/
│   │   ├── home/home_page.dart            # Hero carousel + catalog sections + dock navigation
│   │   ├── details/details_page.dart      # Movie/series detail with episodes, cast, similar
│   │   ├── player/watch_screen.dart       # Stream source selection — progressive loading, quality sort
│   │   ├── player/player_screen.dart      # Full-screen video player with subtitle overlay
│   │   ├── search/search_page.dart        # Debounced multi-addon search
│   │   ├── catalog/catalog_page.dart      # Infinite scroll catalog with genre filters
│   │   ├── discover/discover_page.dart    # Search results / genre browse grid
│   │   ├── settings/settings_page.dart    # Glass toggle, addon management (install/remove/toggle)
│   │   ├── manga/manga_page.dart          # Manga discovery + continue reading
│   │   ├── manga/manga_details_page.dart  # Manga metadata + chapter list with pagination
│   │   ├── manga/manga_reader_page.dart   # Horizontal/vertical reader with zoom + progress
│   │   ├── music/music_page.dart          # Tabbed music interface (home/search/browse/library)
│   │   ├── audiobooks/audiobooks_page.dart    # Audiobook search + continue listening
│   │   ├── audiobooks/audiobook_detail_page.dart # Audiobook chapter list
│   │   ├── audiobooks/audiobook_player_screen.dart # Audiobook player with timer + speed
│   │   └── audiobooks/audiobook_route_transitions.dart # Custom player transitions
│   ├── widgets/
│   │   ├── common/custom_scroll_track.dart     # Glass scrollbar with drag + arrows
│   │   ├── common/error_view.dart              # Full-screen error with retry
│   │   ├── common/liquid_dock.dart             # macOS-style animated dock
│   │   ├── common/performance_liquid_lens.dart # Optimized glass shader presets
│   │   ├── common/poster_skeleton.dart         # Shimmer loading placeholder
│   │   ├── common/section_header.dart          # Title + subtitle + "See All"
│   │   ├── common/slider_arrow.dart            # Glass arrow button for carousels
│   │   ├── movie/movie_card.dart               # Responsive poster card with hover
│   │   ├── movie/movie_slider_section.dart     # Horizontal scrollable row with arrows
│   │   └── manga/manga_card.dart               # Manga poster card with type badge
│   └── utils/
│       ├── parse_torrent_title.dart         # 100+ regex patterns — parses any torrent filename
│       ├── relevance_scorer.dart            # Tiered relevance scoring for search results
│       └── route_transitions.dart           # LiquidRevealRoute + CinematicSlideRoute
├── assets/
│   ├── icon.png                             # App icon (all platforms)
│   ├── subfont.ttf                          # Subtitle rendering font
│   ├── js/cheerio.bundle.js                 # Server-side DOM parsing (JS scraper runtime)
│   └── scrapers/
│       ├── sources.json                     # Scraper registry — 9 entries, version 1.0.0
│       ├── flystream.js                     # FlyStream JS scraper
│       ├── videasy.js                       # Videasy JS scraper (encrypted API)
│       ├── vidsrc.js                        # VidSrc JS scraper
│       ├── multiembed.js                    # MultiEmbed JS scraper
│       ├── vidcore.js                       # VidCore JS scraper
│       ├── fourkhdhub.js                    # 4KHDHub JS scraper
│       ├── xdownloader.js                   # XDownloader JS scraper
│       ├── knaben.js                        # Knaben JS scraper
│       └── torrent_galaxy.js                # TorrentGalaxy JS scraper
├── libass_plugin/                           # iOS native plugin — bundles ass.framework for ASS/SSA subtitles
│   ├── pubspec.yaml
│   ├── lib/libass_plugin.dart
│   └── ios/
│       ├── libass_plugin.podspec
│       └── ass.framework/
├── android/                                 # Android platform — Gradle build, Kotlin app delegate
├── ios/                                     # iOS platform — Swift app/scene delegates, Xcode project
├── macos/                                   # macOS platform — Swift app delegate, entitlements
├── linux/                                   # Linux platform — CMake, C++ runner, GTK embedding
├── windows/                                 # Windows platform — CMake, C++ runner, Win32 embedding
├── test/
│   ├── widget_test.dart                     # Smoke test — app renders "PlayTorrio" text
│   └── subtitle_test.dart                   # Integration test — Subdl subtitle search
├── bin/
│   └── inspect.dart                         # Standalone WeebCentral HTML scraping debug tool
├── pubspec.yaml                             # Flutter project config — dependencies, assets, launcher icons
├── analysis_options.yaml                    # Dart lint rules
└── README.md                                # This file

{
  "version": "1.0.0",
  "updated": "2026-08-09",
  "sources": [
    {"id": "flystream",     "name": "FlyStream",     "provider": "PlayTorrioHTTP", "script": "flystream.js"},
    {"id": "videasy",       "name": "Videasy",       "provider": "PlayTorrioHTTP", "script": "videasy.js"},
    {"id": "vidsrc",        "name": "VidSrc",        "provider": "PlayTorrioHTTP", "script": "vidsrc.js"},
    {"id": "multiembed",    "name": "MultiEmbed",    "provider": "PlayTorrioHTTP", "script": "multiembed.js"},
    {"id": "vidcore",       "name": "VidCore",       "provider": "PlayTorrioHTTP", "script": "vidcore.js"},
    {"id": "fourkhdhub",    "name": "4KHDHub",       "provider": "PlayTorrioHTTP", "script": "fourkhdhub.js"},
    {"id": "xdownloader",   "name": "XDownloader",   "provider": "PlayTorrioHTTP", "script": "xdownloader.js"},
    {"id": "knaben",        "name": "Knaben",        "provider": "PlayTorrio",     "script": "knaben.js"},
    {"id": "torrent_galaxy","name": "TorrentGalaxy", "provider": "PlayTorrio",     "script": "torrent_galaxy.js"}
  ]
}

// Toggle in Settings page — persisted to SharedPreferences
GlassSettings.enabled.value = true;   // Full liquid glass shaders
GlassSettings.enabled.value = false;  // Lightweight gradient fallback

The flutter_launcher_icons package generates app icons for all platforms from assets/icon.png. Configuration:

flutter_launcher_icons:
  android: true
  ios: true
  windows:
    generate: true
    image_path: "assets/icon.png"
  image_path: "assets/icon.png"
  min_sdk_android: 21

Nearly all services follow the singleton pattern — initialized once, accessed globally:

class AddonManager {
  static final AddonManager instance = AddonManager._internal();
  factory AddonManager() => instance;
  AddonManager._internal();
  // ...
}

// Usage anywhere in the app:
AddonManager.instance.fetchAllHomeSections();

Services using this pattern: AddonManager, TorrentStreamService, ScraperManager, SubtitleService, MusicPlayerController, OctaveLibraryService, MangaService.

Scrapers implement a common interface and register with a central manager. Adding a new source requires only implementing StreamScraper:

class MyNewScraper extends StreamScraper {
  @override
  String get name => 'MyNewScraper';
  
  @override
  Future<List<StreamSource>> scrape({...}) async {
    // Custom scraping logic
  }
}

// Registration:
ScraperManager.instance.register(MyNewScraper());

The manager handles concurrent execution, timeout enforcement, deduplication, and error isolation automatically.

Content is streamed to the UI as it arrives rather than waiting for all sources to complete. Both the home screen's catalog sections and the watch screen's stream sources use StreamController to yield results progressively, batched at 60ms intervals to maintain smooth frame rates.

MovieCardSizing and MangaCardSizing are factory classes that compute card dimensions from screen width:

class MovieCardSizing {
  final double cardWidth;
  final double posterHeight;
  
  factory MovieCardSizing(BuildContext context) {
    final width = MediaQuery.of(context).size.width;
    if (width < 600) return MovieCardSizing._(cardWidth: 138, posterHeight: 207);
    if (width < 900) return MovieCardSizing._(cardWidth: 155, posterHeight: 232);
    // ...
  }
}

This pattern ensures consistent visual density across phones, tablets, and desktop windows without media query duplication in every widget.

Metadata, search results, and scraper responses use least-recently-used caches to avoid redundant network requests during a session. Caches are cleared when addons change. The MetadataService caches catalog queries, search results, and metadata lookups separately. The BestSimilarScraper caps its autocomplete cache at 80 entries and details cache at 30 entries.

A single failing scraper or addon never blocks the rest. Every concurrent operation is wrapped in try-catch and silently skipped on failure. The ErrorView widget provides a consistent full-screen error state with a retry button for catastrophic failures. The ScraperManager catches per-scraper errors and continues with remaining scrapers. The AddonManager marks failed addons and continues serving results from healthy ones.

_{Licensed under GPL-3.0 · Built with Flutter and Dart · Streaming powered by libtorrent, fvp, and the open web}