Maestro

Maestro is a Javascript library to stream adaptative and progressive audio stream.

Installation

Maestro is available as an AUI package therefore it should be straightforward to integrate if you are on the RetailWebsite or if you are already consuming AUI libraries. You have two solutions on how to consume Maestro.

The first one is to add MaestrojsBuzz to your version set. The second solution is to use Deploy Package Group in your Approval Workflows. Use this pipeline for reference https://pipelines.amazon.com/pipelines/DigitalMusicWebPlayerMainline.

Once your environment consumes Maestro, you can inject it in your HTML page.

AUI::AssetInjector::currentInjector()->need('MaestrojsBuzz');

Usage

//Whether Maestro can be used on the browser
Maestro.Player.isSupported();
//or
Maestro.Player.isSupported('audio/mp3');

// DRM Support
Maestro.Player.isEMESupported();

// Maestro Player instance
var player = new Maestro.Player();

// Set Maestro configuration
// More Info: https://code.amazon.com/packages/Maestrojs/blobs/7aaa714e7b6917e1bc762632be7aea5ec8627476/--/src/core/player.js#L122
player.setConfig({});

// Prefetch an mp3 file
player.load({
  id: 'track-id-123',
  url: 'http://myfile.mp3',
  duration: 100
});

// Prefetch a DASH Manifest
player.load({
  id: 'track-id-456',
  extension: 'mpd',
  manifest: '<xml></xml>'
});

// Start playback
player.play('track-id-456');
player.play('track-id-456', 30 /* start time */);

// Remove a loaded track
player.remove('track-id-456');

// List cached track ids
player.cacheList();

// Pause
player.pause();

// Resume
player.resume();

// Mute
player.mute();

// Repeat
player.repeat();

// Seek
player.seekTo(20);

// Change Volume (default 1)
player.volume(0.5);

// Get current time
player.getCurrentTime();

// Get current bitrate
player.getCurrentBitrate();

// Get buffered time
// It returns the numbers of seconds in the buffer ahead of the current time
player.getBufferedTime();

// Get duration
player.getDuration();

// Audio is playing
player.isPlaying();

// Audio is paused
player.isPaused();

// Song ended
player.isEnded();

// Song is already prefetched/loaded
player.isCached('track-id-456');

// Check if a given track is set to the current track
player.isCurrentTrackId('track-id-456')

// Audio playback is stalled
player.isStalled();

// Song is currently seeking to a new position for playback
player.isSeeking();

// Add event listeners
// Listeners:
// * paused
// * error
// * ended
// * started
// * timeupdate
// * buffertime
// * bitratechange
// * canplay
// * stalled - with two arguments: 1. {Boolean} true/after -> before/after stalled; 2. {String} current bitrate
// * seeking
// * resumed
// * expired
player.addEventListener('timeupdate', handler);

// Remove event listeners
player.removeEventListener('timeupdate', handler);

DRM

DRM requires a license server url to be provided by the client in order to initiate the license challenge. If you support multiple DRM technology, such as widevine, playready and fairplay, you need to specify a license server url for each of them.

Basic configuration:

player.setConfig({
    drm: {
        'com.widevine.alpha': {
            licenseServerUrl: 'a secure url'
        },
        com.microsoft.playready': {
            licenseServerUrl: 'a secure url'
        }
    }
})

License wrapping

If you need to decorate the request and license to the license server url you need to specify additional configuration. This will let you transform the request object and add HTTP headers, change the request body, etc. Similarly with the response, you will be able to parse and/or modify the response object before Maestro uses the response object.

Maestro is using the fetch Web API for HTTP requests. Refer to the fetch API for the request and response objects. https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

If you are an Amazon Music client, you must configure the license wrapping. Follow this CR for a working implementation in WebPlayer: https://code.amazon.com/reviews/CR-2519927/revisions/3#/diff

Advanced configuration:

player.setConfig({
    drm: {
        'com.widevine.alpha': {
            licenseServerUrl: 'a secure url',
            licenseServerRequestInterceptor: (request, trackId) => { return request; },
            licenseServerResponseInterceptor: (response) => { return response; }
        }
    }
})

Contribute

git clone ssh://git.amazon.com/pkg/Maestrojs
cd Maestrojs
npm install -g http-server

Generate a localhost SSL certificate by following those steps: https://letsencrypt.org/docs/certificates-for-localhost/

npm run server
npm run watch

Visit maestro demo page at any of the following endpoint:

https://127.0.0.1:8080/demo
https://10.219.121.137:8080/demo
https://10.219.118.29:8080/demo