Documentation unclear - how does audio_session relate to just_audio?

[hacker1024]

To which pages does your suggestion apply?

• https://github.com/ryanheise/audio_service/wiki/Migration-Guide#0140
• https://github.com/ryanheise/audio_service

Quote the sentences(s) from the documentation to be improved (if any)

E.g. just_audio will now by default pause or duck audio when its audio session is interrupted by another app playing audio, and will resume normal playback once the interruption has ended, if deemed appropriate by the operating system. However, it is still possible to implement your own logic for handling audio interruptions by using the audio_session API directly.

Describe your suggestion

Perhaps this issue belongs in the just_audio repo, but that doesn't even mention audio_session yet.

It's not clear to me how these two plugins relate - I see that just_audio depends on audio_session, so it must use it, but do we need to do anything to set it up? And how would we override the default behaviour?

On another note, it's also probably necessary to mention audio_session in the README for new users, as right now it's just in the migration guide.

(PS I hope this documentation request isn't taken the wrong way - I understand that 0.14 was only released yesterday. I started this issue to keep track of improvements to the documentation, not to complain.)

[webwayscript]

Also it need 19? uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:audio_session] what about ios? iphone 5 support or not?

[ryanheise]

Hi @webwayscript , audio_service itself will also be moving to a minSdkVersion of 19 as well in order to use the new media2 API which has this minimum requirement, so that will be the minimum going forward. Note that on the Android dashboards, this gives you a market reach of 98.1% of devices which is better than level 16 was a few years ago, so it is reasonable to move things forward now. If you need to support the remaining 1.9% percent of devices, you will be able to use audio_service 0.13.0 although you will not receive future benefits from the use of the new media2 APIs. I am not sure on the iPhone 5 situation but you can open a feature request if it's not there and you need it. I can at least then consider it properly and decide what to do. However, this current issue is regarding documentation, so you would be better to create a separate issue.

[ryanheise]

Hi @hacker1024

I completely understand the need for documentation, and this will need to improve iteratively. I have added this minor clarification to the migration guide:

This default behaviour can be disabled by using the AudioPlayer(handleInterruptions: false) constructor, allowing you to implement your own audio interruption logic by using the audio_session API directly.

In addition to the relationship between audio_session and anything else, I think it is also important to clarify what it is in itself.

What is it?

• It's a package that provides a unified view of the iOS AVAudioSession and Android AudioManager APIs.

What are the relationships?

• An app needs to interact with the audio session if it needs to configure settings that control how the operating system grants your app access to audio hardware with respect to other audio apps on your device.
• An audio plugin needs to interact with audio session (either through this plugin or directly in native code) in order to activate and deactivate the audio session. When an app's audio session is active, it has what is known in Android as the "audio focus", but in iOS is called activating the session. So the audio session is there to coordinate multiple apps with competing needs on the audio hardware.

What sorts of APIs are included, or will be included in audio_session?

• audio focus / interruption handling
• ducking / mixing
• audio route changes
• discovery of audio hardware
• adjust hardware volume

The primary place to document audio_session is the audio_session README itself, but audio_service and just_audio need to provide a brief explanation and a link. Unfortunately, it is very difficult to write something that is both brief and effective.

One other thing I want to mention here is that the primary motivation for creating audio_session is that the Flutter audio ecosystem had inadvertently ended up in a situation where there existed no independent package to configure the audio session settings, and so each and every audio plugin (my own included) ended up duplicating this responsibility, and worse, would overwrite each other's preferred settings for the audio session. If an app wants to use multiple audio plugins, it is more useful to think of these audio plugins as being "guests" riding on a shared audio session that is owned by the app logic itself rather than being owned by any individual audio player or audio recorder. So audio_session essentially helps to achieve that goal of removing the concern of configuring the audio session out of the individual audio plugins (where it was duplicated) and making it a standalone thing that can be shared across the whole app and all of its plugins.

[redimongo]

Really wish there was a simple example of just_audio + audio_service as I can't figure out where the MyBackgroundTask goes or gets called from.

[ryanheise]

I've now added more detailed sections about the audio session to the READMEs of both audio_service and just_audio so I'll close this issue.

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs, or use StackOverflow if you need help with audio_service.