Decide behavior at playlist item end

[defagos]

As a user I want a consistent user experience when playback ends. As a Pillarbox integrator I want to have flexibility in choosing how the player behaves when playback ends, in particular at the end of a playlist.

Acceptance criteria

The following questions have found an answer:

• How must the player behave when reaching the end of the playlist? Should the current item index be returned to nil?
• Should we let actionAtItemEnd be customized? (intuition: probably)
• Should we have built-in meaningful behaviors instead of letting integrators directly deal with actionAtItemEnd to get the behavior they want. For example:
  • Autoplay: Continue automatically for all items except the last one, pause at the end of the last one.
  • No autoplay: Pause at the end of each content
• If we provide built-in behaviors, should we still provide a manual behavior where integrators can still customize actionAtItemEnd directly?
• In general how should states evolve during playback depending on actionAtItemEnd? E.g.:
  • If playback continues automatically should the player briefly reach the ended state (if kept) before turning to playing again? Or should it stay playing all the time?
  • What should be the state when all items have been exhausted? (e.g. ended only for the last item in the playlist if pausing at end, otherwise returning to idle).
• How should the player behave after the last item ended but a previous item is then moved after it (or another item is appended)? Should playback resume depending on actionAtItemEnd or built-in behaviors, if any? Same question if the last item, whose end has been reached, is moved elsewhere in the playlist.
• We should also ensure that control center metadata is correctly updated, especially after the playlist has been entirely exhausted.

Expected output:

• The behavior has been discussed and documented (this possibly requires some PoC code to be written to know what is possible).
• Dedicated implementation stories have been written.

Hints (for stories)

• Some tests (e.g. testCurrentItemIndexAfterPlayerEnded) might have to be updated or added in the process.
• Control center metadata and commands must have a consistent state as well.

Tasks

• [x] Investigate what is possible with a PoC.
• [x] Discuss within the team and reach an agreement.
• [x] Document the agreement.
• [x] Write the stories.

[defagos]

We currently have an inconsistency at the end of playback. The current publisher preserves the last item while the queue player moves to the next item (default actionAtItemEnd). As a result the control center displays the media which just has been finished, which does not match the player true state.

So:

How must the player behave when reaching the end of the playlist? Should the current item index be returned to nil?

Should behave according to actionAtItemEnd. Currently we have the default behavior but later we could also expose other modes. We could either provide the built-in mode or we could add smarter modes like move forward in a playlist but pause on the last item, for example.

Should we let actionAtItemEnd be customized? (intuition: probably) Should we have built-in meaningful... If we provide built-in behaviors

Possibly later, we don't know what users need yet. Will write a story.

In general how should states evolve... We should also ensure that control center metadata is correctly updated

Related problems. Will write a separate story.

How should the player behave

Will write a separate story.

[defagos]

Created issues #304, #305 and #306.

[defagos]

As discussed with @mbruegmann and @nicolasbrunnersrf and the rest of the team:

• We can expose the raw actionAtItemEnd property without any clever behavior.
• When set to .pause we should change the player playback state to .playing or .paused if the user seeks back to a prior position after the player reached the end (in a paused state).
• We should add a setting to the demo to change this behavior globally for our custom player. We should also ensure we can implement a nice behavior for the playlist demo in the .pause case (automatically resume and advance to the next item when reaching the end, except for the last one, all with a gapless playback experience).
• We could improve the story demo as well.

This behavior would be consistent with other platforms:

• The web player already pauses when reaching the end (no playlist support).
• Android has the same setting.

[defagos]

To let apps chain between items something like the following should likely be possible, maybe with a dedicated shorter formalism:

// ...
.onReceive(player.propertiesPublisher.slice(at: \.playbackState).receiveOnMainThread()) { state in
    if state == .ended {
        player.play()
        player.advanceToNextItem()
    }
}

A short test shows that this jumps to the last item in the playlist so we probably have a minor bug when advancing to the next item is made at item end.

[defagos]

A dedicated implementation task has been created. Closed.