Runtime API

Every player interaction is reflected in the redux store. Accessing the players store enables the full control of the player while running. Reacting to player events can be done by attatching to the latest action.

Getting store access

The store is provided after the player was initialized as a promise resolved. A redux store has two methods available: subscribe(), to subscribe to store changes, getState() to get the current state obejct and dispatch({ type: 'action', payload: 'data' }) to dispatch a state change. The following example will set the playtime to one minute after the player was initialized.

<script>
  podlovePlayer('#example', '/path/to/episode/definition/or/object', '/path/to/configuration/or/object').then(store => {
    store.dispatch({
      type: 'PLAYER_REQUEST_PLAYTIME',
      payload: 60000
    });
  })
</script>

Development

To improve the development experience it is highly recommended to use the redux devtools browser extension to get a better understandig about action dispatches and state changes.

Store Actions

The player provides dozens of actions to interact with the store. To simplify the implementation a dedicated actions package can be used:

$ npm install @podlove/player-actions

Once you've added this dependency you should be able to use it likewise:

import { requestPlaytime } from '@podlove/player-actions/timepiece'

podlovePlayer('#example', '/path/to/episode/definition/or/object', '/path/to/configuration/or/object').then(store => {
  store.dispatch(requestPlaytime(60000));
})

Reacting to player events

Some use cases require a reaction to a player event. This is also possible by subscribing to the store:

import { BACKEND_PLAY } from '@podlove/player-actions/types'

podlovePlayer('#example', '/path/to/episode/definition/or/object', '/path/to/configuration/or/object').then(store => {
  store.subscribe(() => {
    const { lastAction } = store.getState();

    if (lastAction.type === BACKEND_PLAY) {
      // Do something once the the player starts playing
    }
  })
})

Caveats

Some actions will trigger browser APIs and are limited due to device and interaction constraints.

REQUEST_PLAY

Audio playback is only allowed after a user interaction happened to prohibit background audio playback. Therefore the play action will only work after a user interaction.

SET_VOLUME

The volume API is only available on desktop devices. Mobile devices control the volume on a global level and doesn't react to volume changes.