If you are known and comfortable with the <audio> element in de browser, or Audio in JavaScript you will be just fine. These two are just an implementation of the HTMLAudioElement.

We can use this element to be able to playback audio in the browser. Audio that is related to the so called "reference audio", or audio that you have recorded with our recorder.

Getting started

The package is available on npm. This is the preferred way of usage. Installing the package is as easy as running npm install in the project root where you want to use it.

npm install @itslanguage/player

An example usage, in code:

import createPlayer from '@itslanguage/player';

// Choose an URL to play.
const audioUrl =
  'https://ia801605.us.archive.org/5/items/rainbowgold_1705_librivox/rainbowgold_10_various_128kb.mp3';

// Create a HTMLAudioElement instance.
const player = createPlayer(audioUrl);

// At this point our player is ready to rock and roll.
// To start playback, you only need to do this, but mind the note below!
player.play();

A special note has to be made about the player.play() method as shown above. Calling it as shown above would be seen, from the browsers point of view, as autoplay. And autoplay is not available by default. The reason why this is autoplay: the user does has not interacted with some element to trigger playback.

In a more realistic use case, one would let a user click a button (like a play button) to playback some audio.

Autoplay is allowed when the audio track is muted. This makes sense for video of course, but for audio this will not help.

More information here: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#attr-autoplay

Unpkg.com

Note that it is also possible to use an UMD version that has been made available through unpkg.com. You can do so by placing a script tag inside your HTML and your're good to go. The features that this library exposes will be set to the global itslPlayer object. A simplistic example, which does not follow any best practices (i.e. use at your own risk):

<!DOCTYPE html>
<html>
  <head>
    <title>Some page title</title>
    <script src="https://unpkg.com/@itslanguage/player@v5.0.0/dist/player.min.js"></script>
    <script>
      // The api is now available through global `itslPlayer`.
      const audioUrl =
        'https://ia801605.us.archive.org/5/items/rainbowgold_1705_librivox/rainbowgold_10_various_128kb.mp3';
      const player = itslPlayer.createPlayer(audioUrl);

      // We will use this function as the event handler for the button on the page
      function playAudio() {
        player.play();
      }
    </script>
  </head>
  <body>
    <button onClick="playAudio">Play</button>
  </body>
</html>

API

createPlayer

createPlayer(
  [(audioUrl = null)],
  [(secureLoad = false)],
  [(crossOrigin = null)],
);

Create a new instance of a HTMLAudioElement (i.e. new Audio() or <audio></audio>).

Arguments

[audioUrl = null: string]: optionally, pass an URL to load.
[secureLoad = false: boolean]: optionally, add an authorization to the request to download the audio fragment. This is needed to load audio from the ITSLanguage backend where you need to be authorised to listen to. Note that if you don't pass an audioUrl, it will skip this flag.
[crossOrigin = null: CorsMode]: optionally pass the crossOrigin mode that needs to be set on the audio player. Valid values are defined by the CorsMode object.

loadAudioUrl

loadAudioUrl(player, audioUrl, [(secureLoad = false)]);

Load a (new) url to an instance of a HTMLAudioElement. Main purpose of this function is to support a way to add a new url with an "access_token". But it also works for url's in general.

Arguments

player: HTMLAudioElement: the element to change src on. Element is expected to be an instance of HTMLAudioElement
audioUrl: string: pass the url to set as src.
[secureLoad = false: boolean]: optionally, add an authorization to the request to download the audio fragment. This is needed to load audio from the ITSLanguage backend where you need to be authorised to listen to. Note that if you don't pass an audioUrl, it will skip this flag.

To read more on the HTMLAudioElement and learn what you can do with, visit MDN: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement

More on the <audio> element (which implements the HTMLAudioElement): https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio

The audio player that this little library exposes is perfectly capable in what it should do: playback audio in a sophisticated way with a rich interface, thanks to the way HTMLAudioElement is defined (HTMLAudioElement -> HTMLMediaElement -> HTMLElement -> Element -> Node -> EventTarget).

If you find yourself in a situation you want more out of your audio player, don't hesitate to contact us but also make sure to read up on the Web Audio API in general on MDN: https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API

[v5.3.0] - 2020-01-10

Fixed

api
- Only unregister an autobahn registration if there is actually an registration registered.
- Reset the lastChunk after it is used.
- Really cleanup some event listeners on the recorder after they have been used for streaming audio to the backend.
- TypeError raised by makeWebsocketCall.
- Allow to pass groups as a string (next to an array) and disallow other types. This is for the getById function of the Progress API.

Changed

api, recorder, player, examples, sdk
- Bumped used package versions.
- Upgraded yarn.lock file.

Keywords

FAQs

What is @itslanguage/player?

Is @itslanguage/player well maintained?

Package last updated on 09 Jan 2020

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@itslanguage/player