@voicebase/react-player

VoiceBasePlayer

The VoiceBase React Player is a React component designed to display and play transcripts and media.

Unlike previous editions the Voicebase React Player expects to be fed a mediaUrl and an analytics (JSON) object.

Alternately the VoiceBasePlayer has a loading and error screen that can be displayed during retrieval of content.

API

The API is modal - only when loading and error are both false (opmitted) does the VoiceBase Player require a complete set of properties describing media.

When Ready To Play:

• analytics - JSON object: describing transcript, predefined vocabulary, etc.
• analyticsFormat - string (optional): one of the following constants: ANALYTICS_SCHEMA_VERSION_V2, ANALYTICS_SCHEMA_VERSION_V2_CALLBACK, ANALYTICS_SCHEMA_VERSION_V3 (the default value), ANALYTICS_SCHEMA_VERSION_EVENT_STREAM.
• mediaUrl - string: a fully qualified hyperlink to an audio file/stream.

*loading and error must be false or omitted to view the Player control panel.

<VoiceBasePlayer analytics={myAnalytics} 
analyticsFormat={ANALYTICS_SCHEMA_VERSION_V2_CALLBACK}
mediaUrl={myMediaURL} />

The control panel will appear like this:

The children of the VoiceBasePlayer tag are ignored during playback.

While Loading

If you want to delay projection of the VoiceBasePlayer panel you can of course simply not display it until you have the mediaUrl and analytics ready, showing any ajax visual display you please. However, if you pass loading={true} to VoiceBasePlayer it will display a loading spinner. Any content of theVoiceBasePlayer tag will be displayed.

<VoiceBasePlayer loading={true}>Getting Source Files, Please Wait
</VoiceBasePlayer>

The load screen appears as this:

On an error:

While you can display your own error screen on errors, the Player will serve as a basic error panel. The only parameter that must be set is:

• error: true

The error message (optional) can be passed through in the body of the <VoieBasePlayer>{my message}</VoiceBasePlayer> tag.

You can put any React tag you want as a child of VoiceBasePlayer react and it will be shown inside a panel.

<VoiceBasePlayer error={true}>Generic URL Error Message</VoiceBasePlayer>

The error screen appears like this:

Retrieval of Media URLs and Analytics from VoiceBase Servers

Note - previous versoins of the VoiceBasePlayer "internalized" the function of accessing content from VoiceBase Servers. the current player does not - it expects you to get those data yourself.

There are VoiceBase APIs that will provide this information. However they require a Bearer Token to access.

There are two APIs - one to get the mediaUrl, and another to get the Analytics Data.

The first returns a string; the second returns the Analytics JSON as a body.

There are functions that will allow you to more easily access that data. You will have to integrate them into your container and coordinate those properties within a wrapping context.

Here is an example of how you would do this.

In this usage, "getProps()" is a utility to pull attributes out of the page URL/search string. You could just as well pull these values from a form.

With this example, we transport the player's usable properties into React component state.

import React, { Component } from 'react';
import _ from 'lodash';
import ReactDOM from 'react-dom';

import VoiceBasePlayer, { getVoicebaseMediaUrl, getVoicebaseAnalytics } from '@voicebase/react-player';

import getProps from './getProps';

const centerText = {
  textAlign: 'center',
  fontSize: '1rem',
};

class PlayerWrapper extends Component {
  constructor(props) {
    super(props);
    this.state = {};
  }

  static getDerivedStateFromProps(props) {
    return props;
  }

  componentDidMount() {
    if (this.state.token && this.state.mediaId) {
      getVoicebaseMediaUrl(this.state.token, this.state.mediaId)
        .then(({ url }) => {
          this.setState({ mediaUrl: url });
        })
        .catch((mediaUrlLoadError) => {
          this.setState({ mediaUrlLoadError });
        });

      getVoicebaseAnalytics(this.state.token, this.state.mediaId, this.state.apiSuffix)
        .then((analytics) => {
          this.setState({ analytics });
        })
        .catch((analyticsLoadError) => {
          this.setState({ analyticsLoadError });
        });
    } else {
      console.log('no token/media id:', this.state);
    }
  }

  render() {
    if (this.state.mediaUrlLoadError || this.state.analyticsLoadError) {
      { /-------- we have errors; display those to the user. -------/ }
      return (
        <VoiceBasePlayer error={true}>
          {this.state.mediaUrlLoadError && (
            <p style={centerText}>
              {_.get(this, 'state.mediaUrlLoadError.message', 'Error loading Media')}
            </p>
          )}
          {this.state.analyticsLoadError && (
            <p style={centerText}>
              {_.get(this, 'state.analyticsLoadError.message', 'Error loading Analytics')}
            </p>
          )}
        </VoiceBasePlayer>
      );
    } else if (this.state.mediaUrl && this.state.analytics) {
      { /-------- we can play media now. Show the player control panel. -------/ }
      return <VoiceBasePlayer {...this.state} />;
    }
   
    { /-------- Without errors OR playing fields, display the loading spinner. -------/ }
    return (
      <VoiceBasePlayer loading={true}>
        <p style={centerText}>Getting source files, please wait</p>
      </VoiceBasePlayer>
    );
  }
}

const props = getProps();

ReactDOM.render(
  <PlayerWrapper {...props} />,
  document.getElementById('root'),
);

The render() branching is useful to pore over. It only displays the VoiceBasePlayer in play mode if it has the required fields analytics and mediaUrl. analyticsFormat (an optional field with a default) may or may not be present.

render() falls through to the loading screen if no errors are present AND the required playing fields are also not complete.

Passing External Hits from the Player URL

When the player is hosted (embedded) in another program, such as the portal, you can pass in hit information in JSON format as a URL parameter to display on the right side panel.

You can specify a Section Title as well as a group title. There is also a boolean field ("showSubItems") for controlling the display of the sub items.

Here is the format of the JSON data that you must URL encode and include as the content of a URL parameter named "externalHits":

{
  "SectionTitle": "Section Title",
  "groupTitle": "Greatest Hits",
  "showSubItems": false,
  "hits": [
    {
      "s": [5433,5999],
      "e": [5667,6099],
      "label": "Hit 1"
    },
    {
      "s": [6133],
      "e": [6667],
      "label": "Hit 2"
    },
    {
      "s": [7033],
      "e": [7067],
      "label": "Hit 3"
    }
  ]
}