Browser SDK¶

@oliviuus/rightra-sdk registers works, plays encrypted content, and applies per-session watermarks. It runs in the browser and does not host media. Encrypted segments stay on your own storage.

Installation¶

npm install @oliviuus/rightra-sdk

Without a bundler, load the UMD build with a version-pinned script tag:

<script src="https://unpkg.com/@oliviuus/rightra-sdk@0.1.3/dist/rightra.umd.js"></script>

Initialization¶

import { Rightra } from "@oliviuus/rightra-sdk";

const rightra = Rightra.init({ apiKey: "rk_live_your_key" });

The key must begin with rk_live_ or rk_test_. A missing or malformed key throws RightraError with code INVALID_API_KEY.

Registering a work¶

registerWork encrypts the file one segment at a time and passes each segment to your uploadSegments callback. Your callback decides where segments are stored.

await rightra.registerWork({
  file,
  title: "My Film",
  type: "film",
  description: "Feature length film.",
  creator_name: "Example Studio",
  rights_holder_name: "Example Studio",
  uploadSegments: async ({ contentId, index, total, segment, iv, isInit }) => {
    const target = await fetch("/my-backend/sign-upload", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ contentId, index }),
    }).then((r) => r.json());

    await fetch(target.url, { method: "PUT", body: segment });
    return { url: target.publicUrl };
  },
  onProgress: ({ stage, done, total }) => console.log(stage, done, total),
});

Parameters¶

Parameter	Type	Required	Description
`file`	`File`	Yes	MP4 file to protect. Non-fragmented files are fragmented in the browser first.
`title`	`string`	Yes	Title of the work.
`type`	`string`	Yes	Content type, for example `film`, `song`, or `narration`.
`description`	`string`	No	Free-text description.
`creator_name`	`string`	No	Creator name.
`rights_holder_name`	`string`	No	Rights holder name.
`uploadSegments`	`function`	Yes	Called once per segment. Must return `{ url }`.
`segmentBytes`	`number`	No	Target segment size. Default 4 MB.
`onProgress`	`function`	No	Called with `{ stage, done, total }`.

`uploadSegments` callback¶

Argument	Description
`contentId`	Rightra content ID.
`index`	Zero-based segment index.
`total`	Total number of segments.
`segment`	Encrypted segment bytes.
`iv`	12-byte initialization vector for the segment.
`isInit`	`true` for the initialization segment.

Return { url } with the public URL from which the segment can be fetched. The SDK calls the callback once per segment and once more for the manifest.

Playing a work¶

const player = await rightra.createPlayer(document.getElementById("player"), {
  contentId: "RTR-853D-52D0",
  manifestUrl: "https://your-storage.example/manifest.json",
  viewer: { id: "user-123", label: "Jane" },
  territory: "RW",
});

await player.play();

Options¶

Option	Required	Description
`contentId`	Yes	Rightra content ID.
`manifestUrl`	Yes	URL of the manifest on your storage.
`viewer.id`	Yes	Stable viewer identifier from your own system. Playback fails closed without it.
`viewer.label`	No	Display label.
`territory`	No	Two-letter territory code for the session.

Player methods¶

Method	Description
`play()`	Starts playback.
`pause()`	Pauses playback.
`destroy()`	Stops playback and releases resources.

The player applies three watermark layers to every session. See Watermarks.

Error handling¶

All failures throw RightraError with code, message, and status.

import { RightraError } from "@oliviuus/rightra-sdk";

try {
  await player.play();
} catch (err) {
  if (err instanceof RightraError) {
    console.error(err.code, err.message, err.status);
  }
}

Errors raised by the SDK itself:

Code	Description
`INVALID_API_KEY`	The API key is missing or malformed.
`TIMEOUT`	A request took longer than 30 seconds.
`NETWORK`	The request could not reach the API.

Errors returned by the API, such as VIEWER_REQUIRED, CONTENT_NOT_FOUND, and SESSION_EXPIRED, are listed in the API reference.