Skip to navigation

Play DRM-protected content

Add DRM-protected playback to your Flutter app so videos stay protected on every device. The FastPix Flutter Player runs the same Dart code on Android and iOS and handles the device’s DRM system for you.

DRM (Digital Rights Management) encrypts your video so it cannot be copied or played outside your app. To play it, the player asks the FastPix license server for a key, and the server gives the key only to viewers with a valid token.

The player picks the right DRM system for each device:

  • Android uses Widevine.
  • iOS uses FairPlay.

The SDK builds the license URL, and the FairPlay certificate URL on iOS, from your playback ID. You only provide the tokens.


Before you begin

Make sure you have the following:

  • The FastPix Flutter Player SDK installed, version 1.2.0 or later. See Install FastPix Flutter player.
  • DRM enabled on your FastPix account, and a video uploaded with DRM protection. See Set up DRM encryption.
  • For iOS: a FairPlay certificate uploaded in your FastPix dashboard under Settings > DRM. Without it, protected videos don’t play on iPhone or iPad.
  • A playback token and a DRM token for the video. See Set up DRM encryption for how to generate them.

Play a DRM-protected video

Pass the playback token as token, and the DRM token inside a FastPixPlayerDrmConfiguration.

  1. Create the data source with your tokens.

    import 'package:fastpix_video_player/fastpix_video_player.dart';
    final dataSource = FastPixPlayerDataSource.hls(
    playbackId: 'your-playback-id',
    token: 'your-playback-token', // Authorizes the stream
    drmConfiguration: FastPixPlayerDrmConfiguration(
    drmToken: 'your-drm-token', // Authorizes the license request
    ),
    );
  2. Initialize the controller.

    final controller = FastPixPlayerController();
    await controller.initialize(dataSource: dataSource);
  3. Add the player to your widget tree.

    FastPixPlayer(controller: controller)

The player detects the platform, requests the license, and starts playback. You don’t need to change any Android or iOS project files.


Required parameters

  • token: A JWT that authorizes playback of the stream.
  • drmToken: A JWT that authorizes the license request.

If you generate the token with the DRM License option turned on, the same token works for both. Pass it to both parameters.


Customize DRM options

FastPixPlayerDrmConfiguration takes these optional settings:

FastPixPlayerDrmConfiguration(
drmToken: 'your-drm-token',
drmType: FastPixDrmType.widevine, // Override the per-platform default
secureScreen: true, // Android only. Default: true
headers: {'X-Custom-Header': 'value'}, // Extra headers on the license request
)
  • drmType: The DRM system to use. Defaults to Widevine on Android and FairPlay on iOS, so most apps leave it unset. Pass FastPixDrmType.widevine or FastPixDrmType.fairplay to override the default.
  • secureScreen: Blocks screenshots and screen recording while the video plays. Android applies this to the whole app, not just the player, so screenshots are blocked everywhere in your app until the player is disposed. Set it to false if your app needs screenshots to keep working. On iOS, FairPlay hides protected video in screenshots and recordings automatically.
  • headers: Adds headers to the license request. Most apps don’t need this.

Handle DRM errors

DRM errors reach your app in two ways:

  • Setup errors, such as a missing token, make initialize throw a FastPixDrmException.
  • Playback errors, such as an expired token, are sent to your error listener as a FastPixPlayerDrmErrorEvent.
import 'package:flutter/foundation.dart';
try {
await controller.initialize(dataSource: dataSource);
} on FastPixDrmException catch (error) {
debugPrint('${error.code}: ${error.message}');
if (error.isTokenRelated) {
// The token is missing, invalid, or expired. Get new tokens and try again.
} else if (error.isRetryable) {
// A temporary problem, such as the network. Try again.
}
}
// DRM failures are also delivered to your error listener.
controller.addEventListener(FastPixPlayerEventTypes.error, (event) {
if (event is FastPixPlayerDrmErrorEvent) {
debugPrint('${event.code} ${event.message}');
}
});

On the caught FastPixDrmException, isTokenRelated tells you whether re-issuing the DRM token is likely to help, and isRetryable whether a plain retry may succeed. For a DRM failure that reaches your error listener during playback, match event.code against the error codes below to decide how to respond.

The player shows its own error screen. To replace it, pass drmErrorWidgetBuilder to FastPixPlayer.

Error codeWhat it means
FP_DRM_CONFIGURATION_MISSINGThe video is DRM protected, but no drmConfiguration was provided.
FP_DRM_MISSING_DRM_TOKENdrmToken is empty.
FP_DRM_MISSING_PLAYBACK_TOKENThe playback token is empty.
FP_DRM_UNSUPPORTED_PLATFORMThe DRM system doesn’t match the platform, such as FairPlay on Android.
FP_DRM_LICENSE_UNAUTHORIZEDThe license server rejected the token. It’s expired, invalid, or made for another video.
FP_DRM_LICENSE_REQUEST_FAILEDThe license request failed because of a network error, server error, or timeout.
FP_DRM_CERTIFICATE_REQUEST_FAILEDThe FairPlay certificate couldn’t be fetched (iOS).
FP_DRM_PROVISIONING_FAILEDThe device couldn’t be set up for DRM.
FP_DRM_DEVICE_NOT_SUPPORTEDThe device can’t play protected content.
FP_DRM_UNKNOWNAny other DRM error. Check error.underlyingError for details.

For general playback errors, see Handle playback errors.


Diagnose DRM failures

The device players report most load failures with the same opaque message, so a DRM problem can look identical to a bad playback ID or an expired playback token. The player can probe the FastPix manifest, license, and certificate endpoints after a failure to find the real cause. This separates a bad playback ID (manifest 404) from an expired playback token (manifest 403) from a rejected DRM token (license 401 or 403).

FastPixPlayer runs this probe by default and renders its own failure state. Pass drmErrorWidgetBuilder and errorWidgetBuilder to supply your own:

FastPixPlayer(
controller: controller,
diagnoseErrors: true, // Default: probe the endpoints after a failure
drmErrorWidgetBuilder: (error) => Text('DRM: ${error.message}'),
errorWidgetBuilder: (error) => Text(error.message),
)

You can also request the diagnosis directly from the controller:

final diagnosis = await controller.diagnosePlayback();
debugPrint(diagnosis?.summary); // Human readable cause
debugPrint(diagnosis?.probes.join(' · ')); // Per-endpoint results

The most recent DRM failure stays available on the controller as controller.lastDrmError, and any playback failure as controller.lastError.


Things to know

  • The Flutter SDK plays DRM-protected on-demand videos.
  • Tokens are issued per video. When you switch videos with controller.loadPlaybackId(...), pass the new video’s own tokens.
  • Always test DRM on real devices. FairPlay doesn’t work in the iOS Simulator, and Android emulators often lack full Widevine support.
  • To confirm DRM is working on iOS, take a screenshot during playback. The video area appears black.
  • On Android, screenshot blocking comes from secureScreen, not from DRM. With secureScreen on, Android blocks the screenshot entirely. With it off, the video appears in the screenshot.
  • Chromecast can’t play DRM-protected videos through Google’s default receiver. You need a custom receiver app.

Frequently asked questions

Which DRM systems does the Flutter player support?

Widevine on Android and FairPlay on iOS. The SDK picks the right one automatically, so the same Dart code works on both platforms.

Do I need both a playback token and a DRM token?

Yes. The playback token authorizes the stream, and the drmToken authorizes the license request. If you generate the token with the DRM License option, use the same value for both.

Why does DRM playback work on Android but not on iOS?

The most common cause is a missing FairPlay certificate. Upload it in the FastPix dashboard under Settings > DRM. Also test on a real iPhone or iPad, since FairPlay doesn’t work in the iOS Simulator.

Why can’t users take screenshots anywhere in my app on Android?

secureScreen is on by default, and Android applies it to the whole app while a DRM video plays. Set secureScreen: false in FastPixPlayerDrmConfiguration if screenshots must keep working.


What’s next