Play your first video

This guide imports a video from a URL, waits for a ready asset, and produces an iframe URL. Run the example in your backend or a local Node.js script. It uses your installation’s API and the TypeScript SDK.

You need an existing Orilla installation, dashboard access to create an environment token, and a media file URL the server can fetch. If you need to run the platform first, follow deployment.

1. Install the SDK

@orilla-video/sdk 0.1.31 requires Node.js 22 or later. Create a separate directory for this example and install the package from npm:

mkdir orilla-first-video
cd orilla-first-video
npm init -y
npm install @orilla-video/sdk

The package is ESM; the .mjs script below runs directly in Node.js. See the SDK guide for the client contract and distribution details.

2. Configure backend credentials

In the dashboard, select your organization and environment. Open API tokens and create a token with View videos (video:read) and Create and edit videos (video:write) permissions. Save its ID and secret in a local .env file in the example directory:

ORILLA_API_URL="https://video.example.com"
ORILLA_TOKEN_ID="YOUR_ENVIRONMENT_TOKEN_ID"
ORILLA_TOKEN_SECRET="YOUR_ENVIRONMENT_TOKEN_SECRET"
ORILLA_SOURCE_URL="https://orilla-site.orbicloud.app/media/flower.mp4"

Replace the platform URL and both credential placeholders. ORILLA_API_URL is your platform origin: for example, https://video.example.com or http://127.0.0.1:18080 for the local deployment. Do not append /video/v1, /v1, or /api. The SDK adds route paths such as /video/v1/assets and /embed/PLAYBACK_ID itself.

ORILLA_SOURCE_URL uses the public flower demo video hosted with the Orilla site. You can replace it with a small video you are allowed to publish. The URL must point directly to media your server can retrieve over HTTP(S); a webpage containing a player is not a source file. An expiring source URL must remain valid long enough for the worker to fetch it. See URL imports for supported sources and limits.

Keep .env out of version control and frontend build configuration. Add it to the example project’s .gitignore:

.env

3. Create an asset and wait for it

Save this complete script as first-video.mjs in the example directory. The SDK returns the asset directly from create and retrieve; you do not need to unwrap a data property.

import { setTimeout as sleep } from "node:timers/promises";
import { Orilla, OrillaAPIError } from "@orilla-video/sdk";

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} in your backend environment.`);
  return value;
}

async function waitUntilReady(orilla, asset) {
  const signal = AbortSignal.timeout(5 * 60 * 1000);

  try {
    while (asset.status !== "ready") {
      if (asset.status === "errored") {
        const detail =
          asset.errors?.messages?.join(" ") ||
          "Inspect the asset in the dashboard.";
        throw new Error(`Processing failed for ${asset.id}: ${detail}`);
      }

      await sleep(2000, undefined, { signal });
      asset = await orilla.assets.retrieve(asset.id, { signal });
    }

    return asset;
  } catch (error) {
    if (signal.aborted) {
      throw new Error(
        `Stopped waiting after five minutes. Asset ${asset.id} may still be processing; resume with ORILLA_ASSET_ID=${asset.id}.`,
        { cause: error },
      );
    }
    throw error;
  }
}

async function main() {
  const orilla = new Orilla({
    baseURL: required("ORILLA_API_URL"),
    tokenId: required("ORILLA_TOKEN_ID"),
    tokenSecret: required("ORILLA_TOKEN_SECRET"),
  });

  const identity = await orilla.whoami();
  console.log(`Environment: ${identity.environment_name}`);

  // Resume an existing asset instead of importing a duplicate after a timeout.
  const asset = process.env.ORILLA_ASSET_ID
    ? await orilla.assets.retrieve(process.env.ORILLA_ASSET_ID)
    : await orilla.assets.create({
        inputs: [{ url: required("ORILLA_SOURCE_URL") }],
        playback_policies: ["public"],
        meta: { title: "My first Orilla video" },
      });

  console.log(`Asset ID: ${asset.id}`);
  console.log(`Status: ${asset.status}`);

  const ready = await waitUntilReady(orilla, asset);
  const playback = ready.playback_ids.find((item) => item.policy === "public");
  if (!playback) {
    throw new Error(
      "This asset has no public playback ID. Check its access policy.",
    );
  }

  console.log("Status: ready");
  console.log(`Playback ID: ${playback.id}`);
  console.log(`Embed URL: ${orilla.media.embedURL(playback.id)}`);
}

main().catch((error) => {
  if (error instanceof OrillaAPIError) {
    console.error(
      `API ${error.status} (${error.type}): ${error.messages.join(" ")}`,
    );
  } else {
    console.error(
      error instanceof Error ? error.message : "The request failed.",
    );
  }
  process.exitCode = 1;
});

Run it with Node.js loading your local environment file:

node --env-file=.env first-video.mjs

The first response may be preparing. The script polls every two seconds and prints a player URL only after the asset is ready. It stops on errored or after five minutes. Each SDK request also has its own default 30-second timeout.

The five-minute polling limit does not cancel processing. Keep the printed asset ID. To check that same asset later, replace the example ID below and run:

ORILLA_ASSET_ID="YOUR_ASSET_ID" node --env-file=.env first-video.mjs

For a production application, save the asset ID with your own content record. Use a verified, deduplicated video.asset.ready webhook to update that record when processing finishes.

4. Embed the ready video

Copy the printed Embed URL into your page. It has this structure; replace the domain and playback ID with the script’s output:

<iframe
  src="https://video.example.com/embed/YOUR_PUBLIC_PLAYBACK_ID"
  title="My first Orilla video"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen
  style="width:100%;aspect-ratio:16/9;border:0"
></iframe>

Open the page and play the video. The iframe URL contains the playback ID, not the asset ID. Your page needs no API token ID or secret. Use the player guide when you need React, the HTML element, or signed URL renewal.

If the example stops

Result	What to check
`401`	The environment token ID and secret are correct and the token has not been revoked.
`403`	The token has both `video:read` and `video:write` permissions.
Asset becomes `errored`	Read the returned processing messages. Confirm the source is fetchable by the server and within supported limits.
Polling reaches five minutes	Inspect the existing asset and processing worker. Resume with its asset ID; a slow import may still be running.
A request times out or loses its response	Check the dashboard before submitting another create request; the first request may already have created an asset.
The iframe does not play	Use the printed public playback ID, confirm the asset is ready, and check the installation’s public HTTPS origin and media routes.

Continue with fundamentals for the resource model, direct uploads for local files, or access control before publishing restricted content.