gumlet_video_player 1.1.2

A robust Flutter SDK for Gumlet Video Player, providing native HLS, DASH, and DRM (Widevine & FairPlay) streaming capabilities.

Gumlet Flutter SDK

A Flutter plugin wrapping the native Gumlet Video Player SDKs for Android and iOS.

Supports HLS/DASH/MP4 playback, DRM (Widevine on Android, FairPlay on iOS), and offline downloads with offline DRM playback.

Installation

Add the plugin to your app's pubspec.yaml:

dependencies:
  gumlet_video_player: ^1.1.0

Android

Fully automated — the plugin pulls com.gumlet.video:player from Gumlet's Maven repository, and the download service plus its permissions (INTERNET, POST_NOTIFICATIONS, FOREGROUND_SERVICE, FOREGROUND_SERVICE_DATA_SYNC) merge into your app automatically.

Set minSdkVersion to at least 24 in android/app/build.gradle.

Before your first download, request the notification permission — downloads run in a foreground service that posts a progress notification, and on Android 13+ they will not progress without it:

await GumletDownloadManager.instance.requestNotificationPermission();

This is a no-op returning true on iOS and below Android 13.

iOS

Fully automated — the plugin vendors the precompiled GumletVideoPlayer.xcframework.

Set the deployment target to at least 13.0 in ios/Podfile.

For background downloads to finish while your app is suspended, forward the session callback in ios/Runner/AppDelegate.swift:

import gumlet_video_player

override func application(
  _ application: UIApplication,
  handleEventsForBackgroundURLSession identifier: String,
  completionHandler: @escaping () -> Void
) {
  FluttersdkPlugin.handleBackgroundSessionEvents(identifier, completionHandler)
}

Playback

import 'package:gumlet_video_player/gumlet_video_player.dart';

SizedBox(
  height: 250,
  child: GumletPlayer(
    videoUrl: 'https://video.gumlet.io/YOUR_VIDEO_ID/main.m3u8',
    autoPlay: true,
    showControls: true,
    drmLicenseUrl: 'https://fairplay.gumlet.com/licence/...',      // Widevine or FairPlay
    certificateUrl: 'https://fairplay.gumlet.com/certificate/...', // iOS FairPlay only
  ),
)

GumletPlayer parameters

Parameter	Type	Default	Description
videoUrl	String	required	Stream URL. Supports .m3u8 (HLS), .mpd (DASH) and .mp4. Also the online fallback when offline playback is on but nothing is downloaded.
autoPlay	bool	true	Start playing as soon as the player mounts.
showControls	bool	true	Show the native playback controls.
drmLicenseUrl	String?	null	DRM license server URL — Widevine on Android, FairPlay on iOS.
certificateUrl	String?	null	FairPlay application certificate URL. iOS only; ignored on Android.
videoId	String?	null	Stable unique id. Required when enableOfflinePlayback is true, and must match the id used to download.
enableOfflinePlayback	bool	false	Play from local storage when a completed download exists for videoId.

The certificate URL must not have a trailing slash. Gumlet returns HTTP 400 ("Organization id is not valid") for .../certificate/<id>/, which AVFoundation then reports as an opaque "Cannot Open" error.

The iOS Simulator cannot play FairPlay DRM. It has no Secure Enclave, so DRM playback and offline DRM downloads must be tested on real hardware. Widevine works fine on Android emulators.

Offline downloads

final downloads = GumletDownloadManager.instance;

// Start a download. videoId must be stable — it is how the file is found later.
await downloads.downloadVideo(
  videoId: 'my-stable-video-id',
  videoUrl: 'https://video.gumlet.io/.../main.m3u8',
  drmLicenseUrl: '...',   // optional
  certificateUrl: '...',  // iOS FairPlay only
);

// React to progress and state changes.
downloads.events.listen((event) {
  print('${event.videoId}: ${event.state}');
});

// Play it back offline.
GumletPlayer(
  videoUrl: streamUrl,          // online fallback
  videoId: 'my-stable-video-id',
  enableOfflinePlayback: true,
);

GumletDownloadManager API

Member	Returns	Description
downloadVideo(...)	Future<void>	Starts a download. No-op if the id is already downloaded or downloading.
removeDownload(id)	Future<void>	Cancels an in-flight download, or deletes a completed one and its offline key.
pauseDownload(id)	Future<void>	Pauses an in-flight download.
resumeDownload(id)	Future<void>	Resumes a paused download.
getDownloadState(id)	Future<GumletDownloadState>	Current state of one video.
getAllDownloads()	Future<Map<String, GumletDownloadState>>	All known downloads, keyed by videoId.
hasOfflineDrmKey(id)	Future<bool>	Whether a persistent offline DRM key is stored.
hasNotificationPermission()	Future<bool>	Android 13+ notification permission state. Always true elsewhere.
requestNotificationPermission()	Future<bool>	Requests it. Required on Android 13+ before downloading.
setDebugLoggingEnabled(bool)	Future<void>	Verbose native logging. Off by default; leave it off in production.
events	Stream<GumletDownloadEvent>	Push-based state and progress updates.

GumletDownloadState

status is one of notDownloaded, queued, downloading, completed, failed, removing, stopped, with isCompleted / isInProgress convenience getters. percentDownloaded (0–100) applies while downloading; reason is set on failure.

Poll for progress on Android

Do not drive a progress bar from events alone. ExoPlayer reports through DownloadManager.Listener.onDownloadChanged, which fires on state transitions — not continuously. After the initial queued → downloading change no further events arrive until the download completes or fails, so the bar freezes and a perfectly healthy download looks stuck.

Poll getAllDownloads() about once a second while anything is in progress:

Timer.periodic(const Duration(seconds: 1), (t) async {
  final all = await downloads.getAllDownloads();
  final active = all.values.any((s) => s.isInProgress);
  if (!active) t.cancel();
  setState(() => _downloads = all);
});

iOS pushes real progress, so the poll is simply redundant there. example/lib/downloads_screen.dart shows the full pattern.

Note also that a DRM HLS download fetches every rendition (360p/480p/540p/720p plus audio), so early progress is a fraction of a percent — render at least two decimals below 10% or it will read as 0%.

Re-downloading

downloadVideo is a no-op when an entry already exists for that videoId. Call removeDownload first to force a fresh download.

This matters for DRM: HLS segments download fine without a DRM key attached, so a video first downloaded without DRM leaves a completed entry that silently blocks the key flow from ever running. Use hasOfflineDrmKey to detect that case.

Offline DRM requires backend configuration

A downloaded DRM video only plays with no network connection if the license server issued a persistable key — and that has to be requested in the license URL.

Platform	Duration parameters
iOS (FairPlay)	storage_duration, playback_duration
Android (Widevine)	rental_duration, playback_duration

https://fairplay.gumlet.com/licence/<org_id>/<asset_id>
    ?expires=<ms_timestamp>
    &storage_duration=2592000
    &playback_duration=86400
    &token=<signature>

These parameters must appear in both the final URL and the string your backend signs, in the same order — otherwise Gumlet returns 401 token signature does not match.

Without them the download still succeeds, but playback falls back to fetching a license over the network, so it will not work in airplane mode. Check hasOfflineDrmKey to confirm.

Test offline playback in airplane mode. On Wi-Fi the SDK silently falls back to streaming, so a broken offline setup looks like success.

Keeping native SDKs in sync

iOS and Android version independently:

./update_sdk_version.sh --ios 1.0.3 --android 1.1.0

After changing native sources or the vendored framework, run cd example/ios && pod install so CocoaPods picks up the new files.

Example

The example/ app demonstrates the full surface — playback, DRM, downloads with progress, pause/resume, an offline-key indicator, and offline playback.

cd example
flutter run