Flutter Go Torrent Streamer #

English | 中文 (Chinese)

Flutter Go Torrent Streamer (English) #

A Flutter plugin for real-time BitTorrent streaming (sequential download) and background downloading on Android, powered by a Go backend via FFI.

Features #

• 🚀 Real-time Streaming: Prioritizes sequential download for video streaming while downloading.
• 📥 Background Downloading: Supports standard downloading (rarest-first strategy) running in the background.
• 🛡️ Android Keep-Alive: Built-in support for Android Foreground Service to prevent the process from being killed.
• ⚡ High Performance: Uses a Go-based backend (anacrolix/torrent) communicated via Dart FFI and Isolates for non-blocking UI.
• ⚙️ Global Configuration: Full control over download/upload speed limits, connection limits, and listening ports.

Installation #

Add flutter_go_torrent_streamer to your pubspec.yaml dependencies.

dependencies:
  flutter:
    sdk: flutter
  flutter_go_torrent_streamer: ^0.0.3

Then run:

flutter pub get

Android Configuration #

To ensure the plugin works correctly, especially for background downloading, configure your android/app/src/main/AndroidManifest.xml.

1. Permissions

Add the following permissions inside the <manifest> tag:

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

    <!-- Network Access -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- Prevent CPU Sleep (for background download) -->
    <uses-permission android:name="android.permission.WAKE_LOCK"/>
    <!-- Foreground Service (Android 9+) -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

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

Usage #

1. Initialization

The plugin initializes automatically when first used. However, you can import it in your main entry point.

import 'package:flutter_go_torrent_streamer/flutter_go_torrent_streamer.dart';

void main() {
  runApp(MyApp());
}

2. Global Configuration (Optional)

You can set global speed limits and other parameters.

await FlutterTorrentStreamer().configure(TorrentStreamerConfig(
  downloadSpeedLimit: 5 * 1024 * 1024, // 5 MB/s
  uploadSpeedLimit: 1 * 1024 * 1024,   // 1 MB/s
  connectionsLimit: 500,               // Max 500 connections
  port: 6881,                          // Listen port
));

3. Start a Session (Magnet Link)

Use startStream to create a session from a magnet link.

String magnetLink = "magnet:?xt=urn:btih:EXAMPLE...";
String savePath = "/path/to/save";

// Create a session
TorrentStreamSession session = await FlutterTorrentStreamer().startStream(magnetLink, savePath);

print("Session ID: ${session.sessionId}");
print("Stream URL: ${session.streamUrl}"); // Can be passed directly to a video player

4. Get Files & Select File

Once metadata is fetched (state becomes Ready), you can list files and select one to download/stream.

// Get file list
List<TorrentFile> files = await session.getFiles();

for (var file in files) {
  print("Index: ${file.index}, Name: ${file.name}, Size: ${file.size}");
}

// Scenario A: User wants to stream file at index 0 (Sequential Mode)
await session.selectFile(0); 

// Scenario B: User wants to download file at index 1 (Background Mode)
await session.downloadFile(1);

5. Background Mode (Android)

Enable background mode to prevent the OS from killing the download process.

// Enable background service with a notification
await FlutterTorrentStreamer().enableBackgroundMode(
  title: "Downloading...",
  content: "Your torrent is downloading in the background.",
);

// ... After task is done ...
await FlutterTorrentStreamer().disableBackgroundMode();

6. Monitor Status

Poll for status updates to refresh your UI.

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

for (var info in sessions) {
  print("Task: ${info.name}");
  print("Progress: ${info.progress.toStringAsFixed(1)}%");
  print("Speed: ${info.downloadSpeed / 1024} KB/s");
  print("State: ${info.state}"); // Downloading, Seeding, Ready, etc.
}

7. Stop Session

await FlutterTorrentStreamer().stopStream(sessionId);

Flutter Go Torrent Streamer (中文文档) #

这是一个 Flutter 插件，支持 BT 磁力链接的流媒体播放（边下边播）以及后台下载功能。底层使用 Go 语言编写，通过 FFI 与 Flutter 通信。

功能特性 #

• 🚀 边下边播: 优先下载文件头部和播放位置，支持流畅的流媒体体验。
• 📥 后台下载: 支持标准的下载模式（Rarest-First 策略），适合普通文件下载。
• 🛡️ 后台保活: 内置 Android 前台服务支持，防止进程在后台被系统杀掉。
• ⚡ 高性能: 核心逻辑由 Go (anacrolix/torrent) 实现，通过 Dart FFI 和 Isolate 调用，不阻塞 UI 线程。
• ⚙️ 全局配置: 支持自定义下载/上传限速、最大连接数、监听端口等。

引入与安装 #

在 pubspec.yaml 中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  flutter_go_torrent_streamer: ^0.0.3

然后运行：

flutter pub get

Android 配置 #

为了确保插件正常工作，特别是后台下载功能，需要对 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>

使用指南 #

1. 初始化插件

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

import 'package:flutter_go_torrent_streamer/flutter_go_torrent_streamer.dart';

void main() {
  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. 存储: 默认情况下，下载的文件存储在应用的私有目录下。如果需要导出文件，需要自行处理文件复制逻辑。