Ligatura

面向 Android 与 iOS 的高性能 Flutter 文件预览组件，用于渲染一种固定结构的 JSON 时间轴格式。组件支持可选的同步音频，也可以完全静音运行。

LigaturaPlayer 是一个干净的渲染视图，不包含按钮、进度条、文件选择器或其他控制 UI，适合直接嵌入现有 Flutter 页面。

特性

使用 CustomPainter 绘制，每帧不重建组件树
加载阶段预计算时间、位置与可见范围
大文件在 worker isolate 中解析
支持内存、本地路径和 Flutter asset 输入
支持可选音频、播放、暂停、定位和倍速
仅支持 Android API 24+ 与 iOS 15.0+

安装

dependencies:
  ligatura:
    git: https://github.com/jiangyin14/Ligatura.git

最小接入

import 'package:ligatura/ligatura.dart';

final source = LigaturaSource(
  chart: LigaturaAsset.flutterAsset('assets/preview.json'),
);

LigaturaPlayer(
  source: source,
  autoplay: true,
);

父组件需要提供有限尺寸，例如 Scaffold.body、Expanded 或 SizedBox。预览画面会在可用空间内保持 9:16，不会被拉伸。

如果连默认的加载状态和错误文字也不需要，可以传入空 builder：

LigaturaPlayer(
  source: source,
  autoplay: true,
  loadingBuilder: (_) => const SizedBox.expand(),
  errorBuilder: (_, __) => const SizedBox.expand(),
);

本地文件与音频

final source = LigaturaSource.files(
  chart: '/path/to/preview.json',
  audio: '/path/to/audio.ogg',
);

LigaturaPlayer(
  source: source,
  audioLoadMode: LigaturaAudioLoadMode.automatic,
);

文件路径输入默认以流式方式读取音频，避免把完整文件复制到 Dart 堆。只有字节数据时，可以改用 LigaturaAsset.memory。

可选控制器

只需要自动预览时无需创建 controller。需要由业务层控制时再传入：

final controller = LigaturaController();

LigaturaPlayer(
  source: source,
  controller: controller,
);

await controller.play();
await controller.pause();
await controller.seek(const Duration(seconds: 30));
await controller.setPlaybackRate(1.25);

controller 由创建它的业务层负责 dispose。需要显示进度时，应监听 positionListenable，避免让整个页面随每一帧重建。

完整接入说明见 Android / iOS 接入指南，内部设计见架构说明，可运行示例见 example。

开发验证

flutter analyze
flutter test
cd example
flutter build apk --release
flutter build ios --release --no-codesign

License

MIT