Flutter Go Torrent Streamer

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.

New in v0.0.8: Supports multiple concurrent download tasks，The plugin now uses a single global torrent client instance to manage multiple sessions, ensuring efficient resource usage and preventing port binding conflicts.

Installation

Add flutter_go_torrent_streamer to your pubspec.yaml dependencies.

dependencies:
  flutter:
    sdk: flutter
  flutter_go_torrent_streamer: ^0.0.8

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.

Note: On Android, ensure savePath is a valid writable path (e.g., using path_provider).

import 'package:path_provider/path_provider.dart';

// ...

String magnetLink = "magnet:?xt=urn:btih:EXAMPLE...";
final dir = await getApplicationDocumentsDirectory();
String savePath = "${dir.path}/downloads"; 

// 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. Control Session (Pause / Resume / Stop)

You can pause, resume, or stop a session.

// Pause the session (stops network activity, keeps state)
await session.pause();

// Resume the session
await session.resume();

// Stop the session (removes it completely)
await session.stop();
// Or use the plugin instance:
// await FlutterTorrentStreamer().stopStream(sessionId);

5. 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);

6. 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();

7. 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.
}

API

Method	Description
`FlutterTorrentStreamer().configure(config)`	Set global limits, port, connections, etc.
`FlutterTorrentStreamer().startStream(magnet, savePath)`	Create a new session from a magnet link. Returns `Session`.
`FlutterTorrentStreamer().stopStream(sessionId)`	Stop and remove a specific session.
`FlutterTorrentStreamer().getAllSessions()`	Get real-time status of all sessions.
`FlutterTorrentStreamer().enableBackgroundMode()`	(Android) Start foreground service to prevent killing.
`FlutterTorrentStreamer().disableBackgroundMode()`	(Android) Stop foreground service.
`session.pause()`	Pause the session (stops network, keeps state).
`session.resume()`	Resume the session.
`session.stop()`	Stop and remove the session.
`session.getFiles()`	Get the list of files in the torrent.
`session.selectFile(index)`	Select a file for streaming (sequential download).
`session.downloadFile(index)`	Select a file for background download (rarest-first).