📺 tha_player #

Native, network‑only video player for Flutter with modern MX/VLC‑style UX. Android uses ExoPlayer; iOS uses AVPlayer. Includes gestures, thumbnails on seek, DRM (Android), fullscreen, BoxFit, and more.

✨ Features #

• ✅ Native engines: ExoPlayer (Android) and AVPlayer (iOS)
• ✅ Gestures: tap to show/hide, double‑tap seek, long‑press skip, horizontal scrub, vertical volume/brightness
• ✅ Controls: play/pause, speed, fullscreen (manual or auto), lock, BoxFit (contain/cover/fill/fitWidth/fitHeight)
• ✅ Quality, audio, and subtitle track selection with data saver toggle
• ✅ Configurable retry/backoff, error callbacks, PiP playback controls
• ✅ Thumbnails: WebVTT sprites or image sequences during seek preview (cached in-memory)
• ✅ DRM (Android): Widevine and ClearKey
• ✅ M3U playlist parsing utility
• ✅ Overlay support (watermark, logos)

📦 Install #

Add to pubspec.yaml:

dependencies:
  tha_player: ^0.4.0

Then:

flutter pub get

🚀 Quick Start #

import 'package:tha_player/tha_player.dart';

final ctrl = ThaNativePlayerController.single(
  ThaMediaSource(
    'https://storage.flutter-io.cn/gtv-videos-bucket/sample/BigBuckBunny.mp4',
    // Optional VTT thumbnails
    // thumbnailVttUrl: 'https://example.com/thumbs.vtt',
  ),
  autoPlay: true,
  playbackOptions: ThaPlaybackOptions(
    maxRetryCount: 5,
    initialRetryDelay: Duration(milliseconds: 800),
  ),
);

// In build:
AspectRatio(
  aspectRatio: 16 / 9,
  child: ThaModernPlayer(
    controller: ctrl,
    doubleTapSeek: Duration(seconds: 10),
    longPressSeek: Duration(seconds: 3),
    autoHideAfter: Duration(seconds: 3),
    initialBoxFit: BoxFit.contain,
  ),
)

Fullscreen #

Tap the fullscreen icon in the control bar. Playback position and state are preserved when entering/exiting fullscreen.

BoxFit #

Choose between contain, cover, fill, fitWidth, and fitHeight from the menu.

Track Selection #

Use the control bar to switch quality, audio, or subtitle tracks at runtime. You can also fetch tracks directly:

final qualities = await ctrl.getVideoTracks();
final audios = await ctrl.getAudioTracks();
final subtitles = await ctrl.getSubtitleTracks();
await ctrl.selectAudioTrack(audios.first.id);
await ctrl.selectSubtitleTrack(null); // disable captions

Lock Controls #

Use the lock icon to prevent controls/gestures; unlock with the floating button.

DRM (Android) #

final ctrl = ThaNativePlayerController.single(
  ThaMediaSource(
    'https://my.cdn.com/drm/manifest.mpd',
    drm: ThaDrmConfig(
      type: ThaDrmType.widevine, // or ThaDrmType.clearKey
      licenseUrl: 'https://license.server/wv',
      headers: {'Authorization': 'Bearer <token>'},
      // clearKey: '{"keys":[{"kty":"oct","k":"...","kid":"..."}]}'
    ),
  ),
);

Thumbnails (WebVTT) #

Provide a .vtt with sprites or images and optional #xywh regions:

ThaMediaSource(
  'https://example.com/video.m3u8',
  thumbnailVttUrl: 'https://example.com/thumbs.vtt',
)

🛠 Platform Notes #

• Android: ExoPlayer backend with Media3; Widevine/ClearKey supported; per‑item HTTP headers.
• iOS: AVPlayer backend; fitWidth/fitHeight approximate via resizeAspect.
• Keep‑screen‑on is enabled during playback (Android/iOS).
• Playability depends on device codecs, stream, and network.

Thumbnails are cached in-memory. Call clearThumbnailCache() if you need to purge the cache.

Resilient playback #

ThaPlaybackOptions lets you tweak retry/backoff behaviour and rebuffer handling. Failures are surfaced via ThaNativeEvents.error and the onError callback on ThaModernPlayer.

Custom HTTP (Android) #

Provide a bespoke OkHttpClient to inject interceptors or caching:

Register the factory inside your Android Application:

class App : FlutterApplication() {
  override fun onCreate() {
    super.onCreate()
    ThaPlayerPlugin.setHttpClientFactory {
      OkHttpClient.Builder()
        .addInterceptor(MyHeaderInterceptor())
        .cache(Cache(cacheDir.resolve("video"), 100L * 1024L * 1024L))
        .build()
    }
  }
}

Set the factory before creating any Flutter controllers so every instance shares the same client.

16 KB Page Size Support #

This plugin does not ship custom native decoder binaries. If you add native libraries, link them with a max page size compatible with 16 KB systems (e.g., -Wl,-z,max-page-size=16384 on Android NDK).

🧪 Example #

See example/ for a runnable app that demonstrates the modern controls, gestures, fullscreen, and thumbnails.

💖 Support #

If this package helps you, consider a tip:

• Tron (TRC20): TLbwVrZyaZujcTCXAb94t6k7BrvChVfxzi

📣 Contributing #

Issues and PRs are welcome! Please file bugs or ideas at the issue tracker.

📄 License #

MIT — see LICENSE.