Skip to main content

yu_video_player 1.0.3 copy "yu_video_player: ^1.0.3" to clipboard
yu_video_player: ^1.0.3 copied to clipboard

Cache the first N bytes of a remote video to disk on Android and iOS, so the opening seconds play from disk while the rest streams from the network.

yu_video_player #

English | 简体中文

Cache the opening bytes of a remote video to disk, so the first seconds play from disk while the rest keeps streaming from the network.

Designed for the "fast first frame" case: prefetch a small prefix before the user taps play, and the player still behaves like a normal online player after that prefix.

Platform support #

Platform Implementation Minimum
Android DataSource (Media3) API 21
iOS AVAssetResourceLoader iOS 15

Neither platform needs host-side configuration:

  • Android uses no local proxy, so no network_security_config is required.
  • iOS uses a custom URL scheme, so no ATS exception is required.

Installation #

dependencies:
  yu_video_player: ^1.0.3

Requires Flutter 3.44 or later (the release where Swift Package Manager became the default dependency manager on iOS).

iOS is supported through SwiftPM only; no podspec is shipped. The CocoaPods trunk went read-only on 2026-12-02, so projects still on CocoaPods should migrate first.

Repository layout #

The native cores are not part of this package. This package is a bridge over two separately published packages:

Repository Contents Distribution
yu_video_player Dart API, channels, PlatformView pub.dev
yu_video_player_ios iOS prefix cache (AVAssetResourceLoader) git tag, consumed by SwiftPM
yu_video_player_android Android prefix cache (Media3 DataSource) Maven (JitPack / Central)

Change native logic in the matching core repository; change channels or the Dart API here.

For local development the iOS dependency points at the local core checkout through coreDependency in ios/yu_video_player/Package.swift; run tool/switch_core_dependency.sh remote before publishing. On Android, local integration resolves through mavenLocal(), so run ./gradlew publishToMavenLocal in the core repository first.

Usage #

import 'package:yu_video_player/yu_video_player.dart';

// 1. Configure capacity (optional; defaults to 1GB total, 16MB per video)
await YUVideoPrefixCache.configure(
  maxTotalBytes: 1024 * 1024 * 1024,
  maxBytesPerVideo: 16 * 1024 * 1024,
);

// 2. Prefetch when the detail page becomes visible
await YUVideoPrefixCache.prefetch('3412', playUrl);

// 3. Inspect usage
final stats = await YUVideoPrefixCache.stats();
debugPrint('${stats.count} entries, ${stats.totalBytes ~/ 1024 ~/ 1024} MB');

// 4. List entries for a settings screen
for (final entry in await YUVideoPrefixCache.entries()) {
  debugPrint('${entry.key} ${entry.bytes} ${entry.progress}');
}

// 5. Clear
await YUVideoPrefixCache.clear('3412');
await YUVideoPrefixCache.clearAll();

Player #

YUPlayerController and YUVideoPlayer wrap the native PlatformView on both platforms, and the data source goes through the cache path automatically:

final controller = YUPlayerController(vid: 'dom01', url: playUrl, autoPlay: true);
// Mounting creates the view and starts playback
Column(children: [AspectRatio(aspectRatio: 16 / 9, child: YUVideoPlayer(controller: controller))]);

controller.play();
controller.seekTo(const Duration(seconds: 3));
controller.setVolume(0);      // 0 = muted, playback continues
controller.setSpeed(1.5);     // 0.25 ~ 4.0

Switching source during playback #

setSource replaces only the native item or MediaSource. The player instance and the view are kept, so there is no black gap from rebuilding the whole view:

// Switch to another video
await controller.setSource(vid: 'dom02', url: nextUrl);

// Refresh the signature or CDN address only: same vid, same cache entry
await controller.setSource(vid: 'dom01', url: freshSignedUrl);

// Same arguments = retry in place
await controller.setSource(vid: 'dom01', url: playUrl);

value resets to the uninitialized state on switch (duration, size and position are cleared) and is filled in when the native ready event arrives. Volume and speed are player-level settings and are not affected.

Native integration #

prefetch only writes bytes to disk. To make a player use that cache, swap its data source on the native side:

  • Android: replace MediaItem with YUVideoCache.mediaSource(context, vid, url), call it once per video switch, and pair acquire with release.
  • iOS: replace AVPlayerItem(url:) with YUVideoCache.playerItem(vid:realURL:), and call YUVideoCache.release(vid:) when leaving the player screen.

Detailed steps live in the repository docs:

  • docs/android-缓存实现说明.md
  • docs/ios-缓存接入说明.md
  • docs/ios-缓存拦截方案.md

How it works #

Player requests bytes=N-
  |- N inside the cached prefix  -> read from disk
  |- N past the prefix           -> fetch from origin
  '- N spans the boundary        -> read disk, then continue from origin
                                      within the same request

The cache is keyed by vid, not by URL. Signature refreshes and CDN switches do not affect cache hits.

Known limitations #

  • Only the range starting at 0 is cached; seeking back outside the prefix downloads again.
  • Writes are sequential and append-only, so a seek into the middle at the very start of playback is not persisted.
  • HLS segment-level caching is not implemented.
  • AirPlay is not supported (iOS custom URL schemes cannot be sent to an external device).

License #

MIT

2
likes
160
points
--
downloads

Documentation

API reference

Publisher

unverified uploader

Cache the first N bytes of a remote video to disk on Android and iOS, so the opening seconds play from disk while the rest streams from the network.

Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

flutter

More

Packages that depend on yu_video_player

Packages that implement yu_video_player