Improve documentation about AudioPlayer.global.setAudioContext and AudioPlayer.setAudioContext

[wujek-srujek]

Checklist

• [X] I made sure that the issue I am raising doesn't already exist

Use case / Problem

I think the documentation about AudioContext could be improved:

Global AudioContext

From the tutorial and documentation (AudioPlayer.global.setAudioContext has none) it isn't clear which one is true:

1. The global context needs to be set first, and any AudioPlayer created afterwards 'inherits' this configuration unless it is overridden with a player-specific setAudioContext - basically: if the global context applies to all players created after this call. This has been my assumption but now I feel it's wrong.

OR

2. The global context, when set, applies to all players created before it, and all players created after the call are not influenced.

OR

3. The global context applies to all players created before this call and future players created after this call. This is probably not true as according to my tests the player created before behaves differently to the player created after, but I am not sure yet which is correct.

Per-player AudioContext interaction with the global one

It is also not clear how the global context interacts with the per-player context. I think that it will also depend on how the global one works, e.g.: if a player with its own context is created, and then set the global context is set - does this player keep it own or does it get overridden by the global one? (If the global context applies to all previously created players, option 2 above).

Explain defaults

It would also be very helpful to explain what the defaults are, i.e. when no context is set whatsoever.

I think explaining these two issues in the documentation / tutorial would be very helpful. I think I have made a lot of mistakes in my code based on false assumptions and got a lot of unexpected results.

Proposal / Solution

Improve documentation and/or the getting started tutorial.

Affected platforms

other (I think the documentation would help developers for any supported platform)

Working on PR

yeah (I can help write the docs, I just need to have the definitive information about the behavior)

[Gustl22]

Answer: it depends

On ios, you can only set the context for all players of your app. For convenience this is also done when calling it on a single player: https://github.com/bluefireteam/audioplayers/blob/main/getting_started.md#audio-context

On Android, some of the options are global, some are only player specific, (everywhere it is stated globally, only can be set globally): https://pub.dev/documentation/audioplayers_platform_interface/latest/audioplayers_platform_interface/AudioContextAndroid-class.html

In principal, the option 1 "The global context needs to be set first, any AudioPlayer created afterwards 'inherits' this configuration" should be correct, at least for Android.

Yes, we should make that more clear on the docs of the individual methods:

https://github.com/bluefireteam/audioplayers/blob/50f56365f8e512df0fc5bdb7222614389cbd4ea0/packages/audioplayers/lib/src/audioplayer.dart#L189

https://github.com/bluefireteam/audioplayers/blob/50f56365f8e512df0fc5bdb7222614389cbd4ea0/packages/audioplayers/lib/src/global_audio_scope.dart#L55

[wujek-srujek]

Yes, my tests show exactly what you say - on Android, the players created after the 'set global context' call inherit these values. In all fairness, the behavior for iOS is documented in the tutorial, no issues here.