Native video processing and secure playback

​

Goal

​

Prerequisites

• An uploaded video in an Assets space you may access, with its asset ID and current source-version ID.
• An Assets token on a trusted backend: assets:read for workspace/session reads, assets:process for encoding, assets:admin for video review.

​

Workflow

​

Edit footage before packaging

​

Use the video workspace

• Preview shows media details and playback analytics; no events is an empty-data state.
• Renditions lists only outputs available from the published package. A missing height is not a broken quality control when the source is smaller or that rendition failed validation.
• Captions uploads/attaches language tracks to the selected source version. Caption replacement does not re-encode the video.
• Embed previews supported options and generates JavaScript/React integration snippets. For private videos, supply a host-backend session callback rather than storing a private URL permanently.
• Versions compares the active package with pending replacement work. Security distinguishes native validation from optional human content review.

​

Availability and compatibility

​

Read the workspace

• active: the package currently selected for playback; it can belong to the previous source version while replacement work proceeds.
• pending: replacement/current processing package when present. A package includes id, version_id, source_checksum_sha256, recipe_hash, processor_revision, status, phase, progress_percent, job_id and failure_code.
• source: current source version_id, scan_status, review_status and review_reason. Scan values are pending/clean/infected/failed; review values are not_required/pending/approved/rejected.
• renditions: available output records with package_id, kind, profile, dimensions, byte size, MIME type and status. Use these records instead of assuming the full ladder exists.
• admission_enabled: whether this installation admits new native encodes.

const workspace = await stackshift.assets.video.workspace(assetId)
if (!workspace.admission_enabled) {
  throw new Error('New video processing is disabled on this installation')
}
const jobPackage = await stackshift.assets.video.process(assetId, versionId)
// Persist IDs, not a claim that processing succeeded.
const tracking = { packageId: jobPackage.id, jobId: jobPackage.job_id }

​

Package states and presentation

• queued: admitted durable work waiting for a claim; do not invent a percentage for unknown totals.
• processing: inspect phase and progress_percent; scanning, encoding and review are separate concerns. Player presentation also has scanning, encoding and awaiting_review states.
• ready: required validated outputs are available and package promotion succeeded.
• degraded: required playback outputs succeeded but one or more additional renditions failed. Show only available renditions.
• failed: inspect failure_code and job information. Fix the input or failed dependency before requesting another attempt.
• cancelled: the cancelled attempt cannot publish. Use the existing durable-job controls for supported cancellation; there is no separate native-video cancel route in this contract.
• Playback phases such as loading, buffering, paused, ended, expired and revoked are player states, not persisted package status values.

​

Outputs, source identity and replacement

​

Validation is not human content review

await stackshift.assets.video.review(
  assetId, versionId, 'approved',
  'Reviewed the full source video and its intended publication.'
)

​

Playback sessions and URLs

​

Management route and scope reference

• GET /assets/{assetID}/video: assets:read; workspace.
• POST /assets/{assetID}/versions/{versionID}/video: assets:process; 202 package/job admission.
• POST /assets/{assetID}/playback-sessions: assets:read; 201 grant.
• DELETE /assets/{assetID}/playback-sessions/{sessionID}: assets:write; returns revoked=true.
• POST /assets/{assetID}/versions/{versionID}/video/review: assets:admin; decision and reason; returns reviewed=true.
• These management paths are relative to /api/v1. Playback renewal/events/public creation are absolute /playback paths.
• CLI names: video, video-process, playback-create, playback-renew, playback-revoke and video-review under stackshift asset. Playback grants contain credentials: do not stream them into CI logs.

​

Billing and recovery

• 401 during playback: expired/invalid credential; renew while allowed or request a newly authorized session.
• 403: revoked/private/unavailable access. Do not switch to a public URL or MP4 to bypass denial.
• 503 or resource failures: investigate origin, replica and worker readiness; preserve identifiers for diagnostics.
• Replacement failed: show the failed pending package while retaining authorized active playback. Do not delete the active package as a retry strategy.
• Admission disabled: an operator explicitly disabled new processing; the default is enabled. Repeated process requests do not change configuration.

​

Go, Python and PHP: submit a version and wait for its active package

package docsexample

import (
	"context"
	"fmt"
	stackshift "github.com/stackshiftCloud/assets-go"
	"time"
)

func processVideo(ctx context.Context, video *stackshift.AssetVideoClient, assetID, versionID string) (map[string]any, error) {
	queued, err := video.Process(ctx, assetID, versionID)
	if err != nil {
		return nil, err
	}
	for attempt := 0; attempt < 100; attempt++ {
		workspace, err := video.Workspace(ctx, assetID)
		if err != nil {
			return nil, err
		}
		source, _ := workspace["source"].(map[string]any)
		if source["version_id"] != versionID {
			return nil, fmt.Errorf("source changed; refresh the inspector")
		}
		active, _ := workspace["active"].(map[string]any)
		if active["id"] == queued["id"] {
			return active, nil
		}
		pending, _ := workspace["pending"].(map[string]any)
		if pending["id"] == queued["id"] {
			switch pending["status"] {
			case "failed", "cancelled":
				return pending, fmt.Errorf("processing stopped: %v", pending["failure_code"])
			case "ready", "degraded":
				return pending, fmt.Errorf("package prepared; check source review before playback")
			}
		}
		select {
		case <-ctx.Done():
			return queued, ctx.Err()
		case <-time.After(3 * time.Second):
		}
	}
	return queued, fmt.Errorf("polling timed out; retain package ID and resume status reads")
}

import time

def process_video(video, asset_id, version_id):
    queued = video.process(asset_id, version_id)
    for _ in range(100):
        workspace = video.workspace(asset_id)
        if workspace.get("source", {}).get("version_id") != version_id:
            raise RuntimeError("Source changed; refresh the inspector")
        active = workspace.get("active", {})
        if active.get("id") == queued["id"]:
            return active
        pending = workspace.get("pending", {})
        if pending.get("id") == queued["id"]:
            if pending["status"] in ("failed", "cancelled"):
                raise RuntimeError(f"Processing stopped: {pending.get('failure_code', '')}")
            if pending["status"] in ("ready", "degraded"):
                raise RuntimeError("Package prepared; check source review before playback")
        time.sleep(3)
    raise TimeoutError(f"Resume status reads for package {queued['id']}")

function processVideo(\StackShift\AssetVideoClient $video, string $assetId, string $versionId): array {
    $queued = $video->process($assetId, $versionId);
    for ($attempt = 0; $attempt < 100; $attempt++) {
        $workspace = $video->workspace($assetId);
        if (($workspace['source']['version_id'] ?? null) !== $versionId) {
            throw new \RuntimeException('Source changed; refresh the inspector');
        }
        if (($workspace['active']['id'] ?? null) === $queued['id']) {
            return $workspace['active'];
        }
        $pending = $workspace['pending'] ?? [];
        if (($pending['id'] ?? null) === $queued['id']) {
            if (in_array($pending['status'], ['failed', 'cancelled'], true)) {
                throw new \RuntimeException('Processing stopped: ' . ($pending['failure_code'] ?? ''));
            }
            if (in_array($pending['status'], ['ready', 'degraded'], true)) {
                throw new \RuntimeException('Package prepared; check source review before playback');
            }
        }
        sleep(3);
    }
    throw new \RuntimeException('Resume status reads for package ' . $queued['id']);
}

​

HTTP operations for this workflow

​

Expected result

​

Common failures

​

Related guides