gstplayer

gstplayer

English | 简体中文

A polished, all-in-one Flutter video player with a beautiful built-in UI and broad format support — most local and network codecs via GStreamer (native C core + Dart FFI), rendered into Flutter external Texture widgets (GStreamer appsink on Apple/desktop; glimagesink + SurfaceProducer on Android).

Supported platforms: Android, iOS, macOS, Windows, Linux.

Android / iOS / macOS: GStreamer SDK is downloaded automatically on the first build. Windows / Linux: install GStreamer once on the machine (see below).

Scope: video playback — open / play / pause / stop / seek / volume / mute / speed / looping, plus state / position / duration / resolution / buffering / EOS / error reporting, scrub preview, poster / last-frame, external subtitles (SRT/VTT overlay), danmaku overlay, and screenshots. It does not do recording, streaming (as a server), or system picture-in-picture.

Screenshots

Android   iOS   macOS   macOS

Android · iOS · macOS,linux (example app)

Table of contents

Features

  • Local files, Flutter assets, and network URLs (http(s)://, rtsp://, ...).
  • Play / pause / stop / seek / looping.
  • EOS replay and looping reload the current VideoSource via open() (same path as switching sources) for local files and progressive network streams (MOV / AVI / MP4); scrub seeks use accurate positioning by default.
  • Volume (popup vertical slider with live 0–100 readout), mute, and playback speed.
  • Bilibili-inspired two-row chrome: pink progress (#FB7299), remaining time, speed / settings / volume / fullscreen, then danmaku input + CC; auto-hiding.
  • Side lock on the same row as the center play/pause (far right). Locking hides the bottom chrome and ignores surface gestures / keyboard shortcuts; tap only shows or hides the unlock button.
  • Two-level settings: mirror, loop, autoplay, play-next, 16:9 / 4:3, hide black bars, lights-off, audio tracks. Chrome copy is zh / en via language.
  • Mobile surface gestures (inline and fullscreen): horizontal seek, left brightness / right volume (HUD shows percent). Disabled while controls are locked.
  • Progress-bar scrub thumbnail preview (external WebVTT + sprite / frame list).
  • Poster image and keep-last-frame after EOS.
  • External subtitle overlay (SRT/WebVTT via SubtitleParser). Embedded subtitle tracks are enumerable via tracks / selectTrack; there is no in-pipeline subtitle renderer or settings UI for them.
  • Danmaku (bullet comment) overlay driven by app-supplied DanmakuItem cues.
  • Frame capture via Settings → Screenshot (onScreenshot — host saves PNG) and one-shot covers (captureThumbnail). Set showCaptureButton: false to hide the settings entry.
  • Reactive state via ChangeNotifier plain getters: state, position, duration, video size, aspect ratio, buffering %, volume, speed, looping, muted, and errors. Rebuild with ListenableBuilder / addListener.
  • A drop-in GstVideoView widget with a built-in, auto-hiding, themeable control bar (Material / Cupertino / adaptive via material_ui; default theme accent matches Bilibili pink).
  • GPU-friendly video via Flutter Texture (Android GL into SurfaceProducer; Apple/desktop pixel-buffer textures fed from GStreamer appsink).

Platform support

Platform Min version Architectures GStreamer
Android API 24 (7.0) arm64-v8a, armeabi-v7a, x86, x86_64 Auto on first build
iOS 13.0 Physical arm64 device (no Simulator) Auto on first SPM resolve / build
macOS 10.13 x86_64 / arm64 Auto on first SPM resolve / build
Windows 10+ x86_64 Install once on the machine (below)
Linux — x86_64 Install once on the machine (below)

Apple Silicon iOS Simulator is not supported (the current plugin integration uses only the arm64 device slice).

When to use kinetic_player instead

If your app targets Android / iOS / macOS / Web and you want a smaller binary that leans on each platform’s native player, prefer kinetic_player (GitHub).

Use gstplayer when you need a GStreamer pipeline (especially Windows / Linux, or codecs / protocols that benefit from GStreamer).

Prerequisites

Install these once on the machine that builds the app. The GStreamer SDK itself is still auto-downloaded for Android / iOS / macOS on first build.

All platforms

  • Flutter matching this plugin (sdk: ^3.13.0, flutter: ">=3.47.0" in pubspec.yaml)
  • Network access on the first Android / iOS / macOS build (GStreamer cache)

Android

  • Android SDK + NDK (normal Flutter Android setup; Gradle runs ndk-build for libgstreamer_android.so)
  • HTTPS / HTTP uses official souphttpsrc from the GStreamer Android SDK (linked into the umbrella at build time — no Rust toolchain)

iOS

  • macOS with Xcode (Command Line Tools)
  • A physical iPhone / iPad (Simulator is not supported)
  • First build downloads the GStreamer iOS SDK automatically (~1.1GB)

macOS

  • Xcode
  • First build downloads the official universal GStreamer.framework automatically
  • Enable Swift Package Manager in the host pubspec.yaml (see Installation); no CocoaPods Podfile is required

Windows / Linux

Host GStreamer + pkg-config — see Windows & Linux host SDK.

Installation

1. Add the dependency

dependencies:
  gstplayer: ^0.0.7
flutter pub get

2. Run your app

flutter run

That is enough for Android / iOS / macOS (after Prerequisites):

  • The first build downloads the official GStreamer SDK into ~/Library/Caches/gstplayer/... (needs network once; no sudo).
  • Later builds reuse the cache.
  • No manual GStreamer installer for those platforms.

iOS: use a physical device (flutter run -d <device>). Simulator is not supported.

Enable Swift Package Manager in the host pubspec.yaml (the plugin already sets this for its own package):

flutter:
  config:
    enable-swift-package-manager: true

The example app is SPM-only (no ios/Podfile or macos/Podfile).

macOS (SPM, one-time): Package.swift links GStreamer.framework, but nothing copies it into the .app. Add an Xcode Run Script build phase on Runner named [gstplayer] Embed GStreamer Framework (after Embed Frameworks):

set -euo pipefail
PLUGINS_JSON="${SRCROOT}/../.flutter-plugins-dependencies"
PLUGIN_MACOS="$(python3 -c "
import json, sys
plugins = json.load(open(sys.argv[1]))['plugins']['macos']
print(next(p['path'] for p in plugins if p['name'] == 'gstplayer') + '/macos')
" "$PLUGINS_JSON")"
# shellcheck source=/dev/null
source "${PLUGIN_MACOS}/scripts/gstreamer_paths.sh"
bash "${PLUGIN_MACOS}/scripts/embed_gstreamer_framework.sh"

Set the phase input to the two scripts under macos/scripts/ and the output to ${TARGET_BUILD_DIR}/${FRAMEWORKS_FOLDER_PATH}/GStreamer.framework. See example/macos/Runner.xcodeproj.

CocoaPods-only hosts still get the framework via vendored_frameworks. If a host keeps a macos/Podfile under SPM hybrid mode, install_gstreamer_embed_script! in macos/gstreamer_podfile_helper.rb injects the same Run Script.

Windows / Linux: install the host GStreamer SDK once — see Windows & Linux host SDK.

Quick start

import 'dart:async';

import 'package:material_ui/material_ui.dart';
import 'package:gstplayer/gstplayer.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // Kickoff only (under 50ms); gst_init continues in the background.
  unawaited(GstPlayer.initialize());
  runApp(const MyApp());
}

class PlayerPage extends StatefulWidget {
  const PlayerPage({super.key});
  @override
  State<PlayerPage> createState() => _PlayerPageState();
}

class _PlayerPageState extends State<PlayerPage> {
  final controller = GstPlayerController();

  @override
  void initState() {
    super.initState();
    controller.initialize().then((_) {
      controller.open(
        VideoSource.network('https://example.com/video.mp4'),
        autoPlay: true,
      );
    });
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: GstVideoView(
        controller: controller,
        language: GstPlayerLanguage.zh, // or GstPlayerLanguage.en
      ),
    );
  }
}

Other sources:

await controller.open(const VideoSource.file('/path/to/video.mp4'));
await controller.open(const VideoSource.asset('assets/sample.mp4'));

Usage notes

  1. Call GstPlayer.initialize() once early (unawaited before runApp is fine).
  2. One GstPlayerController per surface; always dispose() it.
  3. Read playback state inside ListenableBuilder / addListener.
  4. First Android / iOS / macOS build needs network for the SDK cache.
  5. On Android, play() waits for a Flutter Texture (GstVideoView). Calling play without a view holds auto-play until the surface exists.

Network permissions

Local files and Flutter assets need no extra setup.

Platform For http(s):// / rtsp://
Android Ensure INTERNET in AndroidManifest.xml (Flutter templates usually already have it). Optional: android:usesCleartextTraffic="true" for plain http://.
iOS Nothing. GStreamer does not use ATS / NSURLSession. Device only.
macOS With App Sandbox, keep com.apple.security.network.client in Runner entitlements (Flutter templates usually already have it).
Windows / Linux No app permission. Install GStreamer on the development machine; Windows bundles include its runtime, while Linux target machines need runtime plugins (below).

HTTPS verifies server certificates by default. Invalid or untrusted certificates cause playback to fail. For a source that explicitly requires unverified TLS, use VideoSource.network(url, allowInsecureTls: true). The option applies to both playback and thumbnails.

Windows & Linux host SDK

Only these platforms need a one-time machine install. Android / iOS / macOS do not.

Windows

  1. Install gstreamer-1.0-msvc-x86_64-<version>.exe from gstreamer.freedesktop.org/download/ with “Runtime and development headers”.
  2. Put pkg-config on PATH (e.g. choco install pkgconfiglite).
  3. GUI install sets GSTREAMER_1_0_ROOT_MSVC_X86_64; set it yourself for silent installs.

Builds require CMake 3.21+ and a C11-capable MSVC (Visual Studio 2019 16.8+). Install the complete runtime, including playback, decoder and network plugins and GIO/TLS backends. Flutter's install step copies bin/*.dll beside the executable and installs plugins/modules into gstplayer/lib/gstreamer-1.0/ and gstplayer/lib/gio/modules/. Distribute the entire build output directory, including those subdirectories; end users do not need the SDK installed. Runtime discovery prefers the bundled directories, then falls back to the host SDK. Explicit GST_PLUGIN_SYSTEM_PATH (including its _1_0 variant), GIO_MODULE_DIR, and GST_REGISTRY (including its _1_0 variant) are preserved.

Linux

sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
  gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav \
  libgtk-3-dev

Linux target machines also need the runtime plugins above; development headers are only required to build. Plugin and GIO module discovery uses the system GStreamer/GLib defaults and host environment settings without hardcoded distro paths. The registry is cached under $XDG_CACHE_HOME/gstplayer/ (default ~/.cache/gstplayer/), preserving explicit GST_REGISTRY, GST_REGISTRY_1_0, and GST_REGISTRY_FORK settings. Runtime behavior (HTTP headers, User-Agent, duration, screenshot) matches macOS once the plugins above are installed.

API reference

GstPlayer.initialize()

Kickoff-only: opens the native library and starts background gst_init / FFI worker spawn. Target under 50ms; does not wait for runtime readiness. Call early (e.g. before runApp). Idempotent; concurrent calls share one Future. After return, isInitialized may still be false.

GstPlayer.ensureReady()

Awaits full runtime readiness (gst_init success + worker started). Starts initialize() if needed. Controller create and captureThumbnail call this automatically.

GstPlayer.captureThumbnail(VideoSource, {Duration? at, int maxWidth})

One-shot cover extraction via a headless GStreamer pipeline in C (gstp_thumbnail_capture). Returns PNG Uint8List. Does not require an open controller. When at is null, native picks ~5% of duration (or 1s). Progress-bar scrub preview uses scrubPreview (external VTT/sprite), not live capture.

GstPlayerController

Method Description
initialize() Creates the native player and subscribes to events.
open(VideoSource, {bool autoPlay}) Loads a source; optionally starts playback.
play() / pause() / stop() Playback transport.
togglePlayPause() Play if paused, pause if playing.
seek(Duration) Seek to a position.
setVolume(double) Volume in 0.0..1.0.
setMuted(bool) / toggleMuted() Mute control.
setSpeed(double) Playback speed multiplier.
setLooping(bool) Loop at end-of-stream.
tracks / refreshTracks() / selectTrack(MediaTrack, {enable}) Audio / video / subtitle tracks.
captureCurrentFrame() Latest decoded frame as PNG (gstp_player_capture_frame; Apple/desktop appsink).
captureFramePng() Screenshot PNG; Android uses a headless thumbnail pipeline.
dispose() Tear down the player and release all resources.

Reactive state (plain getters on ChangeNotifier; read inside ListenableBuilder or after addListener): state, position, duration, videoSize, aspectRatio, bufferingPercent, volume, speed, looping, muted, isPlaying, isCompleted, error, playerId, initialized, mediaSource, tracks, supportsTracks.

PlayerState: idle, ready, buffering, playing, paused, stopped, completed, error.

VideoSource

  • VideoSource.network(String url, {Map<String, String> httpHeaders})
  • VideoSource.file(String path) (accepts a plain path or a file:// URI)
  • VideoSource.asset(String assetKey)

Network streams use the device User-Agent by default. Pass custom headers when the server requires auth or special headers:

VideoSource.network(
  'https://example.com/video.mov',
  httpHeaders: {'Authorization': 'Bearer …'},
)

GstVideoView

Embeds a Flutter Texture for the controller's video and, by default, an auto-hiding two-row Bilibili-style control bar.

Parameter Default Description
controller required The GstPlayerController to render.
aspectRatioMode AspectRatioMode.fit Layout scaling (fit / fill / stretch). Also via controller.setAspectRatioMode.
backgroundColor black Letterbox / background color.
showControls true Overlay the built-in control bar.
controlsStyle adaptive adaptive / material / cupertino.
fullscreen VideoControlsFullscreenConfig() Immersive / fullscreen chrome options.
language GstPlayerLanguage.zh Chrome copy: zh or en.
onPlayNext null Called at EOS when looping is off and play-next is enabled in settings.
onLightsOffChanged null Lights-off / theater mode changed.
poster null ImageProvider shown before frames / while idle.
keepLastFrame true Capture and keep the last frame after EOS.
scrubPreview null External WebVTT / sprite / frame list; time-only if null.
danmaku [] App-supplied DanmakuItem list.
danmakuEnabled false Toggle danmaku overlay.
onDanmakuSend null Bottom-bar send; shows the input row when non-null.
onDanmakuEnabledChanged null Danmaku toggle from chrome.
onSubtitlesEnabledChanged null CC toggle from chrome.
subtitles [] External SubtitleCue list (e.g. from SubtitleParser).
subtitlesEnabled true Toggle external subtitle overlay.
showCaptureButton true When false, hides Settings → Screenshot.
onScreenshot null Host receives PNG bytes when the user taps screenshot in settings. Plugin does not write disk or show a preview dialog.

Example with poster, subtitles, and danmaku:

GstVideoView(
  controller: controller,
  poster: MemoryImage(posterPng),
  keepLastFrame: true,
  subtitles: await SubtitleParser.loadAsset('assets/sample.srt'),
  subtitlesEnabled: true,
  danmaku: [
    DanmakuItem(at: Duration(seconds: 1), text: 'Hello'),
  ],
  danmakuEnabled: true,
)

Controls, gestures, and theming

Bottom chrome (Bilibili-inspired):

  • Lock: padlock on the far right of the center play/pause row. When locked, the bottom chrome is hidden and not hittable; tap the video to show/hide unlock only. Gestures and keyboard shortcuts do not bypass the lock.
  • Row 1: play / pause, current time, progress, remaining time, speed, settings gear, volume popup, fullscreen.
  • Row 2: danmaku toggle, capsule input + send, CC. Input/send disable when danmaku is off.
  • Settings (two pages): mirror, single-episode loop, autoplay, screenshot; then play-next vs pause-at-end, 16:9 / 4:3, hide black bars, lights-off, audio tracks.

Use Settings → Screenshot (when showCaptureButton is true and onScreenshot is set) or call controller.captureCurrentFrame() from the host.

Volume popup: tap the speaker icon for a vertical pink slider; the live 0–100 value is shown above the track. Long-press toggles mute.

Mobile gestures (Android / iOS, both inline and fullscreen; disabled while locked):

Zone Gesture Effect
Left ~40% Vertical drag Screen brightness + HUD %
Right ~40% Vertical drag Pipeline volume + HUD %
Horizontal Drag Seek preview / seek

Scrub preview: while dragging or hovering the progress bar, a thumbnail bubble appears when scrubPreview is set (GSY-style WebVTT + sprite / frames). Without a track, only time is shown. Live sources may show time only.

Register a VideoControlsTheme in ThemeData.extensions, or use presets material() / cupertino() / bilibili() (pink #FB7299):

MaterialApp(
  theme: ThemeData(
    extensions: [VideoControlsTheme.bilibili()],
  ),
);

Overlays helpers

  • SubtitleParser.parse(String) / SubtitleParser.loadAsset(String) → List<SubtitleCue>
  • DanmakuItem({at, text, color, duration}) — supply to GstVideoView.danmaku
  • GstPlayerLanguage.zh / .en — GstVideoView.language chrome copy

Architecture

Dart:  GstPlayerController ──FFI──► FfiPlayerCommandPort (gstp_player_*)
       GstVideoView (Texture) ◄──native texture── GStreamer sink
C:     native/ playbin3 ─► appsink (Apple/desktop) or glimagesink (Android)
                     │ bus ─► GstpEventCallback ─► Dart Stream
  • Decoding: playbin3 with platform video sink (appsink or glimagesink).
  • Network HTTP(S): souphttpsrc on all platforms (Android/iOS/macOS via static plugins in the umbrella or framework; Windows/Linux via system GStreamer).
  • Rendering: Flutter Texture + native TextureRegistry; Android uses SurfaceProducer + VideoOverlay and defers play until that surface exists; Apple/desktop pull BGRA frames via C ABI (gstp_texture_*).
  • Control plane: Dart FFI → narrow gstp_player_* API (see native/include/gstp_player.h).

Regenerating FFI bindings

After changing native/include/gstp_player.h:

dart run ffigen --config ffigen.yaml

NativeCore sync & verify

native/ is the canonical C source tree. iOS/macOS SPM targets compile from ios/gstplayer/NativeCore and macos/gstplayer/NativeCore, so keep them synced before build/publish:

# after editing native/{include,src}
./tool/native_core.sh sync

# before publish / release checks
./tool/native_core.sh verify

sync also generates the native version header from pubspec.yaml; verify checks the version and full contents of both NativeCore copies.

Regression checks:

flutter analyze
flutter test
python3 tool/test_gstreamer_scripts.py
python3 tool/test_desktop_build.py
# Prepare the corresponding GStreamer SDK first.
bash tool/test_native_macos.sh
bash tool/test_native_ios.sh

test_desktop_build.py uses dependency fixtures to check desktop CMake targets, C11 settings and the Windows runtime install layout, and compiles the Windows texture lifecycle regression when wrapper headers are available. It does not replace full Linux/Windows builds and playback tests. Use CMAKE, CXX and FLUTTER_ROOT to select local tools. On a macOS/Linux host, set GSTP_TEST_GLIB_LIBRARY to the absolute path of a host GLib shared library and run python3 tool/test_desktop_runtime.py to check environment preservation, Unicode bundled paths, SDK fallback and URLMON buffer contracts. Win32 calls use test doubles; GLib calls use the real host library.

Troubleshooting

  • First build is slow / needs network (Android / iOS / macOS): normal — the official GStreamer SDK is downloaded once into ~/Library/Caches/gstplayer/. Offline CI: pre-seed that cache or set GSTREAMER_ROOT_ANDROID / GSTREAMER_ROOT_IOS / GSTPLAYER_GSTREAMER_ROOT.
  • Android ndk-build / umbrella failed: ensure NDK matches android.ndkVersion in the app, network access for the first GStreamer SDK download, and a clean rebuild after plugin updates (flutter clean then flutter run). Stale jniLibs from the old reqwest build are invalidated by .gstreamer-umbrella-soup.
  • macOS pkg-config errors (Homebrew GStreamer dev): install pkgconf (e.g. brew install pkgconf).
  • iOS Simulator: not supported. Use a physical device.
  • iOS Plug-in ended with non-zero exit code: 1: usually the EnsureGStreamerIOS SPM build plugin failed (first-time SDK download, or missing ios/scripts). Open the Xcode Report navigator for the real stderr. Manual fix: sh ios/scripts/ensure_gstreamer_ios.sh (needs network, ~1.1GB), then rebuild. First Flutter SPM builds load the package via a .packages symlink — current plugin code resolves that path to find ios/scripts.
  • iOS 'gst/app/gstappsink.h' file not found: the example uses Swift Package Manager, which does not run the CocoaPods podspec. Package.swift / the EnsureGStreamerIOS build plugin download the SDK into ~/Library/Caches/gstplayer/gstreamer/<ver>/ios/iPhone.sdk on resolve/build. First build needs network. If headers are still missing: sh ios/scripts/ensure_gstreamer_ios.sh, then flutter clean && flutter pub get and rebuild.
  • macOS 'gst/app/gstappsink.h' file not found: same SPM path as iOS — the EnsureGStreamerMacOS build plugin runs ensure_gstreamer_macos.sh before compile (first build downloads ~870MB into ~/Library/Caches/gstplayer/gstreamer/<ver>/). Manual fix: sh macos/scripts/ensure_gstreamer_macos.sh, then rebuild.
  • macOS Library not loaded: ...GStreamer.framework: SPM hosts must add the [gstplayer] Embed GStreamer Framework Run Script (see Installation) and rebuild. Confirm YourApp.app/Contents/Frameworks/GStreamer.framework exists.
  • flutter pub get recreates ios/Podfile / macos/Podfile: enable SPM in the host pubspec.yaml (flutter.config.enable-swift-package-manager: true). A global flutter config --no-enable-swift-package-manager otherwise wins for the plugin package itself unless that key is set.
  • Release crash: Failed to lookup symbol 'gstp_init' (iOS/macOS): set Runner Strip Style = Non-Global Symbols for Release/Profile (the example already does). See Flutter C interop — Stripping symbols.
  • Link error: undefined symbol: _gstp_* (path / SPM): run ./tool/native_core.sh sync, then flutter clean and rebuild.
  • APK too large: narrow abiFilters or ship an App Bundle (each ABI carries a large GStreamer runtime).
  • Android minify / R8: keep org.freedesktop.gstreamer.** (plugin AAR already ships consumer ProGuard rules).
  • Windows pkg-config / missing glib: install the development GStreamer MSVC package and point PKG_CONFIG_PATH at ...\lib\pkgconfig.

Repository

License

See LICENSE.

Libraries

gstplayer
跨平台 GStreamer 视频播放器 Flutter 插件公开 API / Public API for the cross-platform GStreamer video player plugin.