Confusing AudioPlayerState vs AudioPlaybackState

[yringler]

Developer ergonomics
As I was switching to use this library, I found myself losing track of PlayerState (i.e playerState, playerStateStream) and PlaybackState (i.e playbackStateStream). I couldn't remember which was the enum and which was the class, and had to keep on checking.

I suggest that the core issue is that state is a generic word (as in the phrase, "maintaining app state"), and differentiating is relying on the words "player" and "playback", both of which aren't so strongly associated with the data their representing.

I suggest that the API and docs be updated to use "Status" for the enum, and "Details" for the object.

My reasoning:

• Status implies a short, generic description. For example, a short whatsapp status. "At the park", or "Driving home". This fits with the enum - "loading", "playing", "stopped", etc.
• Details implies... details, which are specific to the unique activity which is going on now. TImes, speeds, positions - all the contents of the current AudioPlayerState (As I'm writing this, I have to keep on checking which is which 😅 )

That would give us, perhaps
playerDetailsStream, playbackStatus, playbackStatusStream, etc.

Further, I suggest that the split between "player" and "playback" is additionall information which has to be interpreted by the developer, while not adding that much additional clarity. Perhaps the "prefix" should be a standard "audio", giving
audioDetailsStream, audioStatus, audioStatusStream, and class AudioDetails and enum AudioStatus.

This is my personal opinion, and this is more of a discussion issue (at this point at least).

If you agree, this is something I could try my hands at making a PR for, although it may be a few days until I can get around to it.

[ryanheise]

I appreciate the suggestion. I had the same naming challenge with audio_service, actually. In the native Android APIs, they call the data structure "PlaybackState" and the enum "State" which shows that I am not alone in this struggle.

I definitely want to keep the word 'state" since it is so prevalent in existing media APIs, and the enum itself should definitely be called state because it is a state machine with state transitions. Basically it's a FSA. The word "status" is not suggestive of it being an FSA.

However, I'm open to changing the name of the struct. I think probably a good suffix could be "event" since events are triggered in response to certain things happening and they typically encapsulate multiple pieces of data. So we could have PlaybackState for the enum and PlaybackEvent for the struct. Would that work for you?

[yringler]

Yes. Good points, good idea.
That also includes changing the name of the relevant properties (playbackStateStream, playbackEvent, and playbackEventStream), right?

[ryanheise]

I've just renamed AudioPlayerState to AudioPlaybackEvent and the associated fields. I haven't published a release yet since there is some unrelated iOS code that I need to write/test before releasing.

[ryanheise]

Published.

[yringler]

Awesome! I just updated to 0.0.6, it makes a big difference. Thank you.

[github-actions]

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 just_audio.