youtube_player

Play YouTube videos inline in Flutter, with the official IFrame Player API.
โšก Synchronous APIs, native WebViews, no platform channels, no webview_flutter.

pub platforms BSD-3 License


โœจ Highlights

โšก Synchronous APIs No await in sight. Native interop (JNI, FFI, js_interop) replaces platform channels, and player state is cached, so commands return void and getters return values (why?).
๐Ÿชถ Small native hosts A plain system WebView on Android, iOS and macOS, driven through Pigeon Native Interop (JNI on Android, FFI on iOS/macOS). Direct calls, no platform channels, no webview_flutter.
๐ŸŒ Web & Wasm On the web, YT.Player is driven directly through dart:js_interop. Works with --wasm and with cross-origin isolated pages.
๐Ÿ–ฅ๏ธ System fullscreen The fullscreen button uses the platform's own fullscreen. No Flutter-side re-parenting.
๐ŸŽจ Bring your own UI One controlsBuilder hook swaps YouTube's controls for your Flutter widgets.
๐Ÿชช Client identity built in Your app id is sent as Referer and origin, as YouTube requires. Goodbye, error 153.
๐Ÿ‘€ Polite autoplay Starts only when at least half the player is visible, one player at a time.
๐ŸŽ›๏ธ Tame the player UI Hide YouTube's own buttons, such as the logo, share or watch later (native platforms).
๐Ÿšฆ Navigation decisions Every link or button click asks onNavigationRequest first: let it through, block it, or handle it yourself, even asynchronously (native platforms).
๐Ÿ”’ Privacy first Privacy-enhanced mode (youtube-nocookie.com) is on by default.
๐Ÿ“ Captions, playlists, 360ยฐ Caption size and reload, playlists with loop and shuffle, spherical video controls.
Android iOS macOS Web
โœ… โœ… โœ… โœ… (JS & Wasm)

๐Ÿงญ The journey

  1. ๐Ÿ“ฆ Pack your bags: install and set up
  2. ๐ŸŽฌ Press play: your first video
  3. ๐ŸŽฎ Take the wheel: control playback
  4. ๐Ÿ“ก Listen in: react to state
  5. ๐ŸŽจ Make it yours: custom controls
  6. ๐Ÿ“บ Go big: fullscreen
  7. ๐Ÿงน Tidy the view: hide elements and decide where clicks go
  8. ๐Ÿงณ Coming from youtube_player_iframe?

๐Ÿ“ฆ 1. Pack your bags

flutter pub add youtube_player

Requirements: Dart 3.14+ and Flutter 3.50+.

Then a few platform notes:

  • ๐Ÿค– Android: nothing to do. The plugin declares INTERNET.
    • โœจ Optional: opt in to Hybrid Composition++ for the best rendering on API 34+ devices with Vulkan. Add this inside <application> in AndroidManifest.xml (or use flutter run --enable-hcpp while developing):

      <meta-data
          android:name="io.flutter.embedding.android.EnableHcpp"
          android:value="true" />
      

      The player uses HCPP whenever the device supports it and otherwise falls back to Texture Layer Hybrid Composition. The flag applies to every platform view in the app.

  • ๐ŸŽ iOS / macOS: requires Swift Package Manager (Flutter's default). CocoaPods is not supported.
  • ๐Ÿ’ป macOS: enable com.apple.security.network.client in your entitlements.
  • ๐ŸŒ Web with --wasm multithreading (COOP/COEP headers): set YoutubePlayerParams(webCredentialless: true).
  • ๐Ÿชช Custom client identity: set YoutubePlayerParams(appId: 'com.example.app'). It defaults to the Android application id or Apple bundle id.

๐ŸŽฌ 2. Press play

import 'package:youtube_player/youtube_player.dart';

final controller = YoutubePlayerController.fromVideoId(
  videoId: 'M7lc1UVf-VE',
  autoPlay: true,
  params: const YoutubePlayerParams(mute: true),
);

// In build():
YoutubePlayer(controller: controller);

// When done:
controller.close();

That's it, you're watching YouTube. ๐Ÿฟ

๐Ÿ‘€ About autoplay: fromVideoId(autoPlay: true) waits until at least half of the player is on screen, and only one player autoplays at a time. This follows YouTube's Required Minimum Functionality. Set YoutubePlayer.autoPlayWhenVisible: false to start immediately instead.

๐ŸŽฎ 3. Take the wheel

โšก Synchronous, thanks to native interop

Commands return void and getters return plain values. No await, and it's safe to read in build():

controller.seekTo(seconds: 30, allowSeekAhead: true);
final progress = controller.currentTime / controller.duration;

๐Ÿ”ฌ Why? Instead of platform channels (encode, queue, reply, Future), Pigeon's Native Interop calls straight into Kotlin over JNI and Swift over dart:ffi, and the web uses dart:js_interop. Player state is pushed back the same way and cached, so reads are instant. Only queries YouTube doesn't push (such as playlist, videoUrl and getOptions) still return a Future.

โฏ๏ธ Playback playVideo, pauseVideo, stopVideo, seekTo
๐Ÿ“ผ Loading loadVideoById, cueVideoById, loadVideoByUrl, cueVideoByUrl, loadVideo(url)
๐Ÿ“š Playlists loadPlaylist, cuePlaylist, nextVideo, previousVideo, playVideoAt, setLoop, setShuffle
๐Ÿ”Š Sound mute, unMute, setVolume (check supportsVolume: iOS only allows the hardware buttons)
๐Ÿ‡ Speed setPlaybackRate, playbackRate
๐Ÿ’ฌ Captions setCaptionsFontSize, reloadCaptions
๐ŸŒ 360ยฐ video sphericalProperties, setSphericalProperties
๐Ÿ–ผ๏ธ Thumbnails YoutubePlayerController.getThumbnail(videoId: ...)

๐Ÿ“ก 4. Listen in

controller.videoStateStream.listen((state) => print(state.position));
  • ๐Ÿงฑ Rebuild widgets with YoutubeValueBuilder.
  • ๐ŸŒณ Share a controller with a subtree via YoutubePlayerControllerProvider, then read it with context.ytController.
  • ๐Ÿšฆ value.isReady, value.isAutoplayBlocked and value.isFullScreen tell you what the player is up to.
  • ๐Ÿงฏ onLoadError(YoutubeLoadError) reports pages that fail to load.

๐ŸŽจ 5. Make it yours

Pass controlsBuilder to replace YouTube's controls with Flutter widgets:

YoutubePlayer(
  controller: controller,
  controlsBuilder: (context, value) => MyControls(value),
);

You don't need to set any params. With a controlsBuilder, the player is created with its native controls, keyboard shortcuts and fullscreen button turned off, and the iframe ignores pointer events, so every tap reaches your overlay. The overlay covers exactly the player's aspectRatio box. It rebuilds on every value change, and context.ytController works inside it.

Tip

  • The controls are fixed when the player is created, so decide on controlsBuilder before the player is first shown.
  • The overlay is not shown in native fullscreen. A custom fullscreen button can call enterFullScreen() on Android, macOS and the web; iPhone only allows the player's own button.

๐Ÿ“บ 6. Go big

The fullscreen button (showFullscreenButton, on by default) uses the platform's own fullscreen: WebKit on iOS/macOS, a custom view on Android, the browser on the web. controller.value.isFullScreen and setFullScreenListener reflect it.

enterFullScreen() returns whether the platform accepted the request. Some platforms only allow fullscreen from a user gesture, and iPhone only allows it from the player's own button. On Android, YoutubePlayerParams.fullscreenOrientation controls rotation.

๐Ÿงน 7. Tidy the view

๐Ÿ”— When the user taps the title, logo, channel or a share link, the link opens externally. A related or end-screen video loads in place instead.

๐Ÿ™ˆ Hide elements

On Android, iOS and macOS you can hide parts of YouTube's own player UI:

final controller = YoutubePlayerController.fromVideoId(
  videoId: 'tcodrIK2P_I',
  // Asked once per element when the player is created.
  elementVisibility: (element) => element != PlayerElement.watchLaterButton,
);

// Later, at runtime:
controller.setElementVisible(PlayerElement.title, false);

PlayerElement.values lists the built-in elements: logo, title, channel, share, watch later, copy link, more videos, related videos, end screen, cards and more. Use PlayerElement.custom('<css selector>') for anything else, and add it to YoutubePlayerParams.customElements so clicks on it are recognised.

๐Ÿšฆ Decide where clicks go

onNavigationRequest is asked before a link or button click goes anywhere. Each NavigationRequest tells you which element was clicked and the uri it leads to (null for in-player buttons such as share). Answer with a NavigationDecision:

Decision What happens
โœ… NavigationDecision.navigate The default: a related video loads in place, other links open externally, buttons act as usual.
โ›” NavigationDecision.prevent The click is blocked. Return this after handling the click yourself.

The handler can be async, so you can ask the user or open your own screen first:

final controller = YoutubePlayerController.fromVideoId(
  videoId: 'tcodrIK2P_I',
  onNavigationRequest: (request) async {
    // Keep users in the app when they tap the logo.
    if (request.element == PlayerElement.youtubeLogo) {
      return NavigationDecision.prevent;
    }
    // Open other links in your own in-app browser.
    if (request.uri case final uri?) {
      await openInAppBrowser(uri);
      return NavigationDecision.prevent;
    }
    return NavigationDecision.navigate;
  },
);

Notes:

  • The elements are matched by YouTube's undocumented CSS classes, so a built-in element can stop matching when YouTube changes its player.
  • On the web, the player is a cross-origin iframe that the page cannot reach into. Both hooks are ignored there, and links open in a new tab.

Warning

YouTube's API terms restrict obscuring the player's branding. Hiding elements is at your own risk.

๐Ÿงณ 8. Coming from youtube_player_iframe?

This package is the planned successor to youtube_player_iframe. Most code only needs the import changed to package:youtube_player/youtube_player.dart.

๐Ÿ—บ๏ธ Full migration map
youtube_player_iframe youtube_player
controller.webViewController, package:youtube_player_iframe/webview.dart Removed; there is no webview_flutter.
onWebResourceError onLoadError(YoutubeLoadError)
YoutubePlayerScaffold, orientation lists, autoFullScreen, enableFullScreenOnVerticalDrag Removed; fullscreen is native.
value.fullScreenOption.enabled value.isFullScreen
enterFullScreen({lock}) Future<bool> enterFullScreen()
YoutubePlayer(userAgent:) YoutubePlayerParams(userAgent:)
YoutubePlayerParams(color: 'white') color: .white (ProgressBarColor)
YoutubePlayerParams(enableJavaScript:) Removed (always on).
cuePlaylist(list:, listType: ListType.playlist) ListType has playlist and userUploads (search was removed by YouTube).
getCurrentPositionStream() videoStateStream
YoutubeError.sameAsNotEmbeddable* Merged into notEmbeddable; new missingClientIdentity (153).
showFullscreenButton defaulted to false Defaults to true.
YoutubePlayerThumbnail / player thumbnail placeholder Removed; build one with getThumbnail.
showControls: false + pointerEvents: none for custom controls Pass YoutubePlayer(controlsBuilder:); it sets both.
Player created on the first controller call Created when a YoutubePlayer first shows it; earlier calls are queued.
Commands (playVideo(), seekTo(), mute(), โ€ฆ) and close() return Future<void> They return void; drop the await.
await controller.currentTime, volume, isMuted, playbackRate, playerState, duration, videoLoadedFraction, videoData Synchronous getters. Queries such as playlist and videoUrl still return a Future.

๐Ÿ†• New in this package: setCaptionsFontSize, reloadCaptions, getOptions, sphericalProperties / setSphericalProperties, apiChangeStream, value.isAutoplayBlocked, value.isReady.


๐Ÿ You made it! Found a bug or have an idea? Open an issue ๐Ÿ’ฌ

Libraries

youtube_player
Play YouTube videos inline in Flutter, through the official IFrame Player API.