@streamlet/sdk

Official JavaScript/TypeScript SDK for Streamlet — upload videos, upload images, track processing status, and embed a ready-made player in React apps.

Table of Contents

• Install
• Quick Start
• Authentication
• Video Upload
• Video Status
• Polling Until Complete
• Image Upload
• Document Upload
• React Player
• API Reference
• Supported Caption Languages
• Plan Limits
• Templates
• Documentation

Install

npm install @streamlet/sdk

The React player is included in the same package — no separate install needed:

import { StreamletPlayer } from "@streamlet/sdk/react";

Quick Start

import { StreamletClient } from "@streamlet/sdk";

const client = new StreamletClient({
  baseUrl: "https://api.streamlet.in",
  apiKey: "YOUR_API_KEY",
  accountNumber: "YOUR_ACCOUNT_NUMBER",
});

// Upload a video
const upload = await client.uploadVideo({ file, videoTitle: "Demo" });

// Poll until encoding is done
const result = await client.pollVideoStatus(upload.videoId);

console.log(result.streamUrl);   // ready-to-embed stream URL
console.log(result.thumbnail);   // poster/thumbnail URL

Authentication

Every request uses your API key and account number. Get them from the Streamlet dashboard.

const client = new StreamletClient({
  baseUrl: "https://api.streamlet.in",
  apiKey: "YOUR_API_KEY",
  accountNumber: "YOUR_ACCOUNT_NUMBER",
});

Both values are sent as request headers (x-streamlet-api-key, x-streamlet-account-number) — never exposed in URLs.

Video Upload

const result = await client.uploadVideo({
  file,                          // File object (required)
  videoTitle: "Product Demo",    // defaults to filename
  saveOriginalFile: false,       // keep the original file after processing
  autoAudioEnhancement: true,    // normalise audio levels
  storageSaverEncoding: false,   // smaller HLS files, slower processing
  enableCaption: true,           // generate captions
  captionLanguages: ["english", "hindi", "tamil"],
  enable2kOutput: false,         // Builder and Pro plans — add 1440p rendition
  enable4kOutput: false,         // Pro plan only — add 2160p rendition
});

console.log(result.videoId);   // use this to track progress
console.log(result.status);    // "queued"
console.log(result.statusUrl); // direct URL to poll status

Upload is asynchronous — the video is queued for encoding. Use getVideoStatus or pollVideoStatus to track progress.

Video Status

Check the current state of a video at any time:

const status = await client.getVideoStatus("your_video_id");

console.log(status.status);      // "queued" | "processing" | "completed" | "failed"
console.log(status.videoTitle);
console.log(status.streamUrl);   // available once status === "completed"
console.log(status.thumbnail);
console.log(status.captions);    // array of available caption languages

Polling Until Complete

pollVideoStatus handles the polling loop for you — no setInterval needed:

const final = await client.pollVideoStatus("your_video_id", {
  interval: 4000,           // check every 4 seconds (default)
  timeout: 600000,          // give up after 10 minutes (default)
  onProgress: (status) => {
    console.log("Status:", status.status);
  },
});

if (final.status === "completed") {
  console.log(final.streamUrl);
  console.log(final.thumbnail);
  console.log(final.captions);
} else {
  console.error("Processing failed or timed out");
}

| Option | Type | Default | Description | |---|---|---|---| | interval | number | 4000 | Milliseconds between each status check | | timeout | number | 600000 | Max total wait time in ms before rejecting | | onProgress | function | — | Called with the latest status on every poll tick |

Polling stops automatically when status is "completed" or "failed".

Image Upload

const image = await client.uploadImage({ file: imageFile });

console.log(image.imageId);   // unique image identifier
console.log(image.cdnUrl);    // public URL to serve the image from
console.log(image.width);
console.log(image.height);
console.log(image.sizeBytes); // processed file size in bytes

Images are automatically:

• Rotated based on EXIF orientation
• Resized to a max width of 2000px (aspect ratio preserved)
• Converted to WebP at quality 85

Accepted formats: JPEG, PNG, WebP, AVIF, GIF — max 20 MB per file.

Document Upload

const doc = await client.uploadDocument({ file: pdfFile });

console.log(doc.documentId);        // unique document identifier
console.log(doc.cdnUrl);            // permanent public URL for the PDF
console.log(doc.originalFilename);  // original filename
console.log(doc.sizeBytes);         // file size in bytes

Accepted format: PDF only — max 50 MB per file.

The document is stored as-is and served directly from the CDN. The URL is permanent and ready to embed or link to immediately.

React Player

Import the player from the /react subpath:

import { StreamletPlayer } from "@streamlet/sdk/react";

function VideoPage({ status }) {
  return (
    <StreamletPlayer
      title="Product Demo"
      streamUrl={status.streamUrl}
      posterUrl={status.thumbnail}
      captionLanguages={["english", "hindi"]}
      chaptersUrl={status.chapters?.json}
      chapterTrackUrl={status.chapters?.vtt}
      ownerName="Acme Inc."
      createdAt={status.createdAt}
    />
  );
}

Player Props

| Prop | Type | Default | Description | |---|---|---|---| | streamUrl | string | — | Video stream URL from a completed upload (required) | | title | string | — | Video title shown above the player | | posterUrl | string | — | Thumbnail/poster image URL | | captionLanguages | string[] | ["english"] | Languages to load captions for | | chaptersUrl | string | — | URL to a chapters JSON file | | chapterTrackUrl | string | — | URL to a WebVTT chapter track file | | ownerName | string | — | Creator/owner display name | | createdAt | string \| Date | — | Upload timestamp | | theme | object | — | Custom colour overrides (see below) | | showMeta | boolean | true | Show title and metadata section | | showTimeline | boolean | true | Show the chapter timeline bar | | showChapterSidebar | boolean | true | Show the chapters list sidebar | | emptyMessage | string | — | Message shown when no streamUrl is provided |

Theme

Pass a theme object to override any default colour:

<StreamletPlayer
  streamUrl={status.streamUrl}
  theme={{
    accentColor: "#6366f1",
    progressFillColor: "#6366f1",
    primaryColor: "#ffffff",
    secondaryColor: "#a1a1aa",
    borderColor: "#27272a",
    surfaceColor: "#18181b",
    panelColor: "#09090b",
  }}
/>

API Reference

new StreamletClient(config)

| Field | Type | Description | |---|---|---| | baseUrl | string | Backend API base URL | | apiKey | string | Your Streamlet API key | | accountNumber | string | Your Streamlet account number |

client.uploadVideo(input)

| Field | Type | Required | Description | |---|---|---|---| | file | File | Yes | Video file to upload | | videoTitle | string | No | Title for the video (defaults to filename) | | saveOriginalFile | boolean | No | Preserve the original file post-processing | | autoAudioEnhancement | boolean | No | Auto-normalise audio (default true) | | storageSaverEncoding | boolean | No | Use slower, more storage-efficient H.264 encoding | | videoOptimization | "fast" \| "storage_saver" | No | Explicit encoding mode; storageSaverEncoding is a boolean shortcut | | enableCaption | boolean | No | Generate captions | | captionLanguages | string[] | No | Languages to caption (see Supported Languages) | | enable2kOutput | boolean | No | Add 1440p (2K) top rendition to the HLS ladder — Builder and Pro plans only | | enable4kOutput | boolean | No | Add 2160p (4K) top rendition to the HLS ladder — Pro plan only |

Returns { videoId, status, statusUrl, ... }.

client.getVideoStatus(videoId)

| Field | Type | Description | |---|---|---| | videoId | string | The video ID returned from uploadVideo |

Returns the current processing state including status, streamUrl, thumbnail, captions, videoTitle, and more.

client.pollVideoStatus(videoId, options?)

| Field | Type | Default | Description | |---|---|---|---| | videoId | string | — | Required. Video ID to poll | | options.interval | number | 4000 | Poll interval in ms | | options.timeout | number | 600000 | Max wait time in ms | | options.onProgress | (status) => void | — | Called on each poll tick |

Returns the final status object when processing completes or fails.

client.uploadImage(input)

| Field | Type | Required | Description | |---|---|---|---| | file | File | Yes | Image file to upload |

Returns { imageId, cdnUrl, width, height, sizeBytes }.

client.uploadDocument(input)

| Field | Type | Required | Description | |---|---|---|---| | file | File | Yes | PDF file to upload |

Returns { documentId, cdnUrl, originalFilename, sizeBytes }.

client.getHealth()

Checks if the backend API is reachable. Returns { status, uptime, memory, queues }.

Supported Caption Languages

Pass any combination of these values in captionLanguages:

| Value | Language | |---|---| | "english" | English | | "hindi" | Hindi | | "tamil" | Tamil | | "telugu" | Telugu | | "kannada" | Kannada | | "malayalam" | Malayalam |

Plan Limits

| Feature | Free | Starter | Builder | Pro | |---|---|---|---|---| | Max video duration | 6 minutes | Unlimited | Unlimited | Unlimited | | Storage | 1 GB | 50 GB | 200 GB | 500 GB | | Max resolution | 480p | 720p | 2K (1440p) | 4K (2160p) | | Caption quota / month | 10 min | 5 hours | 25 hours | 50 hours | | 2K output (enable2kOutput) | No | No | Yes | Yes | | 4K output (enable4kOutput) | No | No | No | Yes | | Watermark | Forced streamlet.in | Optional | Optional | Optional |

Caption quota resets on the 1st of each month. Uploads with enableCaption: true that exceed the quota are rejected with error code CAPTION_QUOTA_EXCEEDED.

Full Example

import { StreamletClient } from "@streamlet/sdk";

const client = new StreamletClient({
  baseUrl: "https://api.streamlet.in",
  apiKey: process.env.STREAMLET_API_KEY,
  accountNumber: process.env.STREAMLET_ACCOUNT_NUMBER,
});

async function processVideo(file) {
  // 1. Upload
  const upload = await client.uploadVideo({
    file,
    videoTitle: "Onboarding Walkthrough",
    enableCaption: true,
    captionLanguages: ["english", "hindi"],
    autoAudioEnhancement: true,
    enable2kOutput: false,  // set true on Builder/Pro to add 1440p rendition
    enable4kOutput: false,  // set true on Pro to add 2160p rendition
  });

  console.log("Queued:", upload.videoId);

  // 2. Poll until done
  const result = await client.pollVideoStatus(upload.videoId, {
    interval: 5000,
    timeout: 900000,
    onProgress: ({ status }) => console.log("→", status),
  });

  if (result.status !== "completed") {
    throw new Error("Processing failed");
  }

  // 3. Use the output
  console.log("Stream URL:", result.streamUrl);
  console.log("Thumbnail:", result.thumbnail);
  console.log("Captions:", result.captions);

  return result;
}

Templates

Starter integration templates for common frameworks and languages:

Streamlet-Templates

Documentation

Full API docs, guides, and dashboard:

docs.streamlet.in

Author - shangesh

License

MIT