Python¶

The rightra package provides server-side helpers for Django, Flask, and any other Python backend. It mints upload tokens, signs S3 and R2 uploads, and calls the Rightra API. It has no runtime dependencies. The browser player is loaded separately. See Browser SDK.

Requirements¶

Python 3.9 or later

Installation¶

pip install rightra

Configuration¶

RIGHTRA_API_KEY=rk_live_your_key
RIGHTRA_UPLOAD_SECRET=your-upload-secret
RIGHTRA_UPLOAD_TOKEN_TTL=900

Variable	Required	Description
`RIGHTRA_API_KEY`	Yes	API key. Without it, every API call fails closed.
`RIGHTRA_UPLOAD_SECRET`	Yes	Secret used to sign upload tokens. Must match the secret in `rightra-upload.php`.
`RIGHTRA_UPLOAD_TOKEN_TTL`	No	Upload token lifetime in seconds. Default 900.

The package does not read the environment itself. Load values in your application and pass them explicitly.

Upload tokens¶

import os
import rightra

token = rightra.mint_upload_token(
    "RTR-853D-52D0",
    secret=os.environ["RIGHTRA_UPLOAD_SECRET"],
)

The output matches the format produced by the PHP and Laravel helpers. See Upload tokens.

To validate a token in your own backend, for example when proxying uploads:

rightra.verify_upload_token(token, content_id, secret)

API client¶

import os
from rightra import Client

client = Client(api_key=os.environ["RIGHTRA_API_KEY"])

The client targets the production Rightra API by default.

Method	Description
`register_content(...)`	Registers a work and returns its content ID.
`get_content(content_id)`	Returns a content item.
`set_manifest(content_id, manifest_url=...)`	Stores the manifest URL.
`set_encryption_key(content_id, key_material=...)`	Stores an encryption key. Required only when encrypting on the server.
`queue_fingerprint(content_id, reference_material=..., reference_type=...)`	Queues a fingerprint job.
`create_playback_session(content_id, viewer_id=..., ...)`	Creates a playback session.
`playback_event(session_id=..., event=..., ...)`	Records a playback event.
`request_download(session_id)`	Starts a download job.
`download_status(job_id)`	Returns download job status.
`download_file(job_id, path)`	Streams a completed download to disk.

Request and response schemas are in the API reference.

Register and configure content¶

created = client.register_content(
    title="My Film",
    type="film",
    description="Feature length film.",
    creator_name="Example Studio",
)
content_id = created["content"]["content_id"]

client.set_manifest(
    content_id,
    manifest_url="https://your-storage.example/manifest.json",
)

Create a playback session¶

session = client.create_playback_session(
    content_id,
    viewer_id=str(request.user.id),
    viewer_label=request.user.get_full_name(),
    territory="RW",
)

viewer_id is required. The API rejects requests without it.

Record playback events¶

client.playback_event(
    session_id=session["session_id"],
    event="heartbeat",
    seconds_watched=30,
)

Valid events are start, progress, heartbeat, pause, seek, ended, and error.

Download¶

job = client.request_download(session["session_id"])

status = client.download_status(job["job_id"])   # poll until "ready"
client.download_file(job["job_id"], "output.mp4")

Presigned uploads¶

Sign PUT URLs for S3 or R2 without boto3. Both functions return a fully signed URL. Send the object with PUT <url>.

S3R2

import os
from rightra import sign_s3_put

put_url = sign_s3_put(
    access_key=os.environ["AWS_ACCESS_KEY_ID"],
    secret_key=os.environ["AWS_SECRET_ACCESS_KEY"],
    bucket="my-rightra-bucket",
    key=f"uploads/{content_id}/seg-0.enc",
    region="us-east-1",
)

import os
from rightra import sign_r2_put

put_url = sign_r2_put(
    account_id=os.environ["R2_ACCOUNT_ID"],
    access_key=os.environ["R2_ACCESS_KEY_ID"],
    secret_key=os.environ["R2_SECRET_ACCESS_KEY"],
    bucket="rightra",
    key=f"uploads/{content_id}/seg-0.enc",
)

Error handling¶

All failures raise rightra.RightraError.

Attribute	Description
`status`	HTTP status code. `0` for network errors.
`code`	Error code returned by the API.
`message`	Human-readable description.

from rightra import RightraError

try:
    client.set_manifest(content_id, manifest_url=url)
except RightraError as e:
    log.error("Rightra request failed: %s (%s, status %s)", e.message, e.code, e.status)

Error codes are listed in the API reference.

Framework integration¶

The package has no app context or settings lookup. Create one client from your own configuration.

DjangoFlask

# settings.py
RIGHTRA_API_KEY = os.environ["RIGHTRA_API_KEY"]
RIGHTRA_UPLOAD_SECRET = os.environ["RIGHTRA_UPLOAD_SECRET"]

# rightra_client.py
from django.conf import settings
from rightra import Client

client = Client(api_key=settings.RIGHTRA_API_KEY)

import os
from flask import Flask
from rightra import Client

def create_app():
    app = Flask(__name__)
    app.extensions["rightra"] = Client(api_key=os.environ["RIGHTRA_API_KEY"])
    return app