zstandard_android 1.5.6

Android implementation of the Zstandard compression plugin for Flutter applications.

zstandard_android

The Android implementation of the zstandard Flutter plugin. Uses FFI and the native Zstandard C library.

Installation

Add the main plugin to your app; this package is included automatically via the federated plugin:

dependencies:
  zstandard: ^1.5.0

No extra Gradle or native setup is required for normal use.

Usage

Use the main zstandard API; the Android implementation is selected automatically on Android:

import 'package:zstandard/zstandard.dart';

void main() async {
  final zstandard = Zstandard();
  final data = Uint8List.fromList([1, 2, 3, 4, 5]);

  final compressed = await zstandard.compress(data, 3);
  final decompressed = await zstandard.decompress(compressed ?? Uint8List(0));
}

Or use the extension methods:

final compressed = await data.compress(compressionLevel: 3);
final decompressed = await compressed?.decompress();

API

• ZstandardAndroid() — Creates the Android platform implementation.
• compress(Uint8List data, int compressionLevel) — Compresses data (level 1–22). Returns compressed bytes or null.
• decompressWithOptions(Uint8List data, {int maxOutputSize}) — Decompresses complete, concatenated, or unknown-size zstd frames with a bounded output (256 MiB by default). Invalid, truncated, or oversized input returns null.
• getPlatformVersion() — Returns a platform identifier string.

Architecture

This package uses Dart FFI to load libzstandard_android.so. Public operations send Dart-owned bytes to a worker isolate; native pointers never cross an isolate boundary. Decompression uses zstd's streaming API and enforces the configured output limit while producing bytes.

Gradle locates zstandard_native through the consuming app's .dart_tool/package_config.json, including an enclosing Dart workspace. It resolves the selected dependency's rootUri with the host's file-URI parser and passes its src/zstd directory explicitly to CMake. This supports a versioned Pub cache outside the app, Windows drive paths, spaces and Unicode, without choosing another cached version. Run flutter pub get before building.

An explicit Gradle property -PZSTD_ROOT=... or ZSTD_ROOT environment variable can select a source directory containing zstd.h, common, compress and decompress. Relative overrides use the consuming Android project directory. Direct CMake builds use -DZSTD_ROOT=.... Repository-local fallback is available only when no consumer package configuration or explicit override is present; an invalid selected dependency fails with a diagnostic.

The plugin does not pin an Android Gradle Plugin version. The consuming app owns that choice. The repository contains two Android consumers for CI:

• example/ uses AGP 9.1.0 with built-in Kotlin.
• example_legacy/ uses AGP 8.11.1, Gradle 8.14, and Kotlin Gradle Plugin 2.2.20.

Both consumers compile the same native library for armeabi-v7a, arm64-v8a, and x86_64. CI runs the Flutter integration tests and Android native instrumentation tests on a headless x86_64 emulator. The native tests assert that the shared library loads, compression produces non-empty output, and decompression returns the original byte array.

Testing

From the package directory:

flutter test

Unit tests run only on Android (they are skipped on other platforms). The repository CI also builds debug and release APKs for the three supported Flutter Android ABIs, runs the Flutter integration tests on an emulator, and executes the native androidTest suite. For local end-to-end testing, run one of the example apps on an Android device or emulator.

Troubleshooting

• Library not found: Ensure you build and run the app for Android (e.g. flutter run or flutter build apk) so the native library is compiled and packaged.
• Crashes: Verify inputs are non-null and valid; for decompress, ensure the data is a valid zstd frame.

See the documentation for more.