eyzflow_player
The EYZFlow video player for Flutter apps, in one package:
- The player: fullscreen playback of EYZFlow streams. AVPlay on Samsung Tizen TVs, ExoPlayer on Android and Android TV, AVPlayer on iOS; Widevine and FairPlay DRM; the TV controls overlay; subtitles and audio tracks; resume and watch progress. How it works: doc/player.md.
- The EYZFlow rules around it, the same as the EYZFlow web
player:
- Player key check:
POST /v1/player/license, renewed while playing. - Stream and device limits: a playback session that opens, heartbeats
and closes, with
STREAM_LIMIT/DEVICE_LIMITrefusals shown to the viewer. - Playback quality analytics: cumulative beats to
POST /v1/player/beat(startup time, played, paused and stalled time, stalls, seeks, errors).
- Player key check:
Use
import 'package:eyzflow_player/eyzflow_player.dart';
Navigator.of(context).push(MaterialPageRoute<void>(
fullscreenDialog: true,
builder: (_) => EYZFlowPlayer(
streamId: streamId, // not the catalogue id
title: title,
sourceType: EYZFlowFilm(catalogueId), // or EYZFlowTrailer(…)
progressSeconds: resumeAt,
isTv: isTv,
drmAuthorization: 'Bearer $cognitoAccessToken',
storefrontId: storefront.id,
drmParameters: const {'source': 'internal'},
playerKey: 'pk_…', // optional
configId: 'cfg_…', // optional: dashboard player config
watchProgressStore: myWatchHistory, // optional: see below
language: 'de', // optional: en, de, fr, nl
onLimitReached: (limit) => …, // STREAM_LIMIT, DEVICE_LIMIT, …
onLicenseError: (error) => …, // PLAYER_KEY_INVALID, …
onPlaybackEvent: (event) => …, // the host's own analytics
),
));
Pass the viewer's Authorization and the storefront, and the player builds the
DRM access-token header itself.
VideoplayerFeatureView(videoSource: …) is still exported: the player alone,
with no key check, session or beats, and a ready-made drmAccessHeader.
What happens
Before playback, in the web player's order:
- Reads this device's id (
shared_preferences, keyeyzflow.deviceId). - With a
playerKey: the key check, sending the app ({platform, id}) in place of a web page's Origin. A refusal shows the error screen and callsonLicenseError. If the check cannot be made, playback goes on without a token and without analytics. - With
drmAuthorizationandstorefrontId: opens a playback session withplatform(android,androidtv,ios,tizen) andX-Device-Id, for a trailer too (it says whether the viewer's plan plays ads, see Ads), so trailers count against the plan's stream limit. A limit shows the error screen and callsonLimitReached. Any other failure carries on; the DRM licence request enforces the limits too. - For a film: builds the
access-token:authorizationplusstorefront_id,device_id,playback_session_idandplayer_token, with anydrmParameters.
While playing: the token renews after refresh_after (a refusal stops playback
only when the organisation enforces), the session heartbeats at the interval
the backend gives (a session ended elsewhere stops playback with
PLAYBACK_SESSION_ENDED), and beats go out every heartbeat interval, at once on
the first frame and on errors, and when the app goes to the background. On
close: a final beat and DELETE of the session.
Without playerKey there is no key check and no beats. Without storefrontId
(or drmAuthorization) there is no session. A trailer plays without DRM.
Viewer messages
The player's own copy (controls, playback errors) is localized in en, de, fr
and nl (EYZFlowPlayer(language:) or setEYZFlowPlayerLanguage, else the
device's language). Track names in the TV audio and subtitle panels come from
a built-in table (Unicode CLDR) in the same language: "Deutsch" for de,
deu, ger or de_DE; set EYZFlowLanguageNames.resolver to use your own.
The limit and key messages are the web
player's, in English; replace the error screen with errorBuilder to show
your own (the failure carries its code).
| Code | Message |
|---|---|
STREAM_LIMIT |
You're watching on too many screens. Stop playback on another device to watch here. |
DEVICE_LIMIT |
Your plan's device limit is reached. Remove a device in your account to watch here. |
DEVICE_REVOKED, SESSION_REVOKED |
You were signed out on this device. Sign in again to watch. |
PLAYBACK_SESSION_ENDED |
Playback was stopped from another device. |
PLAYER_KEY_INVALID |
This player is not set up correctly (invalid player key). |
DOMAIN_NOT_ALLOWED, APP_NOT_ALLOWED, … |
This video cannot be played in this app. |
Playback events
onPlaybackEvent reports what playback does: ready, started, paused, resumed,
seeked, buffering started/ended, error, audio/subtitle track changed, ad break
started/ended, completed, closed. The beats are computed from them; a host can also send them
to its own analytics. Rules and limits: doc/player.md.
Chromecast and AirPlay
On Android and iOS phones and tablets, a Cast button appears once a Chromecast is found on the Wi-Fi: inside the native controls on Android (it fades with them), top right on iOS. Picking a TV hands the film over at the phone's position; the phone shows the poster, "Playing on …", play/pause, a seek bar and Stop casting, which hands playback back at the TV's position. Closing the player stops the TV too. If the TV refuses the film, the phone says so and plays on.
While the TV plays, the playback session keeps heartbeating (the film counts
as the phone's one stream: the TV's licence request carries the phone's
device_id and playback_session_id), beats keep counting played, paused and
stalled time, onPlaybackEvent reports the TV's states, and watch progress is
recorded.
Films need the EYZFlow Cast receiver (cast-receiver/): Google's standard
receiver cannot add the DRM access-token to licence requests. It is hosted
at https://stream.eyzflow.com/cast/index.html; register that URL in the
Google Cast console and pass its app id as castReceiverAppId. Without it only trailers offer Cast. See
cast-receiver/README.md.
AirPlay is the iPhone's own: Apple's player controls show the AirPlay button, and FairPlay keys for the Apple TV are requested by the phone.
Casting uses the Chromecast client in our copy of the native player (CASTV2
over the local network, no Google Cast SDK). Turn it off with
enableCast: false, or with features.chromecast: false in a player config.
Ads
On Android, Android TV and iOS the player plays ads from the player config:
features.ads on and a non-empty ads.adTagUrl (a VAST or VMAP tag).
Otherwise no ad request is made at all.
For a storefront viewer (drmAuthorization and storefrontId) the plan
decides too: the playback session, answered before the player loads, says
whether the plan plays ads for the title (ads: true when the plan requires
ads or the product is AVOD or FAST). ads: false plays no ads at all, no
pre-roll and no mid-rolls at the markers. When the session says nothing (no
session, an older backend, a failed request), the config decides as above.
The session's ad_targeting (e.g. plan=basic-ads, access=svod) is added
to the tag's cust_params; a key the tag already sets there keeps the tag's
value. A plan with ads cannot turn on ads the config has off.
Ads play through Google IMA
(interactive_media_ads), which shows the ad, its countdown, the skip button
when the ad allows one, and the click-through. Tizen plays no ads (there is no
IMA for it).
When ads play follows the ad break markers on the stream (dashboard: Stream →
Signals → Ad break), which the backend writes into the manifests as SCTE-35.
The player reads them from the HLS playlist it loads (EXT-X-DATERANGE), the
same rules as the web player:
- Stream with markers: the markers win. A marker at the start is a pre-roll; every other marker is a mid-roll, requested from the tag when playback reaches it, and played once. A marker passed by seeking (or by resuming further on) does not play. A VMAP tag's own schedule is dropped after each break: at a marker only its pre-roll plays, so a VMAP without one gives no ad there. Streams with markers need a VAST tag.
- Stream without markers: the tag decides. It is requested once before the content starts: a VAST gives a pre-roll, a VMAP its own pre-roll, mid-rolls and post-roll.
- Android: the pre-roll plays before the film's player loads, and during a mid-roll the film's player lets go of its video decoder (it reloads at the same position afterwards). TVs often have one hardware decoder, and while the film holds it the ad shows no picture, only IMA's countdown. iOS loads the film while the pre-roll plays.
- At a break the content waits until the ad starts, or until it turns out there is none (empty or failed tag, ad blocker, no answer within 12 s): then it plays on, with no error.
- During an ad the player's controls are hidden and out of reach (on Android
TV the remote cannot focus or seek them), the iOS Cast button is hidden, and
playback analytics leave the ad time out: no played, paused or startup time.
onPlaybackEventreportsPlaybackAdBreakStartedandPlaybackAdBreakEndedaround it. - No ads start while the video plays on AirPlay or a Chromecast. When casting hands playback back, the pre-roll and the breaks already played do not play again.
- Countdown before a mid-roll (
features.adCountdown, on when missing): a small corner notice, "Ad in 5" … "Ad in 1", for the last seconds before a mid-roll:ads.countdownSecondslong (whole seconds, 1–30; missing or not a number means 5, others are rounded and clamped), in the player's language (en, de, fr, nl; English otherwise). It counts down to the stream's markers, else to a VMAP's mid-roll cue points (never a pre-roll or post-roll). A marker passed by seeking counts down again when playback nears it later; a VMAP cue point played through does not after a rewind. It hides while paused, buffering or seeking, during an ad, on AirPlay, and once the viewer seeks past the break. It takes no touch or focus; on Android TV it stays up while the overlay is hidden.falseturns it off; an inlineconfigchange to either field applies without reloading the stream.
Host setup for ads: see step 7 under Host setup. The example app has an Ad tag URL field to try a tag without a config (Google's sample tags: developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags).
Player configs
configId loads a player config from the dashboard (Player → Configs) with
GET {api}/v1/player-configs/{configId}, as the web player does. The endpoint
is public (no auth) and the backend caches it for 60 s; the player keeps each
loaded config in memory for the life of the app. It is loaded before the key
check and playback start, and the player waits at most 5 s for it: an
unknown id, an error or no network plays with the player's defaults and shows
nothing to the viewer.
config: PlayerConfigOverride(…) is the web player's inline config prop:
what it gives wins over the remote config. Theme and features merge field by
field, cast and ads replace the remote ones, drm.parameters merge.
drmParameters, storefrontId and castReceiverAppId given in code win over
the config's.
What each field does on each app route (phones are the native controls on Android and iOS; Android TV and Tizen use the player's own TV overlay):
| Field | Phones | Android TV | Tizen |
|---|---|---|---|
theme.accentColor |
– | focused control (the skip button too), progress bar | same |
theme.textColor |
skip button text | title, times, icons, track rows | same |
theme.backgroundColor |
– | audio/subtitle panel | same |
theme.controlsBarColor |
skip button | shade behind the controls | same |
theme.borderRadius (px) |
skip button | track rows, focused progress bar, skip button | same |
features.controls |
– (the native controls hold Close) | false: no overlay; Back closes, OK plays/pauses, left/right and media keys skip | same |
features.autoHideControls |
– | false: the overlay stays up | same |
features.captions |
– (the native menu offers subtitles) | false: no subtitles, none offered | same |
features.loop |
yes | yes | – (AVPlay's player cannot loop) |
features.chromecast |
false: no Cast button | (TVs never cast) | (TVs never cast) |
features.airplay |
iOS: false keeps the video off AirPlay | – | – |
features.pip |
Android: false turns picture-in-picture off (iOS has none) | (off on TV) | – |
cast.receiverAppId |
the receiver films cast to, when castReceiverAppId is not set |
– | – |
features.ads, ads.adTagUrl |
ads through Google IMA, see Ads | same | – (no IMA on Tizen) |
features.adCountdown |
false: no "Ad in 5" notice before a mid-roll | same | – |
ads.countdownSeconds |
the notice's length, 1–30 s (default 5) | same | – |
features.skipButtons |
false: no "Skip intro / recap / credits" button (the signal events still come) | same | same |
skipButtonTypes.* |
intro, recap, openingCredits, closingCredits: which signals get a skip button (default: all but closing credits) |
same | same |
features.endScreen, endScreen.* |
false: no end screen; autoplaySeconds (0–30), showAt (credits/end), shrinkVideo, secondsBeforeEnd (0–120, without closing credits) tune it |
same | same |
drm.parameters |
into the DRM access-token; storefront_id also opens the playback session |
same | same |
Not honoured anywhere in the apps:
features.autoPlay: the app player opens on the viewer's Watch tap and always starts.features.muted: no app route has an unmute control (Media3's controls, the TV overlay), so a muted film would stay silent.features.qualitySelector: the app players have no quality menu.cast.androidReceiverCompatible,cast.autoJoinPolicy: options of the web Cast SDK.isProtected: the source type decides (EYZFlowFilmplays with DRM).
Without a config (or when it cannot be loaded) the TV overlay keeps its own
white-on-black look; the dashboard's default purple applies only when a
config is loaded or an inline theme is given. The backend stores no drm
section today, so drm.parameters (and a storefront in it) come only from an
inline config.
PlayerConfigClient, PlayerConfig and mergePlayerConfig are exported for
hosts that want the config themselves (lib/src/core/player_config.dart).
Headless
The pieces are exported for hosts that drive playback themselves:
PlayerLicenseClient / PlayerLicenseSession, PlaybackSessionClient,
buildAccessToken, BeatCollector / BeatTransport / HttpBeatSender,
PlaybackEventAdapter and PlaybackCoordinator. The code under
lib/src/core imports no Flutter.
End screen
Pass the films; the player shows them Netflix-style at the closing credits (the video shrinks into a corner) or after the film, counts down to the next stream and plays a picked one in place:
EYZFlowPlayer(
streamId: episode.streamId,
title: episode.title,
endScreen: EYZFlowEndScreen(
nextUp: EYZFlowEndScreenItem(streamId: next.streamId, title: next.title, poster: next.poster),
items: [
for (final f in similar)
EYZFlowEndScreenItem(streamId: f.streamId, title: f.title, poster: f.poster, duration: f.length),
],
onSelect: (selection) => router.replaceWatch(selection.item.streamId),
),
)
onSelect can call preventDefault() to handle the pick itself.
itemBuilder draws a film your way, title renames the row, and the
config's theme styles it. On TV it takes the remote's focus. For a layout of
your own, overlayBuilder is asked at each signal and after the end, and
wins when it returns a widget. See doc/player.md.
Layout
lib/eyzflow_player.dart the public API
lib/src/videoplayer_feature.dart, bloc/, player/, l10n/
the player
lib/src/core/ key check, sessions, access token, beats, player
configs (pure Dart)
lib/src/flutter/ EYZFlowPlayer, the coordinator, the error screen
lib/src/native/, android/, ios/
the native player for Android and iOS, based on
better_native_video_player (MIT, see
THIRD_PARTY_LICENSE_better_native_video_player)
doc/player.md how the player works
example/ loader app
The package has no dependency on any EYZFlow app code: the app passes in what it owns (the viewer's token, the storefront, where watch progress goes).
Watch progress
Films report their position (every 10 seconds, on pause and at the end) to a
WatchProgressStore the app provides, for example its watch-history client:
final class MyWatchHistory implements WatchProgressStore {
@override
Future<void> save({
required String catalogueId,
required double progressSeconds,
required bool completed,
}) => api.saveProgress(catalogueId, progressSeconds, completed);
}
A failed save is logged and never interrupts playback. Trailers record nothing.
Host setup
-
Optionally set the player's language (
EYZFlowPlayer(language:), orsetEYZFlowPlayerLanguagebefore building aVideoplayerFeatureView); without it the device's language is used when the player has it. -
Pass
isTv. The package does not detect the form factor. On Android it picks the D-pad overlay and theandroidtvplatform; Tizen always plays through AVPlay. -
Android: forward the activity lifecycle and picture-in-picture callbacks to
com.eyzflow.player.playback.AndroidPlaybackHost(seeexample/android/.../MainActivity.kt). The native player only plays while the host reports the activity visible.minSdk25 and theINTERNETpermission; a leanback launcher entry for Android TV. -
Tizen: the
internetanddrmplayprivileges intizen-manifest.xml, and a partner-signed certificate for DRM. Addshared_preferences_tizenandpackage_info_plus_tizen(or passdeviceIdStoreandappId); without them the device id lasts for the process only, so the device limit counts the TV again after each restart. -
iOS: deployment target 15.0, and for finding Chromecasts these Info.plist keys (iOS asks the viewer for local network access on the first scan):
<key>NSLocalNetworkUsageDescription</key> <string>Finds Chromecast devices on your Wi-Fi so you can watch on your TV.</string> <key>NSBonjourServices</key> <array><string>_googlecast._tcp</string></array>Android needs nothing extra: the multicast permission comes with the package.
-
Player key from an app: add each app to the key's "Allowed apps" as platform plus package name; matching is exact, so the Android TV build needs its own
androidtventry next toandroid. -
Ads (Google IMA): Android apps need core library desugaring, as in
example/android/app/build.gradle.kts(theACCESS_NETWORK_STATEpermission IMA wants comes with the package):android { compileOptions { isCoreLibraryDesugaringEnabled = true } } dependencies { coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5") }Without it the Android build fails, whether ads are used or not. iOS needs nothing extra.
endpoints moves the key check, sessions and beats (for a dev backend). Stream
and DRM licence URLs come from EYZFlowSource and stay on production, so a dev
session id would not match the production licence gate.
Known limits (v1)
- No bitrate, quality switch or dropped frame figures: the native players do
not report them yet. Beats send
nulland 0. - The position between state changes is estimated (last reported position plus time played), because the players report a position only with each event.
- The player token in the DRM header is the one from the start of playback: the native players take headers once. VOD licences are requested at start.
- Track changes made in the phone's native controls are not reported.
- Player configs: the fields and routes marked "–" in Player configs are not honoured, and nothing re-reads a config while a film plays. The theme and the AirPlay switch are not tried on a device yet.
- Casting: subtitles and audio tracks cannot be switched from the phone while the TV plays (the TV plays the default tracks), and a phone that leaves the Wi-Fi loses control of the TV. Not tested on a real Chromecast yet.
- FairPlay (iPhone, AirPlay) was rewritten to Apple's standard flow and is not tested on a device yet.
- Limit and key messages are English only.
- Ads: tried with Google's sample VAST and VMAP tags on an iPhone (pre-roll, mid-roll, post-roll) and a Philips Android TV (pre-roll, mid-roll); not on an Android phone, and not with ad break markers (no stream had any yet). After an Android mid-roll the film rebuffers for a few seconds. On Android TV the skip button may not be reachable with the remote (IMA's own view; the plugin has no TV focus handling); the sample ads were not skippable. There is no "ad in 5 s" notice before a mid-roll. The marker's planned pod length is not sent to the ad server: the tag decides the pod. Companion and overlay (non-linear) ads are not handled. While a VMAP on a stream without markers waits for its next break, IMA's container stays over the content (it lets touches through).
Develop
Needs Flutter ≥ 3.41.9.
flutter pub get
flutter analyze
flutter test
cd example
flutter run # Android phone/tablet, Android TV, iOS
flutter-tizen run -d <device> # Samsung TV
After editing an ARB file in lib/src/l10n, run flutter gen-l10n and commit
lib/src/l10n/generated.
The example app plays a stream with a bearer token, storefront and optional player key, and logs every playback event, beat, limit and refusal.
Licence
MIT, see LICENSE. The native player for Android and iOS (lib/src/native,
android/, ios/) is based on
better_native_video_player,
also MIT: THIRD_PARTY_LICENSE_better_native_video_player.
Libraries
- eyzflow_player
- The EYZFlow player for Flutter apps.