setAudioModeAsync documentation needs more explanation

The docs for Audio.setAudioModeAsync are a bit confusing. For example, the ‘Returns’ section contains this sentence:

Note that these are the only legal AudioMode combinations of ( playsInSilentModeIOS , allowsRecordingIOS , staysActiveInBackground , interruptionModeIOS ), and any other will result in promise rejection:

and then it lists a number of combinations, which raise a couple questions/confusions for me:

  1. It’s kind of hard to read, or to see at a glance whether the combination I was planning to set (mostly via omission/defaults) is valid or not.
  2. It turns out that the simple approach I expected to use to enable background audio, { staysActiveInBackground: true }, is not valid. This is because:
    • playsInSilentModeIOS is false by default
    • There’s no valid combination where playsInSilentModeIOS is false and staysActiveInBackground is true.
  3. It’s not at all clear why some combinations are valid and others are not.

Can anyone shed light on these issues?

And then to add to the confusion, when I actually attempt to set the audio mode with { staysActiveInBackground: true }, it turns out that what seemed to be optional properties with default values are actually required:

Error: Audio mode attempted to be set without the required keys:
[
  "allowsRecordingIOS",
  "interruptionModeIOS",
  "playsInSilentModeIOS",
  "interruptionModeAndroid",
  "shouldDuckAndroid",
  "playThroughEarpieceAndroid"
]

…it would help if I linked to the released docs, rather than the pre-release sources.

https://docs.expo.io/versions/v33.0.0/sdk/audio/#returns-1

Looks like all the above comments are still relevant, though.