Video player, captions and analytics

​

Goal

​

Prerequisites

• A ready native-video package and access to its asset ID.
• The shared Assets player package and its stylesheet installed in your application.
• For private videos, an application backend that authenticates viewers and authorizes each requested asset.

​

Workflow

​

Package installation and lifecycle

npm --prefix packages/assets-player ci
npm --prefix packages/assets-player run build
# Run in your application directory, using your actual checkout path:
npm install /path/to/stackshift/packages/assets-player

​

Working browser callbacks for a public video

const apiOrigin = 'https://api.stackshift.cloud'
const assetId = 'YOUR_PUBLIC_VIDEO_ASSET_ID'

async function playbackPost(path, credential, body) {
  const response = await fetch(apiOrigin + path, {
    method: 'POST', cache: 'no-store', credentials: 'omit',
    headers: {
      ...(credential ? { Authorization: `Bearer ${credential}` } : {}),
      ...(body ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  })
  if (!response.ok) {
    throw Object.assign(new Error('Playback request failed'), {
      status: response.status,
    })
  }
  return (await response.json()).data
}

export const playbackOptions = {
  getSession: () => playbackPost(
    `/playback/assets/${encodeURIComponent(assetId)}/sessions`
  ),
  renewSession: grant => playbackPost(
    '/playback/sessions/renew', grant.credential
  ),
  sendEvents: (grant, events) => playbackPost(
    '/playback/events', grant.credential, { events }
  ),
}

​

React and plain JavaScript embeds

import { StackshiftAssetsPlayer } from '@stackshift-cloud/assets-player/react'
import '@stackshift-cloud/assets-player/style.css'
import { playbackOptions } from './playback-options'

export function ProductVideo() {
  return <StackshiftAssetsPlayer
    {...playbackOptions}
    title="Product demonstration"
    controls
    showTitle
    autoplay={false}
  />
}

import { createAssetsPlayer } from '@stackshift-cloud/assets-player'
import '@stackshift-cloud/assets-player/style.css'
import { playbackOptions } from './playback-options.js'

const host = document.querySelector('#product-video')
if (!host) throw new Error('Missing player host')
const player = createAssetsPlayer(host, {
  ...playbackOptions, title: 'Product demonstration', controls: true,
})
// Call when the containing page/component is removed:
// player.destroy()

​

Private-session backend contract

// Trusted backend only, after your application has authorized this viewer.
const grant = await stackshift.assets.video.createSession(authorizedAssetId)
return Response.json({ success: true, data: grant }, {
  status: 201,
  headers: { 'Cache-Control': 'private, no-store' },
})

​

Options and recovery behavior

• Required: getSession(). Optional: renewSession(grant), sendEvents(grant, events), onError(code), title, showTitle, poster, controls, autoplay, muted, loop, phase and phaseDetail.
• Defaults: controls enabled, user-initiated playback. Autoplay requests are muted. Responsive sizing follows the host; there is no separate responsive option in this interface.
• The browser bundle is dist/player.js with dist/style.css. Self-host both; its global API is StackshiftAssetsPlayer.createAssetsPlayer. Do not invent a hosted CDN package URL.
• Use native HLS when available, otherwise bundled HLS.js. Unsupported or irrecoverable media errors can fall back to MP4; 401/403 authorization failures must not trigger access-bypassing fallback.
• Renewal is scheduled one minute before expiry; without a renewal callback playback stops at expiry. Transient renewal failures retry only while the current grant remains valid. Preserve numeric error.status so expired/revoked states are distinguishable.
• Settings expose available quality choices and Auto separately from observed playback quality. Speeds are 0.5, 0.75, 1, 1.25, 1.5 and 2×; unsupported picture-in-picture controls are omitted.
• Keyboard: Tab to controls, arrows/Home/End in menus, Escape to dismiss and restore focus. On the player surface Space/K toggles playback, arrows seek five seconds, M mutes and F enters fullscreen. Native OS fullscreen may use different controls.

​

Caption ingestion and validation

• Maximum file size: 2 MiB. A WEBVTT header must be followed by a blank line. UTF-8 BOM and CRLF line endings are accepted; NUL bytes are rejected.
• Use 1–20,000 cues with nondecreasing start times and positive durations. Timestamps use mm:ss.mmm or hh:mm:ss.mmm within the validator’s 24-hour limit.
• NOTE blocks are allowed. STYLE and REGION blocks are rejected. Only the supported standard vertical/align/size/position/line cue settings are accepted; duplicate settings are invalid.
• language must parse as a language tag, such as en or fr. label is required and limited to 80 bytes by the service. kind is captions or subtitles.
• Cues are rendered through browser text tracks, not inserted as raw HTML.

WEBVTT

00:00.000 --> 00:03.000
A full view of the product.

00:03.000 --> 00:06.000
The side panel opens to reveal the controls.

const track = await stackshift.assets.video.addCaption(assetId, versionId, {
  caption_asset_id: captionAssetId,
  caption_version_id: captionVersionId,
  language: 'en', label: 'English', kind: 'captions', is_default: true,
})
const tracks = await stackshift.assets.video.captions(assetId, versionId)

​

Caption replacement, removal and authorization

​

Telemetry contract and interpretation

• Batch size: 1–64 events; body limit 16 KiB. Admission rejects a batch when existing events in the last minute plus its size exceed 120 for that session.
• Each event has sequence, kind and value. Sequence is an integer from 0 to 100000. Use monotonically increasing values and retain the same sequence numbers when retrying a failed batch.
• kind is startup, rebuffer, error, quality, watched or completed. value must be finite and nonnegative, at most 86400000; startup/rebuffer/watched duration values use milliseconds.
• Duplicate (session, sequence) events do not increment aggregates again. Events are session-scoped and revalidated against current authorization.
• GET /api/v1/assets/{assetID}/video/analytics or assets.video.analytics(assetId) requires assets:read. It returns starts, completions, errors, startup_ms, rebuffer_ms and watched_ms across the current UTC day and previous 29 days.
• Duration fields are summed milliseconds, not means or p95 values. When starts > 0, startup_ms / starts is the observed mean startup time; never label it a percentile. Zero starts is an empty-data state, not a measured zero-latency result.
• Raw events have seven-day retention and daily aggregates 30-day retention through maintenance. Client telemetry is not used for billing.

​

Go, Python and PHP: attach or replace an English caption track

func saveEnglishCaption(ctx context.Context, video *stackshift.AssetVideoClient, assetID, versionID, captionAssetID, captionVersionID, replaceID string) ([]map[string]any, error) {
	input := map[string]any{
		"caption_asset_id": captionAssetID, "caption_version_id": captionVersionID,
		"language": "en", "label": "English", "kind": "captions", "is_default": true,
	}
	if replaceID != "" {
		input["replace_caption_id"] = replaceID
	}
	if _, err := video.AddCaption(ctx, assetID, versionID, input); err != nil {
		return nil, err
	}
	return video.Captions(ctx, assetID, versionID)
}

def save_english_caption(video, asset_id, version_id, caption_asset_id, caption_version_id, replace_id=""):
    body = {
        "caption_asset_id": caption_asset_id, "caption_version_id": caption_version_id,
        "language": "en", "label": "English", "kind": "captions", "is_default": True,
    }
    if replace_id:
        body["replace_caption_id"] = replace_id
    video.add_caption(asset_id, version_id, body)
    return video.captions(asset_id, version_id)

function saveEnglishCaption(\StackShift\AssetVideoClient $video, string $assetId, string $versionId, string $captionAssetId, string $captionVersionId, string $replaceId = ''): array {
    $body = [
        'caption_asset_id' => $captionAssetId, 'caption_version_id' => $captionVersionId,
        'language' => 'en', 'label' => 'English', 'kind' => 'captions', 'is_default' => true,
    ];
    if ($replaceId !== '') { $body['replace_caption_id'] = $replaceId; }
    $video->addCaption($assetId, $versionId, $body);
    return $video->captions($assetId, $versionId);
}

​

HTTP operations for this workflow

​

Expected result

​

Common failures

​

Related guides