lychee_player

pub pub points CI License: MIT

A video and audio player for Flutter on Android, iOS, macOS, Windows and Linux. It decodes on the GPU with each platform's own decoders and shows frames as Flutter textures, without a copy where the platform allows.

  • Hardware decoding: MediaCodec, VideoToolbox, Media Foundation and D3D11VA, VAAPI; software when the hardware gives up.
  • MP4, Matroska/WebM, MPEG-TS and HLS (adaptive, AES-128, alternate audio and subtitles), MP3, FLAC, PCM/float WAV, ADTS and Ogg. Windows also plays ASF (WMV/WMA). FLV H.264/AAC, AVI and MPEG-PS have native readers too; AVI and MPEG-PS depend on installed system codecs. Ogg Vorbis needs FFmpeg on Apple and Windows.
  • Accurate seeking, rate 0.25x to 4x with pitch kept, gapless looping, track selection.
  • Text and bitmap subtitles, metadata and cover art, HDR tone-mapped to SDR.

Install

flutter pub add lychee_player

Then set the minimums under Platform setup.

Usage

import 'package:flutter/widgets.dart';
import 'package:lychee_player/lychee_player.dart';

class VideoPage extends StatefulWidget {
  const VideoPage({super.key});

  @override
  State<VideoPage> createState() => _VideoPageState();
}

class _VideoPageState extends State<VideoPage> {
  LycheePlayer? _player;

  @override
  void initState() {
    super.initState();
    LycheePlayer.create().then((player) {
      if (!mounted) {
        player.dispose();
        return;
      }
      setState(() => _player = player);
      player.open('https://example.com/video.mp4');
      player.play();
    });
  }

  @override
  void dispose() {
    _player?.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final player = _player;
    return player == null ? const SizedBox() : LycheeVideo(player);
  }
}

LycheePlayer is a ValueNotifier<LycheePlayerValue>: listen to it, or use a ValueListenableBuilder, for the state, position, duration, buffered, tracks and the rest. LycheeVideo keeps the video's aspect ratio and rotation (fit changes the scaling).

Call Does
LycheePlayer.create(hardwareDecoding: true) A new player.
open(url) Opens a file path or http(s) URL; replaces the current media.
play(), pause(), seek(Duration) Seeks are ignored while value.seekable is false.
setRate(1.5), setVolume(0.5), setLooping(true) Rate is 0.25 to 4, pitch kept.
fade(0, Duration(seconds: 2)), setGain(-6.5, peak: 0.9) A smooth volume ramp; a gain in dB (ReplayGain), boosts limited so they do not clip.
getAudioSamples(1024), getAudioSpectrum(512) What the output plays now, for visualizers.
selectTrack(type, index) An index into value.tracks; null turns that type off.
getMetadata('title') A container tag; value.artwork has the cover.
getStats() Decoders, hardware or not, decoded, rendered and dropped frames, bytes read, download rate, startup, rebuffering and seek times.
dispose() Required: releases the native player.

Subtitles: text arrives in value.subtitle for your app to draw over the video. Bitmap subtitles (PGS; DVB and VobSub with FFmpeg) arrive in value.subtitlePictures, and LycheeVideo draws them itself.

Android TV video output

LycheeVideo(player) uses a Flutter texture by default (surfaceView: false). Pass LycheeVideo(player, surfaceView: true) on Android to send video to a native SurfaceView below Flutter. It can retain 4K panel resolution when the TV renders its Flutter UI at 1080p, and passes HDR to the display. This implementation needs a TextureView-backed Flutter activity:

import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.android.FlutterTextureView
import io.flutter.embedding.android.RenderMode

class MainActivity : FlutterActivity() {
    override fun getRenderMode(): RenderMode = RenderMode.texture
    override fun onFlutterTextureViewCreated(view: FlutterTextureView) {
        super.onFlutterTextureViewCreated(view)
        view.isOpaque = false
    }
}

Widgets painted above the video remain visible; the video rectangle clears widgets painted behind it. Entering this mode can briefly rebuffer. Use one native view per player with finite, bounded constraints. Quarter-turn rotation is applied natively for MediaCodec (hardware or system software) and CPU RGBA frames. Other platforms continue using their texture bridge.

Without onSurfaceError, activities without this setup, unbounded layouts, and non-quarter-turn rotations fall back to the Flutter texture. With onSurfaceError, invalid layout, unsupported rotation, missing host setup, surface creation exceeding five seconds while foregrounded, and window bind/post failures show an actionable error and call onSurfaceError without falling back to a texture; hosts can pause and expose retry UI. Backgrounding and Activity detach suspend output without switching to a texture or timing out; resume recreates the SurfaceView.

The host regression test sdk/android/lychee/src/test/cpp/run.sh exercises the production CPU copy, rotation and failure contracts with a window double. It does not verify Android compositor pixels. Native device validation is still required for CPU/software-codec and hardware-codec output, rotated frames, crop, and foreground/configuration changes.

Players your native code creates

Native code can create players through the C ABI (lychee/lychee.h), for example to feed a live stream with lychee_player_open_live(), and show them in a Flutter Texture. Create the player with the texture's frame types, set it on the texture, and set none before destroying it; the headers say which thread each call needs.

Platform Texture Link the core
iOS, macOS LycheeHostTexture (import lychee_player) Through the plugin
Linux lychee_host_texture_* (lychee_player/lychee_host_texture.h) lychee::lychee in CMake
Windows LycheeHostTexture* (lychee_player/lychee_host_texture.h) lychee::lychee in CMake
Android Render to a Surface with lychee_player_set_video_surface() lychee through prefab

Platform setup

Platform Minimum Set in your app
Android API 26 minSdk = 26 in android/app/build.gradle.kts
iOS 16.0 platform :ios, '16.0' in ios/Podfile and the Runner's deployment target
macOS 11.0 platform :osx, '11.0' in macos/Podfile and the Runner's deployment target
Windows 10 Visual Studio 2022
Linux Ubuntu 22.04 See below

macOS: Flutter's template runs the app in the App Sandbox. Add com.apple.security.network.client to both entitlements files to play URLs. Local files must be ones the user picked (file_selector) or in the app's container; other paths fail with "Operation not permitted".

Linux: building needs libepoxy-dev, libpulse-dev and libpng-dev. At run time the app needs libgtk-3-0, libpulse0, libpng16-16, and for FFmpeg libva2, libva-drm2, libdrm2, libgnutls30 and zlib1g. With NVIDIA's driver, an app that quits while a video plays can crash in libnvidia-eglcore; destroy the window in the runner's shutdown, as the example's runner does.

FFmpeg

FFmpeg is off by default on Android, iOS, macOS and Windows: the app is smaller and the system's decoders play MP4, Matroska/WebM, MPEG-TS, HLS and standalone audio (MP3, FLAC, PCM/float WAV, ADTS and Ogg Opus/FLAC; Android also plays Ogg Vorbis). Windows ASF uses system decoders in both modes. FLV H.264/AAC also plays without FFmpeg; AVI and MPEG-PS need system support for their video and audio codecs. Turn FFmpeg on for other formats or codecs the system lacks. Linux always uses FFmpeg.

For one build, set the environment variable:

LYCHEE_WITH_FFMPEG=ON flutter build apk

To keep the choice in the app, set it once per platform (the environment variable still wins):

Platform File Setting
Android android/gradle.properties LYCHEE_WITH_FFMPEG=ON
Windows windows/CMakeLists.txt, before include(flutter/generated_plugins.cmake) set(LYCHEE_WITH_FFMPEG ON)
iOS, macOS with CocoaPods ios/Podfile, macos/Podfile, before flutter_install_all_*_pods ENV['LYCHEE_WITH_FFMPEG'] ||= 'ON'
iOS, macOS with Swift Package Manager Flutter/LycheePlayer.xcconfig, one-time setup below LYCHEE_PLAYER_FFMPEG = ON

Run flutter clean after switching.

One-time setup for Swift Package Manager

Swift Package Manager resolves the plugin before the app's settings are known, so a build phase picks the core afterwards:

  1. Copy tool/lychee_apple.sh from the example into your app's tool/.

  2. Create ios/Flutter/LycheePlayer.xcconfig and macos/Flutter/LycheePlayer.xcconfig with LYCHEE_PLAYER_FFMPEG = ON, and add #include "LycheePlayer.xcconfig" to iOS Flutter/Debug.xcconfig and Release.xcconfig, and macOS Flutter/Flutter-Debug.xcconfig and Flutter-Release.xcconfig.

  3. In Xcode, append this line to the Runner target's final Flutter embed phase (iOS: Thin Binary; macOS: the phase running macos_assemble.sh embed):

    /bin/bash "$FLUTTER_APPLICATION_PATH/tool/lychee_apple.sh"
    

    and add this to the phase's Output Files, so incremental builds sign the app again:

    $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/lychee_player_backend
    
  4. Keep User Script Sandboxing off for Runner, as Flutter's template has it.

Swift Package Manager builds need Swift 6.1. An environment variable set in an Xcode scheme reaches only the launched app, not the build.

Downloads during the build

Android, iOS and macOS download the prebuilt core, and Linux (and Windows with FFmpeg on) download FFmpeg, from this version's GitHub release, checked against SHA-256s pinned in the package. Where GitHub is slow or blocked, point LYCHEE_PREBUILT_URL at a mirror of https://github.com/boyan01/lychee_player/releases/download (https for Swift Package Manager). On Windows and Linux, LYCHEE_FFMPEG_ROOT uses a local FFmpeg instead.

License

MIT. FFmpeg is LGPL, built by this project and linked dynamically; each release attaches its source. Apps must ship the notices in core/THIRD_PARTY_NOTICES of this package, which the prebuilt core already carries (lychee.framework, and META-INF/lychee/THIRD_PARTY_NOTICES in Android APKs).

Source, roadmap and the native SDKs (Swift, Kotlin, Rust): https://github.com/boyan01/lychee_player

Libraries

lychee_player