lychee_player
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:
-
Copy
tool/lychee_apple.shfrom the example into your app'stool/. -
Create
ios/Flutter/LycheePlayer.xcconfigandmacos/Flutter/LycheePlayer.xcconfigwithLYCHEE_PLAYER_FFMPEG = ON, and add#include "LycheePlayer.xcconfig"to iOSFlutter/Debug.xcconfigandRelease.xcconfig, and macOSFlutter/Flutter-Debug.xcconfigandFlutter-Release.xcconfig. -
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 -
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