Files
SpotiFLAC-Mobile/docs/player_widgets.md
T
zarzet 37e21b5712 feat(branding): rename app and native backend to Mornye
Rename the Dart package, Android and iOS identifiers, Rust crates, native libraries, and Discord plugin. Preserve legacy data readers and compatibility aliases.

Update localized branding, documentation, artwork, build tooling, and release artifacts. Route Telegram release notifications to @mornyeupdates and link @mornyecommunity.
2026-10-20 12:00:44 +07:00

2.9 KiB

Home screen player widgets

Mornye includes a native home screen player for Android and iOS, inspired by Apple Music. Widgets share the existing playback queue and audio handler. They display the current artwork, track, artist, and playback state.

Adding and customizing

  • Android: open the launcher's widget picker and add Mornye Player. Resize it for a compact, horizontal, or large artwork layout. Open the widget's configuration to choose artwork colors, light, or dark, and toggle the artist name. Reconfiguration availability depends on the launcher.
  • iOS 17 or later: add Mornye Player from the home screen widget gallery. Small includes play/pause; medium and large also include previous and next. Long-press and choose Edit Widget for appearance and artist name.
  • Choose a track in the app first. Tap the widget's artwork or text to open the full player. An empty widget opens the app with transport disabled.

Artwork is a static thumbnail. Updates follow track and transport changes; there is no continuous timer or animated artwork in the home screen widget. The operating system controls when widget updates appear.

Native integration

PlayerWidgetService publishes presentation data through com.zarz.mornye/player_widget. Artwork loading discards stale results when tracks change. Commands are serialized and publish the latest state before acknowledging completion. A restored session starts paused and uses the same audio handler as the app.

Android uses RemoteViews and per-widget preferences. Controls call the active Flutter engine. If the process has been killed, a control opens the activity to restore the saved queue and execute the command.

iOS uses WidgetKit with AudioPlaybackIntent, shared between Runner and the widget extension. Runner starts one headless-capable Flutter engine at process launch; UIScene attaches the player interface to that same engine. This keeps widget commands available before a foreground scene exists. player.json and thumbnail images live in the App Group group.com.zarz.mornye; the widget does not receive audio files. The extension target is embedded by Runner and inherits the app's build version.

For physical iOS builds, both Runner and PlayerWidget signing profiles must include group.com.zarz.mornye. If using another bundle identifier, update PLAYER_WIDGET_APP_GROUP in all Runner configurations and ios/PlayerWidget/PlayerWidget.xcconfig, together with the extension bundle ID.

Verification

  • flutter test test/player_widget_service_test.dart
  • flutter analyze lib/services/player_widget_service.dart lib/main.dart
  • Build Runner for an iOS simulator and verify PlayerWidget.appex is embedded.
  • Build Android and run PlayerWidgetTest on an emulator to apply real RemoteViews for all layout sizes and themes.
  • On devices, add widgets and check play/pause, skip, opening the player, cold launch, resizing, appearance, and cover changes while backgrounded.