Skip to content

README.md

Latest commit

 

History

History
217 lines (173 loc) · 10.9 KB

README.md

File metadata and controls

217 lines (173 loc) · 10.9 KB

FlutterTV Plugins

Flutter plugins with Apple TV (tvOS) support, maintained by the fluttertv.dev organization.

These are companions to flutter-tvos — the Flutter tvOS custom embedder. Most are federated *_tvos implementations of popular pub.dev plugins, produced with the flutter-tvos plugin port tool and finished/verified by hand.

Published on pub.dev under the fluttertv.dev verified publisher. Add them like any other plugin (<name>_tvos: ^0.0.1).

List of plugins

Every plugin below has a tvOS implementation; full details (API coverage, disabled regions, and porting notes) are available in each package's README.md and PORTING_REPORT.md.

Plugin Upstream
shared_preferences_tvos pub shared_preferences
video_player_tvos pub video_player
wakelock_plus_tvos pub wakelock_plus
connectivity_plus_tvos pub connectivity_plus
path_provider_tvos pub path_provider
flutter_secure_storage_tvos pub flutter_secure_storage
device_info_plus_tvos pub device_info_plus
package_info_plus_tvos pub package_info_plus
audioplayers_tvos pub audioplayers
flutter_tts_tvos pub flutter_tts
sqflite_tvos pub sqflite

Evaluated but not provided

These were assessed and deliberately not shipped — their core capability does not exist on tvOS, so a published package would be misleading:

Plugin Why not on tvOS
url_launcher No Safari / arbitrary URL or app launching on tvOS
google_sign_in No GoogleSignIn tvOS SDK; tvOS uses a different device-pairing flow
geolocator No location services on Apple TV
permission_handler tvOS lacks the permission surfaces (location, camera, photos, …)
firebase_core No tvOS slice of the Firebase Apple SDK
in_app_purchase StoreKit2 port has an unresolved protocol-conformance cascade
network_info_plus Wi‑Fi SSID/BSSID APIs do not exist on tvOS
webview_flutter No WebKit on tvOS — there is no web view, in-app browser, or HTML rendering

Usage

The upstream plugins do not endorse a tvOS implementation, so add the *_tvos package to your app explicitly, alongside the upstream plugin:

dependencies:
  shared_preferences: ^2.2.0
  shared_preferences_tvos:
    git:
      url: https://github.com/fluttertv/plugins.git
      path: packages/shared_preferences_tvos

Then use the upstream plugin's API exactly as on iOS — the tvOS implementation registers automatically. Once published these become plain ^version dependencies.

A few packages need a writable directory and therefore also path_provider_tvos: e.g. video_player_tvos (for VideoPlayerController.file) and sqflite_tvos (for the database path). Their READMEs note this.

How this repository was created

These packages were not hand-written from scratch. They were produced with the flutter-tvos plugin port tool (part of flutter-tvos) and then verified — and where needed finished — by hand. This is the exact, reproducible workflow.

For the full porter reference — every flag, what the transformer does and doesn't do, and how to read the generated PORTING_REPORT.md — see Porting an existing plugin in the flutter-tvos docs. The summary below is the recipe we used to produce this repo.

0. Prerequisites

# the flutter-tvos CLI (custom embedder + tooling)
git clone https://github.com/fluttertv/flutter-tvos.git
export TVOS=$PWD/flutter-tvos/bin/flutter-tvos

1. Port an upstream plugin

flutter-tvos plugin port takes an existing Apple plugin (the iOS or macOS implementation package) and emits a federated *_tvos package.

# from a published pub.dev package (what we used):
$TVOS plugin port --from-pub video_player_avfoundation \
  --output plugins/packages/video_player_tvos --include-example

# or from git, or from a local path:
$TVOS plugin port --from-git https://github.com/foo/bar.git --ref main --output ...
$TVOS plugin port ../some_plugin_ios --output ...

The exact upstream source for each package is recorded at the top of its PORTING_REPORT.md (e.g. video_player_tvos ← video_player_avfoundation, shared_preferences_tvos ← shared_preferences_foundation, audioplayers_tvos ← audioplayers_darwin).

What the porter does automatically:

  • Copies the upstream Dart lib/ (rewriting package: self-imports) and federates through the upstream *_platform_interface.
  • Copies the native Swift/Objective-C into tvos/Classes/ and generates a tvOS *.podspec (no dependency on the Flutter CocoaPod — tvOS resolves Flutter.framework via search paths).
  • Makes tvOS follow the iOS code paths: widens #if os(iOS) → (os(iOS) || os(tvOS)), ObjC #if TARGET_OS_IOS → (TARGET_OS_IOS || TARGET_OS_TV), and @available / #available / API_AVAILABLE iOS <v> → also tvOS <v>.
  • Collapses modern multi-target / include/-modular SwiftPM packages into one CocoaPods module (drops the macOS-only target).
  • Sets FLTAssetsPath so plugin asset lookup resolves on a real Apple TV; sanitizes example pub-workspace / dependency_overrides wiring.
  • Graceful partial port: an API that genuinely doesn't exist on tvOS, used at type/top-level scope, is wrapped in #if !os(tvOS) / #if !TARGET_OS_TV so the package still compiles with that feature disabled, and every such region is listed in PORTING_REPORT.md under "Disabled on tvOS". A compatibility database (WebKit, SafariServices, CoreLocation, CoreTelephony, AVAudioSession routing options, …) drives this.

2. Read the porting report

Every package gets a PORTING_REPORT.md: the source + version, the tvOS build outlook, methods ported/stubbed, every disabled region with the reason, and a checklist. Read it before trusting a port.

3. Verify

cd plugins/packages/<pkg>/example
flutter pub get
$TVOS build tvos --simulator --debug          # must be green
$TVOS test integration_test/<plugin>_test.dart -d <sim-udid>
# on a physical Apple TV (set your signing team):
DEVELOPMENT_TEAM=XXXXXXXXXX $TVOS run -d <device-udid>

Only a green simulator build (and, ideally, passing integration tests on a real Apple TV) qualifies a package for this list.

4. Hand-finish where the porter can't

The porter is honest about its limits; some packages needed manual work, all of it documented in their PORTING_REPORT.md:

  • path_provider_tvos — path_provider_foundation is a dart:ffi/native-assets plugin the tvOS toolchain can't build, so the porter only emits a skeleton. A real native implementation (NSSearchPathForDirectoriesInDomains / NSTemporaryDirectory) was written by hand.
  • flutter_secure_storage_tvos — Keychain works on tvOS; the optional LAContext / .biometryAny / Secure-Enclave biometric path (which tvOS lacks) was guarded out by hand.
  • audioplayers_tvos, flutter_tts_tvos — AVAudioSession category options that don't exist on tvOS (allowBluetooth, defaultToSpeaker, …) were mapped to no-ops.
  • sqflite_tvos — re-ported once the porter learned to collapse single-target include/-modular SwiftPM packages.

5. Curate

Packages whose primary purpose can't work on tvOS, or that don't build after best-effort, are removed rather than published broken (see Evaluated but not provided).

See AUTHORING.md for the deeper per-plugin recipe.

Repository layout

plugins/
├── packages/<plugin>_tvos/    # one directory per plugin
│   ├── lib/                   # Dart (federated impl)
│   ├── tvos/Classes/          # native Swift/ObjC
│   ├── tvos/<plugin>.podspec  # CocoaPods spec, tvOS 13+
│   ├── example/               # runnable tvOS example
│   ├── PORTING_REPORT.md      # port detail + checklist
│   ├── README.md  CHANGELOG.md  LICENSE
└── AUTHORING.md               # how to add a new one

Contributing

  • Federate via the upstream *_platform_interface; suffix _tvos.
  • Target tvOS 13.0+; guard shared iOS code with #if os(tvOS).
  • Document API support and any disabled regions in the package README.md and PORTING_REPORT.md so users can assess compatibility.
  • A package only ships if it builds green on tvOS.

License

BSD-3-Clause (see LICENSE). Ported packages retain their upstream copyright; tvOS additions are © The FlutterTV Authors.