A production-grade federated Flutter plugin for long-running background execution.

Supports background downloads, audio playback, native notifications, and task execution across all major platforms.

This codebase is substantially generated by AI coding agents (opencode), acting on human-authored instructions in a human-in-the-loop workflow. Every commit goes through the same pipeline: specification by a human, generation by an AI agent, human review, and automated CI checks.

• You are welcome — human contributions are valued and encouraged. Do not let the AI origin of the codebase discourage you from opening issues or submitting PRs.
• Your review matters — the code may contain patterns an AI considers optimal but are non-idiomatic or incorrect. Calling them out in review helps the whole project.
• Follow the same rules — PR standards in CONTRIBUTING.md and AGENTS.md apply to everyone, human or AI. No shortcuts.

• Audit before depending on it — treat each file as a draft written by an enthusiastic but fallible developer. The tests pass, the analysis is clean, but edge-case bugs may exist.
• CI is the floor, not the ceiling — the project passes dart analyze and flutter test, but that does not guarantee production readiness in your specific environment.
• File issues — if you find something wrong, open a bug report. The AI will learn from it on the next iteration.

• Background Downloads — Download files in the background with progress tracking, pause/resume/cancel support
• Audio Playback — Background audio playback with state reporting, seek support, and lock screen controls
• Native Notifications — Foreground service notifications (Android), system notifications (iOS/macOS)
• State Persistence — Runtime state saved across app restarts via platform-native storage
• Unified API — Single Dart API that works identically across all platforms

• Flutter >=3.22.0
• Dart ^3.5.0
• Android: minSdk 24
• iOS: 15.0+
• macOS: 12.0+

dependencies:
  background_runtime: ^0.1.0

Add the following permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

Add Background Modes to your Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>download</string>
</array>

Also enable UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace for public file access.

Add the following entitlements to your Runner.entitlements:

<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.files.user-selected.read-write</key>
<true/>
<key>com.apple.security.files.downloads.read-write</key>
<true/>

import 'package:background_runtime/background_runtime.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await BackgroundRuntime.initialize(
    BackgroundRuntimeConfig(
      enableDownloads: true,
      enableAudio: true,
      enableNotifications: true,
    ),
  );

  // Start a download
  final taskId = await BackgroundRuntime.download(
    DownloadRequest(
      url: 'https://example.com/file.zip',
      destinationPath: 'downloads/file.zip',
    ),
  );

  // Observe progress
  BackgroundRuntime.observeDownloads().listen((event) {
    print('${event.state}: ${event.progress}%');
  });

  // Play audio
  await BackgroundRuntime.play(
    AudioTrack(
      id: 'track-1',
      title: 'My Song',
      url: 'https://example.com/song.mp3',
    ),
  );

  await BackgroundRuntime.shutdown();
}

• Plugin API
• Architecture
• Platform Support

See CONTRIBUTING.md.

MIT — Copyright (c) 2026 Kyaw Zayar Tun