feat: useIsPlaying hook and isPlaying() method

[fivecar]

This addresses some of the trickiness and confusion that users may have in v4's API, where State.Buffering spans both playing and paused states (whereas in v3, you could just const playing = state === State.Playing || state === State.Buffering). #2036 shows the subtlety of doing this right.

This PR adds two things to the public API:

• useIsPlaying: a hook that will likely be used by anyone managing a Play button. It correctly tells you when the button should be shown as "playing" and when it should be shown as "buffering."
• isPlaying(): an async function that gives you the most current playing state. This is needed for cases where you can't use a hook (e.g. outside of React components) or for cases where a hook's delay (due to subscriptions to events) isn't enough for you to make the right fork in your code.

I've added Javadoc-style comments, but am unsure where to update The Real Documentation™. I've also updated the example app for this simpler way of doing things.

[puckey]

This is a really good addition to the library - thanks!

[dcvz]

Great addition! This will be helpful to those building apps -- and allows us to update this in the future if there's a need.

Looks like the CI is failing on a TS error, are you able to resolve this @fivecar ?

[fivecar]

Done, @dcvz. Apparently had an empty blank line at the end of index.ts.

[fivecar]

@puckey : made both updates. PR now returns undefined for both useIsPlaying() as well as isPlaying() when their states are undefined.

Also added docs.

[puckey]

useIsPlaying() is not returning undefined for playing & bufferingDuringPlay yet – it would need to be something like:

function determineIsPlaying(playWhenReady?: boolean, state?: State) {
  if (playWhenReady === undefined || state === undefined) {
    return { playing: undefined, bufferingDuringPlay: undefined };
  }

  const isLoading = state === State.Loading || state === State.Buffering;
  const isErrored = state === State.Error;
  const isEnded = state === State.Ended;

  return {
    playing: playWhenReady && !(isErrored || isEnded),
    bufferingDuringPlay: playWhenReady && isLoading,
  };
}

Also, as it is I think the typescript return type of isPlaying() will unnecessarily be Promise<undefined | boolean>. So it might be an idea to do the following to fix that:

export function useIsPlaying() {
  const { state } = usePlaybackState();
  const playWhenReady = usePlayWhenReady();
  return playWhenReady === undefined || state === undefined
    ? { playing: undefined, bufferingDuringPlay: undefined }
    : determineIsPlaying(playWhenReady, state);
}

function determineIsPlaying(playWhenReady: boolean, state: State) {
  const isLoading = state === State.Loading || state === State.Buffering;
  const isErrored = state === State.Error;
  const isEnded = state === State.Ended;

  return {
    playing: playWhenReady && !(isErrored || isEnded),
    bufferingDuringPlay: playWhenReady && isLoading,
  };
}

export async function isPlaying() {
  const [playbackState, playWhenReady] = await Promise.all([
    TrackPlayer.getPlaybackState(),
    TrackPlayer.getPlayWhenReady(),
  ]);
  const { playing } = determineIsPlaying(playWhenReady, playbackState.state);

  return playing;
}

Finally, why not include the full object returned from determineIsPlaying() in isPlaying()?

[fivecar]

@puckey : Ok, I've made all changes.

1. useIsPlaying now returns double undefineds if either PlaybackState or PlayWhenReady aren't known.
2. isPlaying now returns both playing and bufferingDuringPlay, instead of just one of them.

Note that the original Promise<boolean|undefined> from isPlaying was in response to code review feedback that I should do that, IIRC. Basically return undefined whenever the state isn't fully known. I think I've now changed things to where everyone's feedback is accounted for. LMK.

[tsheaff]

I know it's been almost a year since this came out, but just want to thank @fivecar for this excellent PR. Extremely helpful!