Studio SDK

The Studio SDK is a library for creating and editing videos in the browser. It provides a fully interactive editing environment which work with the Shotstack data model.

Interactive Examples

Try the Shotstack Studio in your preferred framework:

Installation

npm install @shotstack/shotstack-studio

yarn add @shotstack/shotstack-studio

Quick Start

import { Edit, Canvas, Controls, Timeline } from "@shotstack/shotstack-studio";

// 1. Retrieve an edit from a template
const templateUrl =
  "https://shotstack-assets.s3.amazonaws.com/templates/hello-world/hello.json";
const response = await fetch(templateUrl);
const template = await response.json();

// 2. Initialize the edit with dimensions and background color
const edit = new Edit(template.output.size, template.timeline.background);
await edit.load();

// 3. Create a canvas to display the edit
const canvas = new Canvas(template.output.size, edit);
await canvas.load(); // Renders to [data-shotstack-studio] element

// 4. Load the template
await edit.loadEdit(template);

// 5. Add keyboard controls
const controls = new Controls(edit);
await controls.load();

// 6. Add timeline for visual editing
const timeline = new Timeline(edit, {
  width: template.output.size.width,
  height: 300
});
await timeline.load(); // Renders to [data-shotstack-timeline] element

Main Components

Edit

The Edit class represents a video project with its timeline, clips, and properties.

// Create an edit with dimensions and background
const edit = new Edit({ width: 1280, height: 720 }, "#000000");
await edit.load();

// Load from template
await edit.loadEdit(templateJson);

// Playback controls
edit.play();
edit.pause();
edit.seek(2000); // Seek to 2 seconds (in milliseconds)
edit.stop(); // Stop and return to beginning

// Editing functions
edit.addClip(0, {
  asset: {
    type: "image",
    src: "https://example.com/image.jpg",
  },
  start: 0,
  length: 5,
});

edit.addTrack(1, { clips: [] });
edit.deleteClip(0, 0);
edit.deleteTrack(1);

// Get edit information
const clip = edit.getClip(0, 0);
const track = edit.getTrack(0);
const editJson = edit.getEdit();
const duration = edit.totalDuration; // in milliseconds

Events

The Edit class provides an event system to listen for specific actions:

// Listen for clip selection events
edit.events.on("clip:selected", (data) => {
  console.log("Clip selected:", data.clip);
  console.log("Track index:", data.trackIndex);
  console.log("Clip index:", data.clipIndex);
});

// Listen for clip update events
edit.events.on("clip:updated", (data) => {
  console.log("Previous state:", data.previous); // { clip, trackIndex, clipIndex }
  console.log("Current state:", data.current); // { clip, trackIndex, clipIndex }
});

Available events:

• clip:selected - Emitted when a clip is initially selected, providing data about the clip, its track index, and clip index.
• clip:updated - Emitted when a clip's properties are modified, providing both previous and current states.

Canvas

The Canvas class provides the visual rendering of the edit.

// Create and load the canvas
const canvas = new Canvas(edit.size, edit);
await canvas.load();

// Zoom and positioning
canvas.centerEdit();
canvas.zoomToFit();
canvas.setZoom(1.5); // 1.0 is 100%, 0.5 is 50%, etc.
canvas.dispose(); // Clean up resources when done

Controls

The Controls class adds keyboard controls for playback.

const controls = new Controls(edit);
await controls.load();

// Available keyboard controls:
// Space - Play/Pause
// J - Stop
// K - Pause
// L - Play
// Left Arrow - Seek backward
// Right Arrow - Seek forward
// Shift + Arrow - Seek larger amount
// Comma - Step backward one frame
// Period - Step forward one frame

Timeline

The Timeline component provides a visual interface for editing with drag-and-drop functionality, multi-track support, and real-time preview updates.

import { Timeline } from "@shotstack/shotstack-studio";

// Create and load the timeline with default settings
const timeline = new Timeline(edit);
await timeline.load();

// Or create with custom dimensions and theme
const timeline = new Timeline(
  edit,
  { width: 1280, height: 300 }, // dimensions
  { theme: customTheme }         // optional theme configuration
);
await timeline.load(); // Renders to [data-shotstack-timeline] element

// Timeline features:
// - Drag and drop clips between tracks
// - Visual playhead with ruler
// - Collision detection
// - Theme customization
// - Real-time preview updates

Features

Undo/Redo Support

The SDK implements a command pattern architecture that provides complete undo/redo functionality for all editing operations:

// Undo the last operation
edit.undo();

// Redo the last undone operation
edit.redo();