@jaak/playback

@jaak/playback

Simplified interactions with the JAAK Playback API

⚠️ This repo is under active development and the API is likely to change without warning ⚠️

Installation

npm i @jaak/playback

Usage

First, initialise the JAAK JavaScript library with the application ID and private key registered with that application. This information can be found on your application dashboard.

import JAAK from '@jaak/playback'

const jaak = new JAAK({
  applicationId: APPLICATION_ID,
  privateKey: PRIVATE_KEY,
})

With your authenticated jaak instance you can now sign JAAK API requests using the request class method.

const getTracks = await jaak.request({
  query: `
    query Tracks($trackID: String!) {
      tracks(filter: { trackID: $trackID }) {
        ...
      }
    }
  `,
  variables: {
    trackID: 'track-1'
  }
})

Registering devices

You need to register devices with the JAAK API to permit them to stream tracks that you have licensed through your application. These devices can then make authenticated requests with their own set of keys to consume content.

You will need to generate account keys for any new device. This device then needs to be associated with your application and registered with JAAK.

import { JAAK, generateAccountKeys } from '@jaak/playback'

const device = generateAccountKeys()

const jaak = new JAAK({
  applicationId: APPLICATION_ID,
  privateKey: device.privateKey
})

await jaak.registerDevice(device)

Generating an access voucher

To stream a track a device will need to generate an access voucher to request an asset from the JAAK API.

import { generateAccessVoucher } from '@jaak/playback'

const accessVoucher = generateAccessVoucher(track.licenseID, device.privateKey)

Streaming audio

Once you have content in your application you can stream it using your access voucher and any track's asset hash.

const audioSrcUrl = `https://playback.beta.jaak.io/asset/${
  track.hash
}?access_voucher=${accessVoucher}`

<audio
  src=`${audioSrcUrl}`
  controls
/>

API

Exported functions

Name	Arguments	Returns	Description
generateAccessVoucher	(licenseId: String, privateKey: String[, nonce: String])	String	Generates a JAAK access voucher for requesting assets
generateAccountKeys	none	Object	Generates an account object that can be used for registering devices
generateES256KJWT	(payload: Object, privateKey: String)	String	Generates a JWT encoded with a payload and account object
getAccountFromPrivateKey	(privateKey: String)	Object	Generates an account object from a provided private key
JAAK	({ privateKey: String [, applicationId: String ]})	Class	Creates new class instance with authorisation credentials
sendSignedRequest	(payload: Object, uri: String, privateKey: String)	Promise	Used to make requests to the JAAK API, resolves to a GraphQL response object

JAAK class

The JAAK class can be used to to create an authorised jaak instance that allows you to call the exported functions without having to provide information for creating signatures. Along with the exported functions your jaak instance gives you access to some additional utilities.

Name	Arguments	Returns	Description
generateAccessVoucher	(licenseId: String[, nonce: String])	String	Generates a JAAK access voucher for requesting assets
generateES256KJWT	(payload: Object)	String	Generates a JWT encoded with a payload and account object.
registerDevice	(device: Object)	Promise	Convenience method for registering new user devices, performs a network request. Resolves to GraphQL response object.
request	(payload: Object)	Promise	Used to make requests to the JAAK API, resolves to a GraphQL response object.

Contributing 🙋‍♀️

All proposed changes must start in an issue, following the guidelines provided in the issue template. Once the work has been carried out locally on an up-to-date working copy of master a pull request should be opened, following the guidelines provided in the pull request template.

Setup 🏗

These commands are for setting the environment up to contribute to the package.

First run an npm install:

npm install

Test 🃏

Prior to opening a pull request for your changes regression tests must be run. If your changes depend on fixture data please do not edit existing fixture data instead add new data.

npm test