ryanheise
commented
5 years ago To potential iOS contributors
This post describes the work to be done on the iOS side and what might be the best way to break it down.
Android and iOS differences
The architecture of this plugin was really dictated by the nature of Android's component system, so first let's try to understand why things must be the way they are if the plugin is to work on both Android and iOS. In Android, an app is made up of a set of individual components which may be dynamically spawned and destroyed over the lifetime of the app. An audio playing app needs an "Activity" component which is only allowed to run foreground code (i.e. the UI), and a "Service" component which is only allowed to run background code (i.e. playing audio). The idea is that the Activity could be swiped away by the user, i.e. destroyed and freed from memory, while the Service component is allowed to live on and play audio in the background. Flutter automatically sets up an isolate inside the activity to run your Dart code, but since this activity could be swiped away at any time, we can't put the audio playing code here. We therefore use a relatively new Flutter API to create our own isolate attached to the Service for running Dart code, and this is where the audio playing code needs to go. Flutter's API for background execution of Dart code is described in this Medium article.
iOS developers in the thread discussion below have pointed out that things fortunately may be a lot simpler on iOS since there is no such separation of foreground and background code. This may mean that the iOS implementation of the plugin would not need to use Flutter's background execution API. However, to main compatibility with Android's behaviour, I would suggest that the iOS implementation should still spawn a plain old isolate for running the background audio code. This would ensure call-by-value semantics is maintained on both platforms.
Architecture overview
This plugin sets up a Dart isolate for running audio playback code in a way that continues to run when the app is not in the foreground. The dart code that runs in this isolate is called the "background task". The architecture allows one or more "clients" to connect to the background task to control audio playback and be notified of state changes to update the UI. One of those clients is the Flutter user interface, but other clients may include a Bluetooth headset or a smart watch. There are distinct APIs for the Flutter client side and for the background task:
- The
AudioServiceAPI is for the Flutter client and allows for starting, stopping and sending/receiving messages to/from the background isolate. - The
AudioServiceBackgroundAPI is for the background isolate and it dictates a set of callbacks that must be implemented to handle messages from the main isolate, and also provides methods to notify state updates back to all clients.
For example, AudioService.play() sends a message to the background task which is handled by its onPlay callback. But the message is not sent directly from point A to point B. Rather, it must go through a platform channel to the native plugin so that the plugin has a chance to do all of the things that a native app must typically do before playing audio. On Android, this involves acquiring audio focus and calling various APIs to allow the app to keep running while the app is not in the foreground and while the screen is turned off (acquiring a wake lock and starting a service) as well as showing a notification to indicate that the app is playing audio in the background. Once all of these things are done, the plugin THEN passes the message on to the Dart background task via its onPlay callback. Regardless of which client the play command originated from, the plugin should handle the command in the same way by performing any required native rituals to prepare for audio playback and then finally pass control to onPlay.
Stage 0: Foundation
A good starting point would be to implement the method call to start the background isolate, and to implement all other method calls either to directly pass through from one isolate to the other, or even implement them as no-ops. The only methods that absolutely need to work in this stage are:
start- tell the plugin to start the background isolate.stopped- tell the plugin that the background isolate has completed.
With this much, the demo example app should start playing audio and will stop once the audio has run out by itself, but will not allow clients to control playback and will not notify the clients of state changes.
Stage 1: Basic functionality
The basic functionality provides the ability to control playback with the basic play/pause operations (which can also be controlled with a headset button click), and also the ability to stop the background task on request. The relevant method calls to implement are: connect, disconnect, ready, isRunning, setState/onPlaybackStateChanged, stop/onStop, pause/onPause, play/onPlay, setMediaItem/onMediaChanged and click/onClick. I'll be happy to answer questions about any of these in the comments below.
There are also a set of method calls that allow jumping to different positions and tracks that don't require any special set up on the native side so all they do is forward the messages on to the background task. They are: seekTo/onSeekTo, skipToNext/onSkipToNext, skipToPrevious/onSkipToPrevious, fastForward/onFastForward and rewind/onRewind.
The plugin should also have a default case for custom actions (whose method names begin with "custom_". These are also just forwarded directly to the background task without any special setup on the native side.
Stage 2: Queue functionality
This functionality adds the ability to manipulate the playlist/queue and jump to an arbitrary media items. The relevant method calls are: addQueueItem/onAddQueueItem, addQueueItemAt/onAddQueueItemAt, removeQueueItem/onRemoveQueueItem, skipToQueueItem/onSkipToQueueItem and playFromMediaId/onPlayFromMediaId.
Stage 3: Browsing functionality
This adds the ability for clients to browse media items offered by the background task. The relevant methods are: setBrowseMediaParent, notifyChildrenChanged, onChildrenLoaded and onLoadChildren.
Addressing API differences between Android and iOS
When there are equivalent features on iOS and Android, the preference is to implement both sides with the same API. If things would be easier on the iOS side if the API were changed, please make the suggestion below! I would definitely prefer to change the API if it means that the Android and iOS APIs can be harmonised.
In cases where a purely iOS-specific feature is desirable, it can be added as long as it is named with an ios prefix.
hacker1024
alexelisenko
docaohuynh
adriancmurray
ZheGuangZeng
LoSunny
Dekkee
konstantin-mohin
alexandergottlieb
yringler
I'm creating this issue to keep track of an iOS implementation. I myself am an Android developer, and I'd love to see an iOS developer contribute.