Timebox: API play / pause / state

[defagos]

As developers we need to agree on a common playback API where applicable so that our products are meaningfully aligned.

Acceptance criteria

• Decisions have been taken regarding play / pause APIs.
• Identified states have been named consistently.

Tasks

• [x] Discuss play / pause API.
• [x] Discuss playback states.
• [x] Create issues where alignment is required.

[defagos]

About play / pause:

Facts

• Web: A single content is loaded with src and played with play.
• Android: Content is provided, then must be prepared manually. play is called to start playback.
• iOS / tvOS: Content is provided and automatically prepared. play is called to start playback (rate set to non-zero value).

Decisions

• For Android and the web which expose their underlying player (ExoPlayer / video.js) and thus reflect their API, stay close to the underlying API / philisophy.
  • That means keep prepare on Android and do not attempt to make some play method prepare and play.
  • If appropriate some convenience playback methods (e.g. some prepareAndPlay) might be added.
  • Advantage is that users can be forwarded to the underlying player documentation for more information and that the underlying documentation is also relevant for implementing Pillarbox.
• For iOS which hides the wrapped player the idea is the same. AVQueuePlayer automatically prepares items and play is only called to make the playback move forward.

[defagos]

Facts

More than actual states it appears we should be more interested in how we can learn about what happens in the player:

• ExoPlayer: As a Pillarbox client we listen to ExoPlayer playback state (idle, ready, buffering, ended) changes and other broadcast flag changes (e.g. onPlayReadyChange, onIsPlayingChange).
• Web: As a client we subscribe to some video.js events (e.g. playing, timeUpdate or ended).
• iOS / tvOS: Playback states consolidate tricky to combine event sources (e.g. item status, rate changes) into meaningful events.

Decisions

• The models are different between platforms. We should stick to their respective philosophies. Attempting to have a common state concept would be harmful.

[defagos]

TL;DR

• For everything playback-related it is crucial to stay as close as the underlying platform-specific implementation rather than attempting to fit everything into a single model.
• For peripheral business features (e.g. segments, geoblocking, ...) alignment will be easier and more desirable.