@shotstack/shotstack-studio 1.4.0 → 1.5.0

package/package.json

@@ -5,7 +5,7 @@
 		"cpuccino",
 		"dazzatron"
 	],
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"description": "A video editing library for creating and editing videos with Shotstack",
 	"type": "module",
 	"main": "dist/shotstack-studio.umd.js",
@@ -28,7 +28,7 @@
 		"url": "https://github.com/shotstack/shotstack-studio-sdk"
 	},
 	"scripts": {
-		"build": "vite build && tsc --emitDeclarationOnly",
+		"build": "vite build",
 		"prepublishOnly": "npm run build"
 	},
 	"peerDependencies": {
@@ -46,9 +46,11 @@
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-plugin-import": "^2.31.0",
 		"typescript": "^5.6.2",
-		"vite": "^5.4.10"
+		"vite": "^5.4.10",
+		"vite-plugin-dts": "^4.5.4"
 	},
 	"dependencies": {
+		"fast-deep-equal": "^3.1.3",
 		"howler": "^2.2.4",
 		"opentype.js": "^1.3.4",
 		"pixi-filters": "^6.0.5",

package/readme.md

@@ -19,7 +19,9 @@ Try Shotstack Studio in your preferred framework:
 ## Features
 
 - 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 using browser-based FFmpeg
 
@@ -46,14 +48,13 @@ You can skip this if you're using the [Shotstack Edit API](https://shotstack.io/
 ## Quick Start
 
 ```typescript
-import { Edit, Canvas, Controls } from "@shotstack/shotstack-studio";
+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);
+// 1. Load a template
+const response = await fetch("https://shotstack-assets.s3.amazonaws.com/templates/hello-world/hello.json");
 const template = await response.json();
 
-// 2. Initialize the edit with dimensions and background color
+// 2. Initialize the edit
 const edit = new Edit(template.output.size, template.timeline.background);
 await edit.load();
 
@@ -64,15 +65,20 @@ await canvas.load(); // Renders to [data-shotstack-studio] element
 // 4. Load the template
 await edit.loadEdit(template);
 
-// 5. Add keyboard controls
+// 5. Initialize the Timeline
+const timeline = new Timeline(edit, { width: 1280, height: 300 });
+await timeline.load(); // Renders to [data-shotstack-timeline] element
+
+// 6. Add keyboard controls
 const controls = new Controls(edit);
 await controls.load();
 ```
 
-Your HTML should include a container with the `data-shotstack-studio` attribute:
+Your HTML should include containers for both the canvas and timeline:
 
 ```html
 <div data-shotstack-studio></div>
+<div data-shotstack-timeline></div>
 ```
 
 ## Main Components
@@ -182,6 +188,25 @@ await controls.load();
 // Cmd/Ctrl + Shift + Z - Redo
 ```
 
+### Timeline
+
+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 });
+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
 
 The VideoExporter class exports the edit to a video file.
@@ -191,6 +216,101 @@ 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.
+
+### Built-in Themes
+
+The library includes pre-designed themes that you can use immediately:
+
+```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";
+
+// Apply a theme when creating the timeline
+const timeline = new Timeline(edit, { width: 1280, height: 300 }, { theme: darkTheme });
+```
+
+### Custom Themes
+
+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 });
+```
+
+### Theme Structure
+
+Themes are organized by component, making it intuitive to customize specific parts of the interface:
+
+- **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:
@@ -338,6 +458,29 @@ Creates a new controls instance for the provided Edit.
 
 - `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.

package/dist/src/components/canvas/index.d.ts

@@ -1,14 +0,0 @@
-export { Entity } from "@core/shared/entity";
-export { Player } from "./players/player";
-export { AudioPlayer } from "./players/audio-player";
-export { HtmlPlayer } from "./players/html-player";
-export { ImagePlayer } from "./players/image-player";
-export { LumaPlayer } from "./players/luma-player";
-export { ShapePlayer } from "./players/shape-player";
-export { TextPlayer } from "./players/text-player";
-export { VideoPlayer } from "./players/video-player";
-export { TextCursor } from "./text/text-cursor";
-export { TextEditor } from "./text/text-editor";
-export { TextInputHandler } from "./text/text-input-handler";
-export { Edit } from "@core/edit";
-export { Inspector } from "./system/inspector";

package/dist/src/components/canvas/players/audio-player.d.ts

@@ -1,17 +0,0 @@
-import type { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import { Player } from "./player";
-export declare class AudioPlayer extends Player {
-    private audioResource;
-    private isPlaying;
-    private volumeKeyframeBuilder;
-    private syncTimer;
-    constructor(edit: Edit, clipConfiguration: Clip);
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    getVolume(): number;
-}

package/dist/src/components/canvas/players/html-player.d.ts

@@ -1,17 +0,0 @@
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import type { Edit } from "core/edit";
-import { Player } from "./player";
-export declare class HtmlPlayer extends Player {
-    private background;
-    private text;
-    constructor(timeline: Edit, clipConfiguration: Clip);
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    protected getFitScale(): number;
-    private parseDocument;
-    private parseAlignment;
-}

package/dist/src/components/canvas/players/image-player.d.ts

@@ -1,15 +0,0 @@
-import type { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import { Player } from "./player";
-export declare class ImagePlayer extends Player {
-    private texture;
-    private sprite;
-    constructor(timeline: Edit, clipConfiguration: Clip);
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    private createCroppedTexture;
-}

package/dist/src/components/canvas/players/luma-player.d.ts

@@ -1,18 +0,0 @@
-import type { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import * as pixi from "pixi.js";
-import { Player } from "./player";
-export declare class LumaPlayer extends Player {
-    private texture;
-    private sprite;
-    private isPlaying;
-    constructor(edit: Edit, clipConfiguration: Clip);
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    getVolume(): number;
-    getMask(): pixi.Sprite | null;
-}

package/dist/src/components/canvas/players/player.d.ts

@@ -1,76 +0,0 @@
-import { type Edit } from "@core/edit";
-import { type Size, type Vector } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import { Entity } from "../../../core/shared/entity";
-/**
- * TODO: Move handles on UI level (screen space)
- * TODO: Handle overlapping frames - ex: length of a clip is 1.5s but there's an in (1s) and out (1s) transition
- * TODO: Scale X and Y needs to be implemented separately for getFitScale cover
- * TODO: Move animation effects and transitions out of player
- * TODO: On pointer down and custom keyframe, add a keyframe at the current time. Get current and time and push a keyframe into the state, and then reconfigure the keyframes.
- * TODO: Move bounding box to a separate entity
- */
-export declare abstract class Player extends Entity {
-    private static readonly SnapThreshold;
-    private static readonly DiscardedFrameCount;
-    private static readonly ScaleHandleRadius;
-    private static readonly RotationHandleRadius;
-    private static readonly RotationHandleOffset;
-    private static readonly OutlineWidth;
-    private static readonly MinScale;
-    private static readonly MaxScale;
-    layer: number;
-    shouldDispose: boolean;
-    protected edit: Edit;
-    clipConfiguration: Clip;
-    private positionBuilder;
-    private offsetXKeyframeBuilder?;
-    private offsetYKeyframeBuilder?;
-    private scaleKeyframeBuilder?;
-    private opacityKeyframeBuilder?;
-    private rotationKeyframeBuilder?;
-    private outline;
-    private topLeftScaleHandle;
-    private topRightScaleHandle;
-    private bottomLeftScaleHandle;
-    private bottomRightScaleHandle;
-    private rotationHandle;
-    private isHovering;
-    private isDragging;
-    private dragOffset;
-    private scaleDirection;
-    private scaleStart;
-    private scaleOffset;
-    private isRotating;
-    private rotationStart;
-    private rotationOffset;
-    private initialClipConfiguration;
-    constructor(edit: Edit, clipConfiguration: Clip);
-    reconfigureAfterRestore(): void;
-    protected configureKeyframes(): void;
-    load(): Promise<void>;
-    update(_: number, __: number): void;
-    draw(): void;
-    dispose(): void;
-    getStart(): number;
-    getLength(): number;
-    getEnd(): number;
-    getPlaybackTime(): number;
-    abstract getSize(): Size;
-    getOpacity(): number;
-    getPosition(): Vector;
-    getPivot(): Vector;
-    protected getFitScale(): number;
-    getScale(): number;
-    getRotation(): number;
-    isActive(): boolean;
-    shouldDiscardFrame(): boolean;
-    private onPointerStart;
-    private onPointerMove;
-    private onPointerUp;
-    private onPointerOver;
-    private onPointerOut;
-    private clipHasPresets;
-    private clipHasKeyframes;
-    private hasStateChanged;
-}

package/dist/src/components/canvas/players/shape-player.d.ts

@@ -1,15 +0,0 @@
-import type { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import { Player } from "./player";
-export declare class ShapePlayer extends Player {
-    private shape;
-    private shapeBackground;
-    constructor(timeline: Edit, clipConfiguration: Clip);
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    protected getFitScale(): number;
-}

package/dist/src/components/canvas/players/text-player.d.ts

@@ -1,19 +0,0 @@
-import { Player } from "@canvas/players/player";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-/**
- * TextPlayer renders and manages editable text elements in the canvas
- */
-export declare class TextPlayer extends Player {
-    private background;
-    private text;
-    private textEditor;
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    dispose(): void;
-    getSize(): Size;
-    protected getFitScale(): number;
-    private createTextStyle;
-    private positionText;
-    updateTextContent(newText: string, initialConfig: Clip): void;
-}

package/dist/src/components/canvas/players/video-player.d.ts

@@ -1,22 +0,0 @@
-import type { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-import { type Clip } from "@schemas/clip";
-import { Player } from "./player";
-export declare class VideoPlayer extends Player {
-    private texture;
-    private sprite;
-    private isPlaying;
-    private volumeKeyframeBuilder;
-    private syncTimer;
-    constructor(edit: Edit, clipConfiguration: Clip);
-    /**
-     * TODO: Add support for .mov and .webm files
-     */
-    load(): Promise<void>;
-    update(deltaTime: number, elapsed: number): void;
-    draw(): void;
-    dispose(): void;
-    getSize(): Size;
-    getVolume(): number;
-    private createCroppedTexture;
-}

package/dist/src/components/canvas/shotstack-canvas.d.ts

@@ -1,25 +0,0 @@
-import { Edit } from "@core/edit";
-import { type Size } from "@layouts/geometry";
-export declare class Canvas {
-    private static extensionsRegistered;
-    private readonly size;
-    private readonly edit;
-    private readonly inspector;
-    private container?;
-    private background?;
-    private minZoom;
-    private maxZoom;
-    private currentZoom;
-    constructor(size: Size, edit: Edit);
-    load(): Promise<void>;
-    private setupTouchHandling;
-    centerEdit(): void;
-    zoomToFit(): void;
-    setZoom(zoom: number): void;
-    private registerExtensions;
-    private configureApplication;
-    private onTick;
-    private configureStage;
-    private onClick;
-    dispose(): void;
-}

package/dist/src/components/canvas/system/inspector.d.ts

@@ -1,18 +0,0 @@
-import { Entity } from "@core/shared/entity";
-export declare class Inspector extends Entity {
-    private static readonly Width;
-    private static readonly Height;
-    fps: number;
-    playbackTime: number;
-    playbackDuration: number;
-    isPlaying: boolean;
-    private background;
-    private text;
-    constructor();
-    load(): Promise<void>;
-    update(_: number, __: number): void;
-    draw(): void;
-    dispose(): void;
-    private getMemoryInfo;
-    private bytesToMegabytes;
-}

package/dist/src/components/canvas/text/text-cursor.d.ts

@@ -1,47 +0,0 @@
-import { type Clip } from "@schemas/clip";
-import * as pixi from "pixi.js";
-type TextCursorOptions = {
-    width?: number;
-    color?: number;
-    blinkInterval?: number;
-};
-export declare class TextCursor {
-    private static readonly DEFAULT_BLINK_INTERVAL_MS;
-    private static readonly DEFAULT_CURSOR_WIDTH_PX;
-    private static readonly DEFAULT_CURSOR_COLOR;
-    private cursor;
-    private parent;
-    private textElement;
-    private clipConfig;
-    private textPosition;
-    private pixelX;
-    private pixelY;
-    private currentLine;
-    private isBlinking;
-    private blinkInterval;
-    private blinkIntervalMs;
-    private width;
-    private color;
-    private isVisible;
-    constructor(parent: pixi.Container, textElement: pixi.Text, clipConfig: Clip, options?: TextCursorOptions);
-    updatePosition(textPosition: number): void;
-    setPosition(x: number, y: number): void;
-    show(): void;
-    hide(): void;
-    setVisible(visible: boolean): void;
-    startBlinking(): void;
-    stopBlinking(): void;
-    setBlinkInterval(intervalMs: number): void;
-    dispose(): void;
-    private createCursor;
-    private validateTextPosition;
-    private calculateAndApplyPixelPosition;
-    private calculatePixelPositionFromText;
-    private updateGraphicsPosition;
-    private startBlinkingAnimation;
-    private stopBlinkingAnimation;
-    private measureText;
-    isInitialized(): boolean;
-    getState(): object;
-}
-export {};

package/dist/src/components/canvas/text/text-editor.d.ts

@@ -1,43 +0,0 @@
-import type { TextPlayer } from "@canvas/players/text-player";
-import { type Clip } from "@schemas/clip";
-import * as pixi from "pixi.js";
-export declare enum HorizontalAlignment {
-    LEFT = "left",
-    CENTER = "center",
-    RIGHT = "right"
-}
-export declare enum VerticalAlignment {
-    TOP = "top",
-    CENTER = "center",
-    BOTTOM = "bottom"
-}
-export declare class TextEditor {
-    private static readonly DOUBLE_CLICK_THRESHOLD_MS;
-    private static readonly EDITING_BG_PADDING_PX;
-    private static readonly EDITING_BG_ALPHA;
-    private static readonly CLICK_HANDLER_DELAY_MS;
-    private parent;
-    private targetText;
-    private clipConfig;
-    private isEditing;
-    private lastClickTime;
-    private editingContainer;
-    private editableText;
-    private textCursor;
-    private textInputHandler;
-    private outsideClickHandler;
-    constructor(parent: TextPlayer, targetText: pixi.Text, clipConfig: Clip);
-    dispose(): void;
-    private startEditing;
-    private stopEditing;
-    private checkForDoubleClick;
-    private setupOutsideClickHandler;
-    private createEditingEnvironment;
-    private setupEditingContainer;
-    private setupTextInputHandler;
-    private updateTextAlignment;
-    private calculateHorizontalPosition;
-    private calculateVerticalPosition;
-    private getContainerDimensions;
-    private getAlignmentSettings;
-}

package/dist/src/components/canvas/text/text-input-handler.d.ts

@@ -1,54 +0,0 @@
-type TextInputHandlerOptions = {
-    initialText?: string;
-    autoFocus?: boolean;
-    focusDelay?: number;
-};
-type TextChangeCallback = (text: string, cursorPosition: number) => void;
-type KeyboardEventHandlers = {
-    onTextInput?: TextChangeCallback;
-    onCursorMove?: (direction: "left" | "right" | "up" | "down", event: KeyboardEvent) => void;
-    onEnter?: (event: KeyboardEvent) => void;
-    onEscape?: (event: KeyboardEvent) => void;
-    onDelete?: (type: "backspace" | "delete", event: KeyboardEvent) => void;
-    onFocus?: (event: FocusEvent) => void;
-    onBlur?: (event: FocusEvent) => void;
-    onTabNavigation?: (direction: "forward" | "backward") => void;
-    onCustomKey?: (key: string, event: KeyboardEvent) => boolean;
-};
-export declare class TextInputHandler {
-    private static readonly DEFAULT_FOCUS_DELAY_MS;
-    private hiddenInput;
-    private isFocused;
-    private focusRetryCount;
-    private maxFocusRetries;
-    private focusDelay;
-    private eventHandlers;
-    private abortController;
-    private textChangeCallback;
-    private lastSyncedText;
-    private isComposing;
-    setupInput(initialText: string, options?: TextInputHandlerOptions): void;
-    updateInputValue(text: string): void;
-    focusInput(): void;
-    blurInput(): void;
-    setSelectionRange(start: number, end: number): void;
-    getCursorPosition(): number;
-    getValue(): string;
-    setTextInputHandler(callback: TextChangeCallback): void;
-    setEventHandlers(handlers: Partial<KeyboardEventHandlers>): void;
-    isFocusedInput(): boolean;
-    dispose(): void;
-    private createHiddenTextarea;
-    private setupEventListeners;
-    private removeAllEventListeners;
-    private handleTextInput;
-    private handleKeyDown;
-    private handleKeyboardShortcuts;
-    private handleCompositionStart;
-    private handleCompositionEnd;
-    private handleFocus;
-    private handleBlur;
-    private handlePaste;
-    private selectAll;
-}
-export {};

package/dist/src/core/animations/curve-interpolator.d.ts

@@ -1,6 +0,0 @@
-export declare class CurveInterpolator {
-    private curves;
-    constructor();
-    private initializeCurves;
-    getValue(from: number, to: number, progress: number, easing?: string): number;
-}

package/dist/src/core/animations/effect-preset-builder.d.ts

@@ -1,18 +0,0 @@
-import { type Size } from "../layouts/geometry";
-import { type Clip } from "../schemas/clip";
-import { type Keyframe } from "../schemas/keyframe";
-export type EffectKeyframeSet = {
-    offsetXKeyframes: Keyframe[];
-    offsetYKeyframes: Keyframe[];
-    opacityKeyframes: Keyframe[];
-    scaleKeyframes: Keyframe[];
-    rotationKeyframes: Keyframe[];
-};
-export declare class EffectPresetBuilder {
-    private clipConfiguration;
-    constructor(clipConfiguration: Clip);
-    build(editSize: Size, clipSize: Size): EffectKeyframeSet;
-    private getPresetName;
-    private getZoomSpeed;
-    private getSlideStart;
-}