Cast to Chromecast
Cast FastPix videos from your Flutter app to a Chromecast receiver. Casting is not screen mirroring: the receiver fetches the stream itself, directly from FastPix, and FastPixCastController only sends it commands. Three things follow from that:
- The stream URL must be reachable by the receiver, so authentication travels in the URL.
FastPixPlayerDataSource.urlalready carries the playback token as a query parameter, butheadersare dropped, because the receiver makes its own request. - Local and remote playback are mutually exclusive. Use
startCastingFromandstopCastingToto move between them rather than driving both players by hand. - DRM streams cannot be cast through Google’s Default Media Receiver. See DRM on Chromecast.
Casting is supported on Android and iOS. On any other platform the controller settles on FastPixCastState.unavailable instead of throwing, so you can build cast UI unconditionally and let the state hide it.
Platform setup
Android
Add the discovery permissions and the Cast framework configuration to android/app/src/main/AndroidManifest.xml:
The SDK makes the runtime NEARBY_WIFI_DEVICES request itself from startDiscovery(), once per app process, so a viewer who declined is not prompted again on every screen. Casting also needs Google Play Services. When it is missing or too old, the failure arrives as FP_CAST_PLAY_SERVICES_UNAVAILABLE.
iOS
Add the local network keys to ios/Runner/Info.plist. NSBonjourServices must list the Cast service and, when you use a custom receiver, the service for its application ID:
On iOS, when the local network permission is denied, discovery simply returns zero devices, with no callback.
Quick start
Move playback between the phone and the TV
startCastingFrom connects, pauses the local player, and loads the stream on the receiver at the position playback had reached. The connection is established before local playback is touched, so a receiver that fails to connect leaves the phone playing where it was. If the receiver connects but the stream fails to load, the session is torn down and the error is rethrown, so a load failure arrives as an exception, not as false. Local playback resumes only if it was playing when casting started.
Keep the FastPixPlayer widget mounted while casting. Hide it rather than removing it. Unmounting tears down the platform player, and stopCastingTo then has nothing to hand playback back to. It reports FP_CAST_RESUME_UNAVAILABLE, and the session still ends cleanly.
A session and the discovered device list can change from outside the app, such as the Google Home app, another sender, or the TV powering off. Treat stateStream and the cast events as the single source of truth rather than assuming a command succeeded.
Control the receiver
remoteVolume is what this app last asked for, not ground truth. The Cast plugin provides no callback for volume, so changes made from the TV remote, the Google Home app, or the phone’s volume buttons are not reflected.
To end the session entirely:
Subtitles while casting
Subtitle tracks come from two places and are reported the same way. Tracks declared in FastPixPlayerDataSource.subtitles are sent to the receiver on load, and tracks inside the HLS manifest are found by the receiver. Both appear in textTracks only once the receiver has reported a media status.
The selection is not recorded locally. The receiver confirms it in its next media status, which is also how a change made from a TV remote or another sender arrives.
Cast events
Cast events are ordinary FastPixPlayerEvents. Pass the player’s event manager to the constructor to have them reach the same listeners as playback events:
castError deliberately does not extend FastPixPlayerErrorEvent: a cast failure is not a local playback failure, and the phone may still be playing.
Handle cast errors
The most recent failure stays on cast.lastError, so UI that mounts after the failure can still render it. Branch on the classification rather than on the message:
An empty device list on Android 13+ is usually the nearby devices permission. requiresNearbyDevicesPermission tells you whether that explanation can apply on the current device:
Cast error codes
DRM on Chromecast
Chromecast receivers speak Widevine only, never FairPlay, and Google’s Default Media Receiver cannot perform a license request at all. Loading a DRM protected source without a custom receiver is refused: loadMedia throws UnsupportedError and emits FP_CAST_DRM_UNSUPPORTED.
The refusal happens at load time, not before connecting. startCastingFrom connects to the receiver and pauses local playback first, so a DRM source tears the fresh session down again on the way out. Check for DRM yourself before offering the cast button if you would rather the receiver were never woken.
With a custom receiver configured through appId, the SDK sends the license details in the media’s customData, using the Widevine license URL derived from the playback ID even when the phone plays the same title locally through FairPlay:
Your receiver application reads loadRequest.media.customData.licenseUrl and configures its playback manager with it. The FastPix license endpoint carries its token as a query parameter, so the receiver needs no custom headers.
Segment format
A Cast receiver is a web player and must know how the segments are packaged before it can build a playback pipeline. When the manifest does not make that obvious, the receiver assumes MPEG-TS, and an fMP4/CMAF stream then connects, displays its title, and never starts playing, with no error on either side.
If casting connects but nothing plays, this is almost always the cause:
Modern packaging is fMP4/CMAF, and any stream serving both Widevine and FairPlay from one source, which is how FastPix DRM works, is CMAF. FastPixCastSegmentFormat.auto (the default) sends no hint and is correct for plain MPEG-TS streams.
What does not survive the trip
Because the receiver fetches and renders the stream itself, several data source options have no effect while casting:
headersare dropped. Authentication has to be in the URL, which the FastPix playback token already is.- Resolution hints (
resolution,minResolution,maxResolution,renditionOrder) are sent as URL parameters, but adaptive switching is then the receiver’s decision. cacheEnabled,loop, andendAtare local player behaviors with no receiver equivalent.
Lifecycle
dispose() releases every subscription and stream the controller opened, but deliberately does not end a live session: a viewer who started casting expects the TV to keep playing when they leave the player screen. Call disconnect() first if the session should stop with the screen. For the same reason, hold the cast controller at app scope rather than rebuilding it per screen.
What’s next
- Play a DRM-protected video for how DRM works on the phone and on a custom receiver.
- Manage a playlist to queue videos for playback.