@shotstack/shotstack-studio 1.10.0 → 2.0.0-beta.1

package/package.json

@@ -5,7 +5,7 @@
 		"cpuccino",
 		"dazzatron"
 	],
-	"version": "1.10.0",
+	"version": "2.0.0-beta.1",
 	"description": "A video editing library for creating and editing videos with Shotstack",
 	"type": "module",
 	"main": "dist/shotstack-studio.umd.js",
@@ -48,14 +48,15 @@
 		"build": "npm run build:main && npm run build:schema",
 		"build:main": "vite build",
 		"build:schema": "vite build --config vite.config.schema.ts",
-		"test": "npm run build && jest",
+		"test": "jest",
 		"test:watch": "jest --watch",
 		"test:package": "node test-package.js",
 		"typecheck": "tsc --noEmit && tsc --project tsconfig.test.json --noEmit",
 		"lint": "eslint --ignore-path .gitignore .",
 		"lint:fix": "eslint --ignore-path .gitignore --fix .",
 		"format": "prettier --ignore-path .gitignore --write .",
-		"prepublishOnly": "npm run build && npm run test && npm run test:package"
+		"prepublishOnly": "npm run build && npm run test && npm run test:package",
+		"generate:fonts": "npx tsx scripts/fetch-google-fonts.ts"
 	},
 	"devDependencies": {
 		"@jest/globals": "^30.2.0",
@@ -71,6 +72,7 @@
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-plugin-import": "^2.31.0",
 		"jest": "^30.2.0",
+		"jest-environment-jsdom": "^30.2.0",
 		"prettier": "^3.6.2",
 		"ts-jest": "^29.4.5",
 		"typescript": "^5.6.2",
@@ -78,10 +80,12 @@
 		"vite-plugin-dts": "^4.5.4"
 	},
 	"dependencies": {
-		"@shotstack/shotstack-canvas": "^1.5.1",
+		"@huggingface/transformers": "^3.0.0",
+		"@shotstack/shotstack-canvas": "^1.6.5",
 		"fast-deep-equal": "^3.1.3",
 		"howler": "^2.2.4",
 		"mediabunny": "^1.11.2",
+		"opentype": "^0.1.2",
 		"opentype.js": "^1.3.4",
 		"pixi-filters": "^6.0.5",
 		"pixi.js": "^8.5.2",

package/readme.md

@@ -20,7 +20,6 @@ Try Shotstack Studio in your preferred framework:
 
 - Create video compositions with multiple tracks and clips
 - Visual timeline interface
-- WYSIWYG text editing
 - Multi-track, drag-and-drop clip manipulation with snap-to-grid
 - Use in conjunction with the [Shotstack Edit API](https://shotstack.io/docs/guide/getting-started/hello-world-using-curl/) to render video
 - Export to video via the browser
@@ -44,22 +43,22 @@ import { Edit, Canvas, Controls, Timeline } from "@shotstack/shotstack-studio";
 const response = await fetch("https://shotstack-assets.s3.amazonaws.com/templates/hello-world/hello.json");
 const template = await response.json();
 
-// 2. Initialize the edit
-const edit = new Edit(template.output.size, template.timeline.background);
+// 2. Create Edit from template and load it
+const edit = new Edit(template);
 await edit.load();
 
 // 3. Create a canvas to display the edit
-const canvas = new Canvas(template.output.size, edit);
+const canvas = new Canvas(edit);
 await canvas.load(); // Renders to [data-shotstack-studio] element
 
-// 4. Load the template
-await edit.loadEdit(template);
-
-// 5. Initialize the Timeline
-const timeline = new Timeline(edit, { width: 1280, height: 300 });
-await timeline.load(); // Renders to [data-shotstack-timeline] element
+// 4. Initialize the Timeline
+const container = document.querySelector("[data-shotstack-timeline]");
+const timeline = new Timeline(edit, container, {
+  features: { toolbar: true, ruler: true, playhead: true, snap: true }
+});
+await timeline.load();
 
-// 6. Add keyboard controls
+// 5. Add keyboard controls
 const controls = new Controls(edit);
 await controls.load();
 ```
@@ -80,14 +79,12 @@ The Edit class represents a video project with its timeline, clips, and properti
 ```typescript
 import { Edit } from "@shotstack/shotstack-studio";
 
-// For schema validation only (e.g., in tests):
-import { EditSchema, ClipSchema } from "@shotstack/shotstack-studio/schema";
-// Create an edit with dimensions and background
-const edit = new Edit({ width: 1280, height: 720 }, "#000000");
+// Create an edit from a template
+const edit = new Edit(templateJson);
 await edit.load();
 
-// Load from template
-await edit.loadEdit(templateJson);
+// Or reload a different template later
+await edit.loadEdit(newTemplate);
 
 // Playback controls
 edit.play();
@@ -112,6 +109,8 @@ edit.deleteTrack(1);
 // Undo/Redo
 edit.undo();
 edit.redo();
+edit.canUndo(); // Check if undo is available (useful for UI)
+edit.canRedo(); // Check if redo is available
 
 // Get edit information
 const clip = edit.getClip(0, 0);
@@ -122,27 +121,48 @@ const duration = edit.totalDuration; // in milliseconds
 
 #### Events
 
-The Edit class provides an event system to listen for specific actions:
+The Edit class provides a typed event system to listen for specific actions:
 
 ```typescript
+import { Edit, EditEvent } from "@shotstack/shotstack-studio";
+
 // Listen for clip selection events
-edit.events.on("clip:selected", data => {
+edit.events.on(EditEvent.ClipSelected, 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 }
+edit.events.on(EditEvent.ClipUpdated, data => {
+  console.log("Previous state:", data.previous);
+  console.log("Current state:", data.current);
 });
+
+// Listen for playback events
+edit.events.on(EditEvent.PlaybackPlay, () => console.log("Playing"));
+edit.events.on(EditEvent.PlaybackPause, () => console.log("Paused"));
 ```
 
 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.
+**Playback:** `PlaybackPlay`, `PlaybackPause`
+
+**Clips:** `ClipAdded`, `ClipDeleted`, `ClipSelected`, `ClipUpdated`, `ClipCopied`, `ClipSplit`, `ClipRestored`
+
+**Selection:** `SelectionCleared`
+
+**Edit State:** `EditChanged`, `EditUndo`, `EditRedo`
+
+**Tracks:** `TrackAdded`, `TrackRemoved`
+
+**Duration:** `DurationChanged`
+
+**Output:** `OutputResized`, `OutputFpsChanged`, `OutputFormatChanged`
+
+**Merge Fields:** `MergeFieldRegistered`, `MergeFieldUpdated`, `MergeFieldRemoved`, `MergeFieldChanged`
+
+**Transcription:** `TranscriptionProgress`, `TranscriptionCompleted`, `TranscriptionFailed`
 
 ### Canvas
 
@@ -150,7 +170,7 @@ The Canvas class provides the visual rendering of the edit.
 
 ```typescript
 // Create and load the canvas
-const canvas = new Canvas(edit.size, edit);
+const canvas = new Canvas(edit);
 await canvas.load();
 
 // Zoom and positioning
@@ -190,16 +210,17 @@ The Timeline class provides a visual timeline interface for editing.
 ```typescript
 import { Timeline } from "@shotstack/shotstack-studio";
 
-const timeline = new Timeline(edit, { width: 1280, height: 300 });
+const container = document.querySelector("[data-shotstack-timeline]");
+const timeline = new Timeline(edit, container, {
+  features: {
+    toolbar: true, // Playback controls and editing buttons
+    ruler: true, // Time ruler with markers
+    playhead: true, // Draggable playhead
+    snap: true, // Snap clips to grid and other clips
+    badges: true // Asset type badges on clips
+  }
+});
 await timeline.load();
-
-// Timeline features:
-// - Visual track and clip representation
-// - Drag-and-drop clip manipulation
-// - Clip resizing with edge detection
-// - Playhead control for navigation
-// - Snap-to-grid functionality
-// - Zoom and scroll controls
 ```
 
 ### VideoExporter
@@ -211,286 +232,66 @@ const exporter = new VideoExporter(edit, canvas);
 await exporter.export("my-video.mp4", 25); // filename, fps
 ```
 
-## Theming
-
-Shotstack Studio supports theming for visual components. Currently, theming is available for the Timeline component, with Canvas theming coming in a future releases.
+## Merge Fields
 
-### Built-in Themes
-
-The library includes pre-designed themes that you can use immediately:
+Merge fields allow dynamic content substitution using `{{ FIELD_NAME }}` syntax in your templates.
 
 ```typescript
-import { Timeline } from "@shotstack/shotstack-studio";
-import darkTheme from "@shotstack/shotstack-studio/themes/dark.json";
-import minimalTheme from "@shotstack/shotstack-studio/themes/minimal.json";
+import { Edit, EditEvent } from "@shotstack/shotstack-studio";
 
-// Apply a theme when creating the timeline
-const timeline = new Timeline(edit, { width: 1280, height: 300 }, { theme: darkTheme });
-```
+// Set a merge field value
+edit.setMergeField("TITLE", "My Video Title");
+edit.setMergeField("SUBTITLE", "A great subtitle");
 
-### Custom Themes
+// Get all registered merge fields
+const fields = edit.getMergeFields();
 
-Create your own theme by defining colors and dimensions for each component:
-
-```typescript
-const customTheme = {
-  timeline: {
-    // Main timeline colors
-    background: "#1e1e1e",
-    divider: "#1a1a1a",
-    playhead: "#ff4444",
-    snapGuide: "#888888",
-    dropZone: "#00ff00",
-    trackInsertion: "#00ff00",
-
-    // Toolbar styling
-    toolbar: {
-      background: "#1a1a1a",
-      surface: "#2a2a2a", // Button backgrounds
-      hover: "#3a3a3a", // Button hover state
-      active: "#007acc", // Button active state
-      divider: "#3a3a3a", // Separator lines
-      icon: "#888888", // Icon colors
-      text: "#ffffff", // Text color
-      height: 36 // Toolbar height in pixels
-    },
-
-    // Ruler styling
-    ruler: {
-      background: "#404040",
-      text: "#ffffff", // Time labels
-      markers: "#666666", // Time marker dots
-      height: 40 // Ruler height in pixels
-    },
-
-    // Track styling
-    tracks: {
-      surface: "#2d2d2d", // Primary track color
-      surfaceAlt: "#252525", // Alternating track color
-      border: "#3a3a3a", // Track borders
-      height: 60 // Track height in pixels
-    },
-
-    // Clip colors by asset type
-    clips: {
-      video: "#4a9eff",
-      audio: "#00d4aa",
-      image: "#f5a623",
-      text: "#d0021b",
-      shape: "#9013fe",
-      html: "#50e3c2",
-      luma: "#b8e986",
-      default: "#8e8e93", // Unknown asset types
-      selected: "#007acc", // Selection border
-      radius: 4 // Corner radius in pixels
-    }
-  }
-  // Canvas theming will be available in future releases
-  // canvas: { ... }
-};
-
-const timeline = new Timeline(edit, { width: 1280, height: 300 }, { theme: customTheme });
+// Listen for merge field changes
+edit.events.on(EditEvent.MergeFieldUpdated, ({ field }) => {
+  console.log(`Field ${field.name} updated to:`, field.value);
+});
 ```
 
-### Theme Structure
-
-Themes are organized by component, making it intuitive to customize specific parts of the interface:
+In templates, use placeholders that will be replaced with merge field values:
 
-- **Timeline**: Controls the appearance of the timeline interface
-  - `toolbar`: Playback controls and buttons
-  - `ruler`: Time markers and labels
-  - `tracks`: Track backgrounds and borders
-  - `clips`: Asset-specific colors and selection states
-  - Global timeline properties (background, playhead, etc.)
-
-- **Canvas** (coming soon): Will control the appearance of the video preview area
-
-## Template Format
-
-Templates use a JSON format with the following structure:
-
-```typescript
+```json
 {
-  timeline: {
-    background: "#000000",
-    fonts: [
-      { src: "https://example.com/font.ttf" }
-    ],
-    tracks: [
-      {
-        clips: [
-          {
-            asset: {
-              type: "image", // image, video, text, shape, audio
-              src: "https://example.com/image.jpg",
-              // Other asset properties depend on type
-            },
-            start: 0,        // Start time in seconds
-            length: 5,       // Duration in seconds
-            transition: {    // Optional transitions
-              in: "fade",
-              out: "fade"
-            },
-            position: "center", // Positioning
-            scale: 1,           // Scale factor
-			offset: {
-				x: 0.1,         // X-axis offset relative to position
-				y: 0            // Y-axis offset relative to position
-			}
-          }
-        ]
-      }
-    ]
-  },
-  output: {
-    format: "mp4",
-    size: {
-      width: 1280,
-      height: 720
-    }
+  "asset": {
+    "type": "text",
+    "text": "{{ TITLE }}"
   }
 }
 ```
 
-## License
-
-PolyForm Shield License 1.0.0
-
-## API Reference
-
-### Edit
+## Custom Toolbar Buttons
 
-The `Edit` class represents a video editing project with its timeline, clips, and properties.
+Register custom toolbar buttons to extend the canvas toolbar with your own actions:
 
 ```typescript
-import { Edit } from "@shotstack/shotstack-studio";
-import { EditSchema } from "@shotstack/shotstack-studio";
-```
-
-#### Constructor
-
-```typescript
-constructor(size: Size, backgroundColor: string = "#ffffff")
-```
-
-Creates a new Edit instance with the specified dimensions and background color.
-
-#### Properties
-
-- `assetLoader` - Asset loader instance for managing media assets
-- `events` - Event emitter for handling events
-- `playbackTime` - Current playback position in milliseconds
-- `totalDuration` - Total duration of the edit in milliseconds
-
-#### Methods
-
-- `async load()` - Initialize and prepare the edit for rendering
-- `async loadEdit(edit: EditType)` - Load an edit from a JSON template
-- `play()` - Start playback
-- `pause()` - Pause playback
-- `seek(target: number)` - Seek to a specific time in milliseconds
-- `stop()` - Stop playback and return to beginning
-- `addClip(trackIdx: number, clip: ClipType)` - Add a clip to a specific track
-- `deleteClip(trackIdx: number, clipIdx: number)` - Delete a clip
-- `getClip(trackIdx: number, clipIdx: number)` - Get a clip by track and index
-- `addTrack(trackIdx: number, track: TrackType)` - Add a new track
-- `getTrack(trackIdx: number)` - Get a track by index
-- `deleteTrack(trackIdx: number)` - Delete a track
-- `getEdit()` - Get the full edit configuration as a JSON object
-- `undo()` - Undo the last editing operation
-- `redo()` - Redo the last undone operation
-
-#### Events
-
-- `clip:selected` - Triggered when a clip is selected
-- `clip:updated` - Triggered when a clip is modified
-- `edit:undo` - Triggered when an undo operation is performed
-- `edit:redo` - Triggered when a redo operation is performed
-
-### Canvas
-
-The `Canvas` class provides the visual rendering of the edit.
-
-```typescript
-import { Canvas } from "@shotstack/shotstack-studio";
-import type { Size } from "@shotstack/shotstack-studio";
-```
-
-#### Constructor
-
-```typescript
-constructor(size: Size, edit: Edit)
-```
-
-Creates a new canvas with specified dimensions for rendering the edit.
-
-#### Methods
-
-- `async load()` - Initialize the canvas and add it to the DOM
-- `centerEdit()` - Center the edit in the canvas
-- `zoomToFit()` - Zoom to fit the entire edit
-- `setZoom(zoom: number)` - Set zoom level
-- `dispose()` - Clean up resources and remove the canvas from the DOM
-
-### Controls
-
-The `Controls` class adds keyboard controls for playback.
-
-```typescript
-import { Controls } from "@shotstack/shotstack-studio";
-```
-
-#### Constructor
-
-```typescript
-constructor(edit: Edit)
-```
-
-Creates a new controls instance for the provided Edit.
-
-#### Methods
-
-- `async load()` - Set up event listeners for keyboard controls
-
-### Timeline
-
-The `Timeline` class provides a visual timeline interface for video editing.
-
-```typescript
-import { Timeline } from "@shotstack/shotstack-studio";
-```
-
-#### Constructor
-
-```typescript
-constructor(edit: Edit, size: { width: number, height: number }, themeOptions?: TimelineThemeOptions)
-```
-
-Creates a new timeline interface for the provided Edit.
-
-#### Methods
-
-- `async load()` - Initialize the timeline and add it to the DOM
-- `setTheme(themeOptions: TimelineThemeOptions)` - Change the timeline theme
-- `setOptions(options: Partial<TimelineOptions>)` - Update timeline options
-- `dispose()` - Clean up resources and remove from DOM
-
-### VideoExporter
-
-The `VideoExporter` class handles exporting the edit to MP4.
+// Register a custom button
+edit.registerToolbarButton({
+  id: "add-text",
+  icon: `<svg viewBox="0 0 16 16">...</svg>`,
+  tooltip: "Add Text",
+  event: "text:requested",
+  dividerBefore: true // Optional: add a divider before this button
+});
 
-```typescript
-import { VideoExporter } from "@shotstack/shotstack-studio";
+// Handle the custom event
+edit.events.on("text:requested", ({ position }) => {
+  // position is the current playhead position in milliseconds
+  edit.addClip(0, {
+    asset: { type: "text", text: "New Text" },
+    start: position / 1000,
+    length: 5
+  });
+});
 ```
 
-#### Constructor
-
-```typescript
-constructor(edit: Edit, canvas: Canvas)
-```
+## API Reference
 
-Creates a new exporter for the provided Edit and Canvas.
+For complete schema and type definitions, see the [Shotstack API Reference](https://shotstack.io/docs/api/#tocs_edit).
 
-#### Methods
+## License
 
-- `async export(filename: string = "shotstack-export.mp4", fps: number = 25)` - Export the edit to an MP4 video file
+PolyForm Shield License 1.0.0