HQ Video Player

A high-performance, feature-rich, fully customizable Flutter video player package built on top of media_kit and flutter_bloc. Designed to follow the HighQApps package architecture standard with complete control over theme, localizations, icons, gestures, behavior, controls, custom widgets, subtitle options, network headers, and live event callbacks.

---

Features

• High Performance & Cross-Platform: Hardware-accelerated video playback powered by media_kit across Android, iOS, Web, macOS, Windows, and Linux.
• Explicit Source Enums (HqVideoSourceType, HqSubtitleSourceType, HqPosterSourceType):
  • Video: HqVideoSourceType.network, HqVideoSourceType.asset, HqVideoSourceType.file.
  • Subtitles: HqSubtitleSource.network(...), HqSubtitleSource.asset(...), HqSubtitleSource.file(...).
  • Poster Thumbnails: HqPosterSource.network(...), HqPosterSource.asset(...), HqPosterSource.file(...).
• Vertical Short-Form Video Support (HqVideoPlayerBehavior.vertical()):
  • Preset behavior for TikTok, Reels, Shorts, and Stories.
  • Expands to full height in fullscreen mode without auto-rotating to landscape.
• In-Stream & External Subtitles & Multi-Audio Tracks:
  • Embedded subtitle stream track selection (SRT, VTT, ASS/SSA).
  • External SRT/VTT subtitle parsing and rendering.
  • Multi-audio stream track selection.
• Interactive Gesture Overlay:
  • Double-tap left/right to seek forward or backward (customizable duration).
  • Vertical swipe on left side for Screen Brightness control.
  • Vertical swipe on right side for Media Volume control.
  • Long-press anywhere for fast-forward speed boost (default 2x).
  • Two-finger pinch-to-zoom (1x to 4x).
• Full Picker-Style Customization (HqVideoPlayerConfig):
  • HqVideoPlayerTheme: Custom colors for timeline, overlays, buttons, menus, and text styles.
  • HqVideoPlayerLocalizations: Complete control over all text strings with built-in Arabic preset (HqVideoPlayerLocalizations.ar()).
  • HqVideoPlayerIcons: Override any icon with your own custom Flutter Widgets.
  • HqVideoPlayerGestures: Custom seek seconds, hold speed multiplier, toggle gestures independently.
  • HqVideoPlayerBehavior: Custom auto-hide delay, allowed playback speeds list, initial volume, start muted, autoPlay, looping.
  • HqVideoPlayerControlsConfig: Granular toggles for top bar, title, speed, timeline, and lock.
  • HqVideoPlayerCustomWidgets: Watermark overlays, custom loading spinners, custom error widgets.
  • HqVideoPlayerSubtitleConfig: Font size, font family, text color, background color, bottom padding.
  • HqVideoPlayerNetworkConfig: Custom HTTP headers (Auth Tokens/Cookies), weak network timeouts.
  • HqVideoPlayerCallbacks: Live callbacks (onPositionChanged, onPlayingChanged, onFullscreenChanged, onVolumeChanged, onSpeedChanged, onSeek).
• Miniplayer Service: Picture-in-picture floating miniplayer with drag-and-drop position.
• Zero setState Architecture: Clean state management driven by HqVideoPlayerBloc and optimized BlocSelector rebuilds.

---

Getting Started

Add hq_video_player to your pubspec.yaml:

dependencies:
  hq_video_player: ^0.0.1

---

Quick Usage

1. Asset Video Player with Asset Subtitles (HqVideoPlayer.asset)

import 'package:flutter/material.dart';
import 'package:hq_video_player/hq_video_player.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  MediaKitService.ensureInitialized();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
        body: HqVideoPlayer.asset(
          assetPath: 'assets/pubg.mp4',
          subtitleSource: HqSubtitleSource.asset('assets/subtitles.srt'),
          title: 'PUBG Gameplay',
        ),
      ),
    );
  }
}

---

2. Vertical Short-Form Video Player (TikTok / Shorts / Reels)

HqVideoPlayer.asset(
  assetPath: 'assets/vertical_video.mp4',
  title: 'Vertical Story',
  config: const HqVideoPlayerConfig(
    behavior: HqVideoPlayerBehavior.vertical(),
  ),
)

---

3. Network Video Player with Arabic Localizations (HqVideoPlayerConfig.ar)

HqVideoPlayer.network(
  videoUrl: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
  subtitleSource: const HqSubtitleSource.network('https://example.com/subtitles.vtt'),
  title: 'Sample Network Video',
  config: HqVideoPlayerConfig.ar(
    posterConfig: const HqVideoPlayerPosterConfig(
      posterSource: HqPosterSource.network('https://example.com/poster.jpg'),
      posterFit: BoxFit.cover,
    ),
    theme: const HqVideoPlayerTheme(
      timelinePlayedColor: Colors.deepPurpleAccent,
      timelineHandleColor: Colors.deepPurpleAccent,
      subtitleBackgroundColor: Color(0xCC1E1E2E),
      menuBackgroundColor: Color(0xFF1E1E2E),
    ),
    gestures: const HqVideoPlayerGestures(
      doubleTapSeekSeconds: 10,
      longPressSpeed: 2.0,
    ),
    behavior: const HqVideoPlayerBehavior(
      autoPlay: true,
      looping: false,
      showMuteButton: true,
    ),
  ),
)

---

4. Explicit Source Enum Constructor (HqVideoSourceType)

HqVideoPlayer(
  videoUrl: '/storage/emulated/0/Download/movie.mp4',
  sourceType: HqVideoSourceType.file,
  subtitleSource: const HqSubtitleSource.file('/storage/emulated/0/Download/movie.srt'),
  title: 'Local File',
)

---

API Reference

HqVideoPlayer Reference

Property	Type	Default	Description
videoUrl	String	required	Video URL, asset path, or local file path
sourceType	HqVideoSourceType	required	Type of video source (network, asset, or file)
subtitleSource	HqSubtitleSource?	null	Explicit subtitle source (.network, .asset, .file)
title	String	''	Title text displayed in top control bar
showControls	bool	true	Toggle visibility of controls overlay
showGestures	bool	true	Toggle touch gesture overlay
allowFullscreen	bool	true	Enable fullscreen mode toggle button
playPauseOnly	bool	false	Simplified mode showing only play/pause button
config	HqVideoPlayerConfig	default	Central config aggregating theme, localizations, icons, gestures, behavior, controls, custom widgets, subtitle options, network options, and callbacks

---

License

This package is licensed under the MIT License.