SDK

Install the SDK

Build, validate, and preview AppVideoStudio video compositions from your own code. The SDK ships document helpers, the <avs-player> web component, and a Playwright test harness as ES modules with full TypeScript declarations.

npm install @appvideostudio/sdk
npm GitHub Playground
Package @appvideostudio/sdk
Version 0.1.0
License MIT

Entry Points

The SDK exposes four import paths, each targeting a different environment:

Import Environment Description
@appvideostudio/sdk Node + Browser Document helpers, validation, constants
@appvideostudio/sdk/document Node + Browser Document module directly
@appvideostudio/sdk/player Browser only <avs-player> web component
@appvideostudio/sdk/test-harness Node (Playwright) Automated preview and screenshots 
import {
  createEmptyVideoDocument,
  validateVideoDocument,
} from '@appvideostudio/sdk';

// 1. Create a document
const doc = createEmptyVideoDocument({
  name: 'My Video',
  width: 1080,
  height: 1920,
  timelineDuration: 10,
});

// 2. Add assets
doc.assets.push({
  id: 'bg-asset',
  type: 'image',
  name: 'Background',
  url: 'https://example.com/bg.jpg',
  posterUrl: null,
  duration: null,
  width: 1080,
  height: 1920,
  mimeType: 'image/jpeg',
});

// 3. Add timeline components
doc.timeline.push({
  id: 'comp-1',
  componentType: 'image-fill',
  layerId: 'layer-1',
  startTime: 0,
  duration: 10,
  params: {},
  assetBindings: { source: 'bg-asset' },
  customLabel: 'Background',
  color: '#2563eb',
});

// 4. Validate
const errors = validateVideoDocument(doc);
console.log(errors); // [] if valid
 
import { createEmptyVideoDocument } from '@appvideostudio/sdk';
import { defineAVSPlayerElement } from '@appvideostudio/sdk/player';

// Register the custom element
defineAVSPlayerElement();

// Create and append the player
const player = document.createElement('avs-player');
document.body.appendChild(player);

// Load a document
const doc = createEmptyVideoDocument({ width: 1920, height: 1080 });
// ... add layers, assets, components ...

await player.ready;
await player.load(doc);
await player.preloadAssets();
await player.play();

The <avs-player> element creates an iframe to the AppVideoStudio player runtime at https://create.appvideostudio.com. The hosted runtime must be reachable for playback.

 
import { test, expect } from '@playwright/test';
import { createPlayerHarness } from '@appvideostudio/sdk/test-harness';
import { createEmptyVideoDocument } from '@appvideostudio/sdk';

test('visual regression at key frames', async ({ page }) => {
  const doc = createEmptyVideoDocument({ name: 'Regression Test' });
  // ... add components to doc ...

  const harness = await createPlayerHarness(page, { document: doc });

  // Take screenshots at specific times
  const frames = await harness.screenshotSequence([0, 2, 5, 10]);
  for (const { time, buffer } of frames) {
    expect(buffer).toMatchSnapshot(`frame-${time}s.png`);
  }

  await harness.destroy();
});

Requires @playwright/test as a peer dependency (>=1.40.0). Install with npm install --save-dev @playwright/test.

A VideoDocument contains project settings, layers, assets, and a timeline of components:

Field Type Description
schemaVersion number Always 1
metadata { id, name } Document identity
projectDimensions { width, height } Canvas size in pixels
timelineDuration number Total duration in seconds (default 24)
layers Layer[] Rendering order; each has id, name, color
assets Asset[] Media files with id, type, url, dimensions
timeline Component[] Each has componentType, layerId, startTime, duration, params, assetBindings

Example document

{
  "schemaVersion": 1,
  "metadata": { "id": null, "name": "My Video" },
  "projectDimensions": { "width": 1080, "height": 1920 },
  "timelineDuration": 24,
  "layers": [
    { "id": "layer-1", "name": "Layer 1", "color": "#2563eb" }
  ],
  "assets": [
    {
      "id": "asset-1", "type": "image", "name": "Background",
      "url": "https://example.com/bg.png",
      "posterUrl": null, "duration": null,
      "width": 1080, "height": 1920, "mimeType": "image/png"
    }
  ],
  "timeline": [
    {
      "id": "comp-1", "componentType": "text-basic",
      "layerId": "layer-1", "startTime": 0, "duration": 5,
      "params": { "text": "Hello world" },
      "assetBindings": {}, "customLabel": null, "color": "#6366f1"
    }
  ]
}

Document Functions

FunctionDescription
createEmptyVideoDocument(options?) Create a new document with default layers. Options: id, name, width, height, timelineDuration, layers
validateVideoDocument(doc, options?) Returns ValidationError[]. Options: { knownTemplateIds?: Set }
normalizeVideoDocument(input?) Normalize a partial or malformed document into a valid VideoDocument
exportVideoDocumentFromState(state?) Export a video document from internal editor state
getDocumentDuration(doc) Returns the effective duration (max of timelineDuration and last component end)
getDocumentTimelineEnd(doc) Returns the end time of the last timeline component
getTimelineWindow(components?, range?) Filter and sort components overlapping a time range
sortTimeline(components?) Sort by startTime, then by id
createDefaultLayers(count?) Create an array of default layer definitions (default: 3)

Constants

ConstantValue
DEFAULT_PROJECT_DIMENSIONS { width: 1080, height: 1920 }
DEFAULT_TIMELINE_DURATION 24
PLAYER_SCHEMA_VERSION 1

Player Element

Method / PropertyDescription
defineAVSPlayerElement() Register the <avs-player> custom element (safe to call multiple times)
player.ready Promise that resolves when the player iframe is ready
load(doc) / loadFromUrl(url) Load a document object or fetch from URL
play() / pause() / stop() / seek(time) Playback control
preloadAssets() Preload all media assets
getStatus() / getErrors() Query player state
addComponent(def) / removeComponent(id) Mutate the timeline
updateComponentParams(id, patch) Patch component parameters
replaceDocument(doc) / exportDocument() Replace or export the full document
listTemplates() / getTemplate(id) Query available templates from the runtime

Supports autoplay, loop, and no-controls HTML attributes. See the API Overview for the full attribute reference.

Test Harness

MethodDescription
createPlayerHarness(page, options) Create a Playwright harness. Options: document (required), playerUrl, validate, width, height, readyTimeout
harness.play() / pause() / seek(t) Playback control in the harness
harness.screenshotAt(time) Take a screenshot at a specific time
harness.screenshotSequence(times) Take screenshots at multiple times
harness.getStatus() / getErrors() Query player state in the harness
harness.destroy() Clean up the harness