Flutter Torrent Streamer #

这是一 Flutter 插件。支持 BT 磁力链接 的流媒体播放（边下边播）以及后台下载功能。

引入与安装 (Installation) #

由于本项目包含本地 Go 代码和构建脚本，建议通过本地路径引入。

1. 将 flutter_torrent_streamer 文件夹复制到你的项目目录中（例如 packages/ 目录下）。
2. 在你的主项目 pubspec.yaml 中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  
  # 添加本地插件依赖
  flutter_torrent_streamer:
    path: ./packages/flutter_torrent_streamer

3. 运行 flutter pub get 安装依赖。

Android 配置 (Configuration) #

为了确保插件正常工作，特别是后台下载功能，需要对 Android 项目进行配置。

1. 权限声明 (AndroidManifest.xml) #

打开 android/app/src/main/AndroidManifest.xml，添加以下权限：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.your_app">

    <!-- 网络访问权限 -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- 防止 CPU 休眠 (用于后台下载) -->
    <uses-permission android:name="android.permission.WAKE_LOCK"/>
    <!-- 前台服务权限 (Android 9+) -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

    <application ...>
       ...
    </application>
</manifest>

使用指南 (Usage) #

1. 初始化插件 #

在应用启动时（例如 main() 函数中），首先初始化插件。这一步会加载 Go 核心库并准备本地数据库。

import 'package:flutter_go_torrent_streamer/flutter_go_torrent_streamer.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 插件会自动初始化，但可以在此处预先配置
  runApp(MyApp());
}

2. 全局配置 (可选) #

你可以配置全局的下载限速、最大连接数等参数。

await FlutterTorrentStreamer().configure(TorrentStreamerConfig(
  downloadSpeedLimit: 5 * 1024 * 1024, // 5 MB/s
  uploadSpeedLimit: 1 * 1024 * 1024,   // 1 MB/s
  connectionsLimit: 500,               // 最大 500 个连接
  port: 6881,                          // 指定监听端口
));

3. 开始任务 (磁力链接) #

使用 startStream 方法通过磁力链接创建一个新的会话。

String magnetLink = "magnet:?xt=urn:btih:EXAMPLE...";
String savePath = "/path/to/save"; // 设置保存路径

// 创建任务
TorrentStreamSession session = await FlutterTorrentStreamer().startStream(magnetLink, savePath);

print("任务ID: ${session.sessionId}");
print("流媒体地址: ${session.streamUrl}"); // 可直接丢给播放器

4. 获取文件列表与选择文件 #

创建任务后，通常需要等待元数据解析完成（状态变为 Ready），然后获取文件列表供用户选择。

// 获取文件列表
List<TorrentFile> files = await session.getFiles();

for (var file in files) {
  print("文件索引: ${file.index}, 文件名: ${file.name}, 大小: ${file.size}");
}

// 场景 A: 用户想播放第 0 个文件 (边下边播模式)
// 这会优先下载文件的开头和当前播放位置
await session.selectFile(0); 

// 场景 B: 用户想纯下载第 1 个文件 (后台下载模式)
// 这会使用 Rarest-First 策略全速下载
await session.downloadFile(1);

5. 开启/关闭后台保活模式 #

为了防止在后台下载时被系统杀掉，建议在开始下载时开启后台保活。

// 开启后台保活 (显示通知栏)
await FlutterTorrentStreamer().enableBackgroundMode(
  title: "下载中...",
  content: "正在后台下载文件",
);

// ... 任务完成后关闭 ...
await FlutterTorrentStreamer().disableBackgroundMode();

6. 获取所有任务状态 #

你可以轮询获取所有任务的最新状态，用于更新 UI 进度条。

List<SessionInfo> sessions = await FlutterTorrentStreamer().getAllSessions();

for (var info in sessions) {
  print("任务: ${info.name}");
  print("进度: ${(info.progress * 100).toStringAsFixed(1)}%");
  print("速度: ${info.downloadSpeed / 1024} KB/s");
  print("状态: ${info.state}"); // Downloading, Seeding, Ready 等
}

7. 停止/删除任务 #

// 停止指定任务
await FlutterTorrentStreamer().stopStream(sessionId);

API 速查表 #

注意事项 #

1. Android 编译: 本插件依赖 Go 编译的 libtorrent_streamer.so。如果你修改了 go/ 目录下的代码，请务必运行 go/build_android.ps1 重新编译动态库。
2. 网络权限: 确保设备连接了网络，并且未被防火墙拦截 P2P 流量。
3. 存储: 默认情况下，下载的文件存储在应用的私有目录下。如果需要导出文件，需要自行处理文件复制逻辑。