FlixQuest

---

✨ Features

🎬 Extensive Movie & TV Show Catalog

• Discovery Feeds: Categorized home feeds with shimmer loading effects — Trending, Top 10 This Week, New Releases, Upcoming, and Popular.
• Detailed Media Pages: Media details featuring trailers, cast & crew filmographies, user reviews, and intelligent "More Like This" recommendations powered by TMDB.
• Explore & Filter: Filter content by genre, release year, streaming provider, country, or sort order, alongside a random discovery tool.
• TV Seasons & Episodes: Interactive episode browser with episode thumbnails, descriptions, air dates, and quick episode switcher sheets.

📺 Android TV (10-Foot UI Experience)

• D-Pad Focus Navigation: Native TV remote control navigation with directional keymaps and focus memory.
• TV Home Shell & Rail: TV navigation rail, catalog screens, and hero banners designed specifically for large screens.
• TV Search & History: Remote-friendly search interface with recent search query history.
• Automatic Presentation Detection: Automatically detects TV devices and adapts the interface between mobile touch and TV 10-foot layout.

📡 Free Live TV & Sports Streaming

• Live TV Integration: Integrated DaddyLive service providing 24/7 TV channels and scheduled live sports events.
• Category Browsing & Search: Search channels by name, filter by category, and view local time-formatted schedules.
• Stream Recovery & Buffering: Smart playback recovery (90-second window), auto-reconnect, and optimized live buffering.
• Local Caching: Fast SQLite caching for live channels and event schedules.

🚀 Multi-Source Video Providers & Scraper API v2

• Dynamic Provider System: Integrated with FlixQuest Scraper API v2 for scraping high-quality streams.
• Live Provider Health Status: Real-time provider uptime monitoring (/providers/status) with in-app status indicators.
• Direct Fallback Provider: Built-in direct VixSrc provider fallback.
• Custom Provider Prioritization: Reorder and prioritize your preferred streaming providers in Settings.
• Stream Formats: Full support for HLS (.m3u8), DASH (.mpd), and direct MP4 streams with custom header support.

💬 Comprehensive Subtitle Management

• Automatic External Subtitles: Multi-language subtitle search and retrieval powered by Wyzie Subtitles API.
• Local Subtitle Upload: Pick and load local .srt or .vtt subtitle files directly from your device storage.
• Subtitle Customization: Adjust font size, text color, background color, and visual styling presets.
• Encoding & HI Support: Smart character encoding handling (UTF-8, Latin1, ASCII) and Hearing-Impaired (HI) tags.

📥 Offline Downloads

• Background Downloads: Download movies and TV episodes with background download management and progress notifications.
• Aspect Ratio Normalization: Built-in video exporter with square-pixel aspect ratio normalization.
• Subtitle Bundling: Automatically export and bundle subtitles with downloaded videos for offline viewing.
• Offline Player: Dedicated offline library and media player for downloaded files.

🎨 Modern UI, Ambient Glow & Seasonal Themes

• Phosphor Icons: Clean, consistent icon set using Phosphor Flutter icons across the entire app.
• Ambient Mode: Dynamic color palette extraction from movie/show posters and backdrops for an immersive ambient background glow.
• Occasional & Seasonal Themes: Dynamic holiday themes (Christmas, New Year, Halloween, Valentine's Day, Easter, Eid, Diwali, Ethiopian New Year, etc.) with animated vector particle overlays (snow, fireworks, bats, hearts, adey flowers, confetti, stars, sparkles). Configurable via Firebase Remote Config.
• Themes: Light, Dark, AMOLED Pure Black, and Material 3 Dynamic Color palettes.

Advertising

• Centrally configured Adsterra WebView banners replace Start.io across existing phone, tablet, and Android TV slots.
• Firebase Remote Config controls network/TV switches, banner codes, six supported sizes, and per-placement overrides with width fallbacks.
• Hosted /ads announcements can stack above network banners or take priority. TV ads remain display-only.
• Setup: Remote Config advertising guide and configured banner catalog, with a blank template for other accounts.

🔐 User Profiles & Cloud Synchronization

• Firebase Authentication: User accounts with email/password authentication, profile management, and account deletion.
• Cross-Device Bookmark Sync: Dual-layer bookmark synchronization between local SQLite and Cloud Firestore.
• Recently Watched & Resume: Track watch progress across movies and episodes with quick resume playback.

🌍 Multi-Language Localization

• Complete internationalization powered by easy_localization supporting multiple languages including English, Spanish, Arabic, Hindi, and more.

---

📱 Screenshots

---

⚙️ Environment Variables & API Keys

FlixQuest uses flutter_dotenv to load environment variables. Create a .env file in the root directory of the project:

# Required: TMDB API Key for movie and TV show metadata
TMDB_API_KEY="your_tmdb_api_key"

# Required: FlixQuest Scraper API v2 instance URL
FLIXQUEST_API_URL="https://your-flixquest-api-instance.com"

# Optional: Mixpanel project token for general analytics
MIXPANEL_API_KEY="your_mixpanel_api_key"

Obtaining API Keys

• TMDB API Key: Register at The Movie Database (TMDB) to get your free API key.
• FlixQuest Scraper API: The scraper service is closed-source. For API access, self-hosting inquiries, or support, please reach out to [email protected].
• Mixpanel Token (Optional): Create a free account at Mixpanel.

---

🕷️ FlixQuest Scraper API v2

FlixQuest communicates with FlixQuest Scraper API v2 for resolving streaming sources. The backend service is closed-source; please contact [email protected] for support or API instance access.

The client-side API contract and payload schemas are documented in openapi.json.

Key endpoints consumed by the app:

• GET /providers: Discovers available and enabled video providers.
• GET /providers/status: Fetches live provider health status, latency, and uptime.
• GET /stream-movie: Scrapes streaming links for movies using TMDB ID.
• GET /stream-tv: Scrapes streaming links for TV episodes using TMDB ID, season, and episode number.
• GET /subtitles/search: Searches every subtitle provider for a movie or episode and returns one combined catalog.
• GET /subtitles/{provider}/{id}: Downloads a subtitle file. The API converts and re-encodes it, so the app never contacts a subtitle host directly.
• POST /stream-size: Estimates the byte size behind a stream token so the quality picker can show sizes.
• GET /api/v2/intro: Retrieves branded intro video configuration.

---

🔥 Firebase Configuration

FlixQuest uses Firebase for several services:

Service	Purpose
Firebase Authentication	User authentication, profile management, and session handling.
Cloud Firestore	Cloud bookmark synchronization across multiple devices.
Firebase Remote Config	Dynamic configuration for feature toggles (Watch now, Download, Live TV), app logos, seasonal themes, and vector animation effects. See docs/firebase_remote_config.md for full schema details.
Firebase Cloud Messaging	Background notifications and alerts.
Firebase In-App Messaging	Dynamic in-app banners and update notices.
Firebase Analytics	Usage and performance analytics.

Note: To connect to your own Firebase project, place your google-services.json inside android/app/.

---

▶️ Custom better_player Package

This repository uses a customized version of better_player (better_player_plus) located at github.com/BeamlakAschalew/flixquest-betterplayer.

You can configure it in pubspec.yaml using a local path or git URL:

better_player_plus:
  git:
    url: https://github.com/BeamlakAschalew/flixquest-betterplayer.git

Or reference a local sibling directory:

better_player_plus:
  path: ../flixquest-betterplayer

---

🛠️ Getting Started & Build Instructions

Prerequisites

• Flutter SDK: >=3.0.0 <4.0.0
• Dart SDK: ^3.0.0
• Android SDK / NDK: Android SDK 34+, Java 17

Installation Steps

1. Clone the repository:

   git clone https://github.com/BeamlakAschalew/flixquest.git
   cd flixquest
   

2. Clone the custom better_player repository (if using local path):

   cd ..
   git clone https://github.com/BeamlakAschalew/flixquest-betterplayer.git
   cd flixquest
   

3. Configure Environment Variables: Create a .env file in the project root:

   cp .env.example .env # or create a new .env file with your keys
   

4. Install Dependencies:

   flutter pub get
   

5. Run the Application:

   • For Android Mobile / Tablet:

     flutter run
     

   • For Android TV (Emulator or connected TV device):

     flutter run -d <tv-device-id>
     

   The app detects TV or mobile mode automatically by default. If a custom ROM reports the wrong device type, choose Settings → Appearance → App mode → TV or Mobile. The interface switches immediately and the choice is saved across launches. Choose Automatic to return to device detection.

   Android has two flavors: prod (the default) and dev. To test real banner ads using Firebase's banner_ad_network_test selector, run the dev flavor:

   flutter run --flavor dev
   flutter run --flavor dev --release
   

   The test selector works in dev debug/profile/release builds. Prod ignores it in every build mode. See banner testing setup. Both flavors reuse the existing Android package and Firebase registration; they share an install slot. The dev launcher label is FlixQuest Dev.

6. Build Release APK:

   flutter build apk --release
   

   This uses the default prod flavor and outputs build/app/outputs/flutter-apk/app-prod-release.apk. You can also specify --flavor prod explicitly. A development release APK is built with .

---

🤝 Contributing

Contributions, feature suggestions, design ideas, and translations are always welcome!

• Pull Requests: Please ensure your code passes static analysis and is properly formatted:

  dart format .
  flutter test
  

• Issue Reports: Please follow the provided issue templates when opening bugs or feature requests.

---

⚠️ Disclaimer

• The developers of this application have no affiliation with content providers like TMDB, DaddyLive, or any third-party streaming websites.
• FlixQuest does not host or upload any video content. All media is retrieved via public scrapers and third-party APIs.
• In case of copyright infringement, please contact the responsible hosting services or source providers directly.

---

---

🙏 Credits & Integrations

• TMDB API: Media metadata, cast, crew, and artwork.
• Phosphor Icons: Beautiful, consistent icon pack (phosphor_flutter).
• Matinee Flutter: Initial UI inspiration and base architecture (bimsina/Matinee-Flutter).

---