hls_proplayer #

A fully customizable Flutter video player for HLS (.m3u8) live and recorded streams, with video quality switching, custom controls, playback speed, fullscreen handling, and offline MP4 playback with zoom support. 🎥

✨ Features #

• 📡 Play HLS live and recorded streams
• 🎚️ Video quality switching (parse .m3u8 variants)
• 🧩 Fully customizable UI: theming + builders for controls, placeholder, buffering
• 🔒 Token auth via request headers
• ⏯️ Autoplay and looping options
• ⏩ Playback speed control
• 📱 Fullscreen orientation handling
• 📥 Offline download support – play saved .mp4 files
• 🔍 Zoom & pan gestures when playing videos

🚀 Installation #

Add to your pubspec.yaml:

dependencies:
  hls_proplayer: ^0.1.5

---

## 🧰 Usage

### Basic Example

```dart
import 'package:flutter/material.dart';
import 'package:hls_proplayer/hls_proplayer.dart';

class VideoPlayerScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: HlsPlayer(
        url: 'https://example.com/master.m3u8',
        mode: Mode.live,
        autoplay: true,
        looping: false,
      ),
    );
  }
}

Advanced Example with Custom Theme #

HlsPlayer(
  url: 'https://example.com/master.m3u8',
  mode: Mode.live,
  headers: {'x-token': 'your-auth-token'},
  autoplay: true,
  looping: false,
  startAt: 0, // Start position in seconds (for recorded mode)
  controlsHideTimeout: const Duration(seconds: 4),
  controlsTheme: const HlsControlsTheme(
    progressActiveColor: Colors.blue,
    progressInactiveColor: Colors.grey,
    liveIndicatorColor: Colors.red,
    iconColor: Colors.white,
    iconSize: 24.0,
  ),
  placeholderBuilder: (ctx) => const Center(
    child: Text('Loading video...', style: TextStyle(color: Colors.white)),
  ),
  bufferingIndicatorBuilder: (ctx) => const Center(
    child: CircularProgressIndicator(color: Colors.blue),
  ),
)

Recorded Video Playback #

HlsPlayer(
  url: 'https://example.com/recorded.m3u8',
  mode: Mode.recorded,
  startAt: 30, // Start at 30 seconds
  autoplay: true,
  looping: true,
)

MP4 File Playback #

HlsPlayer(
  url: '/path/to/local/video.mp4',
  mode: Mode.MP4,
  autoplay: true,
  looping: false,
)

Custom Controls #

HlsPlayer(
  url: 'https://example.com/master.m3u8',
  mode: Mode.live,
  controlsBuilder: (context, controller, isFullScreen, qualities, controlsVisible, showControls) {
    return MyCustomControls(
      controller: controller,
      isFullScreen: isFullScreen,
      qualities: qualities,
      onToggleControls: showControls,
    );
  },
)

🎨 Customization API #

• Theming: pass HlsControlsTheme to style overlay, icon colors/sizes, progress & live colors.
• Controls builder: provide controlsBuilder to render a completely custom controls widget.
• Placeholders: placeholderBuilder (before qualities load) and bufferingIndicatorBuilder (while loading/buffering).
• Behavior: autoplay, looping, controlsHideTimeout.

📦 Example App #

See example/ for a minimal app demonstrating live and recorded playback and custom UI.

❗ Troubleshooting #

• UnimplementedError: init() has not been implemented. Add video_player as a dependency in your app (not only the plugin) so the platform implementation is registered:

dependencies:
  video_player: ^2.10.0

• Android: ensure a recent emulator/device with GLES 2.0+. If you see called unimplemented OpenGL ES API, try a real device or change emulator graphics settings.