TypeScript Types

1// Root metadata structure
2interface MP4EMetadata {
3  schemaVersion: string;            // "2.0"
4  metadataType: string;             // "mp4e"
5
6  videoDetails: VideoDetails;
7  processingStats?: ProcessingStats;
8
9  objects: {
10    registry: ObjectRegistry;       // Keyed by objectId
11    timeline: FrameData[];          // Frame-by-frame positions
12  };
13
14  overlays: Overlay[];
15  rules: UnifiedRule[];
16  layers: Layer[];
17  variables: Variable[];
18
19  plugins: {
20    enabled: string[];              // Plugin types to enable
21    config: Record<string, any>;
22  };
23
24  objectGroups?: ObjectGroup[];
25  scenes?: Scene[];
26
27  videoId?: string;
28  videoMetadata?: VideoMetadata;
29  playerConfig?: PlayerConfig;
30  trackingEvents?: TrackingEventsConfig;
31  seo?: SEOMetadata;
32}
33
34interface VideoDetails {
35  totalFrames?: number | null;
36  totalFramesAnalyzed?: number | null;
37  fps?: number;
38  width?: number;
39  height?: number;
40  duration?: number;
41}
42
43interface SEOMetadata {
44  title: string;
45  description: string;
46  tags: string[];
47  chapters: Chapter[];
48  thumbnail?: {
49    type: 'frame' | 'custom';
50    frame?: number;
51    data?: string;              // Base64 JPEG for custom
52  };
53}
54
55interface Chapter {
56  id: string;
57  title: string;
58  description?: string;
59  startTime: number;
60  endTime: number;
61}

1// Object registry (keyed by objectId)
2type ObjectRegistry = Record<string, ObjectData>;
3
4interface ObjectData {
5  label: string;                    // AI-detected label
6  userLabel?: string;               // User-defined display name
7  confidence: number;               // Detection confidence (0-1)
8
9  // Tracking type
10  trackingType?: 'bbox' | 'polygon' | 'surface';
11  referencePolygon?: number[];      // Flattened coords for polygon tracking
12  surfaceData?: SurfaceData;        // For surface tracking
13
14  // Frame range
15  firstSeenFrame?: number;
16  lastSeenFrame?: number;
17
18  // Quality metrics
19  trackQuality?: number;
20  totalAppearances?: number;
21  occlusionRate?: number;
22
23  // E-commerce
24  buyLink?: string;
25  productId?: string;
26  price?: number;
27  currency?: string;
28  description?: string;
29
30  // AI analysis
31  llmAnalysis?: {
32    style?: string;
33    color?: string;
34    material?: string;
35    setting?: string;
36  };
37
38  // Custom data
39  customData?: Record<string, any>;
40}
41
42interface SurfaceData {
43  referenceFrame: number;
44  referenceCorners: SurfaceCorners;
45  trackingQuality?: 'draft' | 'standard' | 'high';
46}
47
48interface SurfaceCorners {
49  topLeft: { x: number; y: number };
50  topRight: { x: number; y: number };
51  bottomRight: { x: number; y: number };
52  bottomLeft: { x: number; y: number };
53}
54
55// Timeline frame data
56interface FrameData {
57  frame: number;
58  time: number;                     // frame / fps
59  objects: FrameObject[];
60}
61
62interface FrameObject {
63  id: string;                       // Reference to ObjectData
64  bboxXyxy: [number, number, number, number];  // [x1, y1, x2, y2] normalized
65  visibility?: number;              // 0-1
66  trackingConfidence?: number;      // Per-frame confidence
67
68  // For polygon tracking
69  polygon?: number[];               // Flattened coordinates
70
71  // For surface tracking
72  corners?: SurfaceCorners;
73  cornerConfidence?: number;
74}
75
76// Object groups
77interface ObjectGroup {
78  id: string;
79  name: string;
80  objectIds: string[];
81  displaySettings?: DisplaySettings;
82  rules?: UnifiedRule[];
83}
84
85// Displays: what opens for an object (object → group → project)
86interface DisplaySettings {
87  eventBindings: Array<{
88    event: string;                  // 'hovered' | 'clicked' | 'visible' | ...
89    enabled: boolean;
90    display: { type: string; config: Record<string, any>; [field: string]: any };
91    [field: string]: any;
92  }>;
93}
94
95// What a plugin reads about objects (mp4e.getObject / getVisibleObjects / getObjectBox).
96// Boxes are video pixels [x1, y1, x2, y2] at the current frame.
97interface PluginObject {
98  id: string;
99  label: string;
100  userLabel: string;
101  data: Record<string, any>;
102  groupIds: string[];
103  bbox: [number, number, number, number] | null;
104}
105
106interface ObjectBox {
107  visible: boolean;
108  bbox: [number, number, number, number] | null;
109  polygon: [number, number][] | null;
110}

1// All 16 variable types
2type VariableType =
3  | 'text'
4  | 'number'
5  | 'boolean'
6  | 'timer'
7  | 'counter'
8  | 'date'
9  | 'state'
10  | 'list'
11  | 'object'
12  | 'map'
13  | 'set'
14  | 'json'
15  | 'computed'
16  | 'accumulated'
17  | 'mapped'
18  | 'sequence';
19
20// Base variable structure
21interface VariableBase {
22  id: string;
23  name: string;
24  type: VariableType;
25  description?: string;
26  category?: string;
27  hidden?: boolean;
28  onChange?: Rule[];
29}
30
31// Text variable
32interface TextVariable extends VariableBase {
33  type: 'text';
34  initialValue: string;
35  validation?: {
36    minLength?: number;
37    maxLength?: number;
38    pattern?: string;
39  };
40}
41
42// Number variable
43interface NumberVariable extends VariableBase {
44  type: 'number';
45  initialValue: number;
46  min?: number;
47  max?: number;
48  step?: number;
49}
50
51// Boolean variable
52interface BooleanVariable extends VariableBase {
53  type: 'boolean';
54  initialValue: boolean;
55}
56
57// Timer variable
58interface TimerVariable extends VariableBase {
59  type: 'timer';
60  initialValue: number;             // Starting value in ms
61  direction: 'up' | 'down';
62  target?: number;                  // Target value for conditions
63  autoStart?: boolean;
64  pauseWithVideo?: boolean;
65}
66
67// Counter variable
68interface CounterVariable extends VariableBase {
69  type: 'counter';
70  initialValue: number;
71  min?: number;
72  max?: number;
73  step?: number;
74  overflow?: 'clamp' | 'wrap' | 'error';
75}
76
77// State machine variable
78interface StateVariable extends VariableBase {
79  type: 'state';
80  initialState: string;
81  states: string[];
82  transitions: StateTransition[];
83}
84
85interface StateTransition {
86  from: string;
87  to: string;
88  condition?: Condition;
89}
90
91// Date variable
92interface DateVariable extends VariableBase {
93  type: 'date';
94  initialValue: string | number | null;
95  format?: string;
96  timezone?: string;                    // IANA timezone identifier
97}
98
99// List/Array variable
100interface ListVariable extends VariableBase {
101  type: 'list';
102  initialValue: any[];
103  itemType?: 'string' | 'number' | 'object';
104  maxLength?: number;
105  unique?: boolean;
106}
107
108// Object variable
109interface ObjectVariable extends VariableBase {
110  type: 'object';
111  initialValue: Record<string, any>;
112  schema: {
113    fields: Array<{
114      key: string;
115      type: 'string' | 'number' | 'boolean';
116      required?: boolean;
117      default?: any;
118      label?: string;
119    }>;
120  };
121}
122
123// Map variable
124interface MapVariable extends VariableBase {
125  type: 'map';
126  initialValue: Record<string, any>;
127  keyType: 'string';
128  valueType: 'string' | 'number' | 'boolean';
129}
130
131// Set variable
132interface SetVariable extends VariableBase {
133  type: 'set';
134  initialValue: any[];
135  itemType: 'string' | 'number';
136  maxSize?: number;
137}
138
139// JSON variable
140interface JsonVariable extends VariableBase {
141  type: 'json';
142  initialValue: any;
143}
144
145// Computed variable
146interface ComputedVariable extends VariableBase {
147  type: 'computed';
148  expression: string;
149  dependencies: string[];
150  resultType?: 'string' | 'number' | 'boolean';
151  fallback?: any;
152}
153
154// Accumulated variable
155interface AccumulatedVariable extends VariableBase {
156  type: 'accumulated';
157  sourceVariable: string;
158  aggregation: 'sum' | 'avg' | 'min' | 'max' | 'count';
159  windowSize?: number;
160  sampleRate?: number;
161}
162
163// Mapped variable
164interface MappedVariable extends VariableBase {
165  type: 'mapped';
166  sourceVariable: string;
167  segments: MappedSegment[];
168  defaultOutput?: any;
169  easing?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';
170}
171
172interface MappedSegment {
173  from: number;
174  to: number;
175  output: any;
176}
177
178// Sequence variable — ordered entry lookup against a source value.
179// Pure: the value depends only on the source, never on playback history.
180interface SequenceVariable extends VariableBase {
181  type: 'sequence';
182  /** Variable id/name, or a single wrapped expression like '{{currentFrame}}' */
183  source: string;
184  /** 'range' compares from/to numerically; 'equals' compares scalars */
185  match: 'range' | 'equals';
186  /** Ordered — first match wins; overlaps are legal */
187  entries: SequenceEntry[];
188  /** Value when no entry matches (default null) */
189  fallback?: any;
190}
191
192interface SequenceEntry {
193  /** Range mode: inclusive lower bound */
194  from?: number;
195  /** Range mode: inclusive upper bound */
196  to?: number;
197  /** Equals mode: the scalar to match */
198  equals?: any;
199  /** Any JSON. Interpolated on selection, including nested object fields */
200  value: any;
201}
202
203// Union type
204type Variable =
205  | TextVariable
206  | NumberVariable
207  | BooleanVariable
208  | TimerVariable
209  | CounterVariable
210  | DateVariable
211  | StateVariable
212  | ListVariable
213  | ObjectVariable
214  | MapVariable
215  | SetVariable
216  | JsonVariable
217  | ComputedVariable
218  | AccumulatedVariable
219  | MappedVariable
220  | SequenceVariable;

1// Unified rule system
2interface UnifiedRule {
3  id: string;
4  name?: string;
5  enabled: boolean;
6  priority: number;                 // Higher = evaluated first
7
8  trigger?: UnifiedTrigger;
9  conditions: RuleGroup | Condition;
10  onMatch?: Action[];
11  onUnmatch?: Action[];
12
13  evaluateOn?: ('frame' | 'event' | 'stateChange')[];
14  cacheResult?: boolean;
15  cacheTTL?: number;
16  description?: string;
17}
18
19// Condition group
20interface RuleGroup {
21  logic: 'ALL' | 'ANY' | 'NONE';
22  conditions: (RuleGroup | Condition)[];
23}
24
25// All 21 condition types
26type ConditionType =
27  | 'variable'
28  | 'timerVariable'
29  | 'counterVariable'
30  | 'stateMachineVariable'
31  | 'arrayVariable'
32  | 'state'
33  | 'event'
34  | 'eventData'
35  | 'elementStats'
36  | 'playbackStatus'
37  | 'time'
38  | 'frame'
39  | 'object'
40  | 'userAttribute'
41  | 'abTest'
42  | 'device'
43  | 'geo'
44  | 'schedule'
45  | 'pluginState'
46  | 'expression'
47  | 'inputKey';
48
49// Comparison operators
50type ComparisonOperator =
51  | 'eq' | 'neq'
52  | 'gt' | 'gte' | 'lt' | 'lte'
53  | 'in' | 'notIn'
54  | 'contains' | 'startsWith' | 'endsWith'
55  | 'matches'
56  | 'exists' | 'notExists'
57  | 'between';
58
59// Base condition
60interface ConditionBase {
61  type: ConditionType;
62  operator?: ComparisonOperator;
63  value?: any;
64  value2?: any;                     // For 'between' operator
65}
66
67// Variable condition
68interface VariableCondition extends ConditionBase {
69  type: 'variable';
70  name: string;
71}
72
73// Time condition
74interface TimeCondition extends ConditionBase {
75  type: 'time';
76  timeType: 'playback' | 'wallClock' | 'sessionDuration';
77}
78
79// Object condition
80interface ObjectCondition extends ConditionBase {
81  type: 'object';
82  objectId?: string;
83  groupId?: string;
84  check: 'isVisible' | 'anyVisible' | 'confidence';
85}
86
87// Device condition
88interface DeviceCondition extends ConditionBase {
89  type: 'device';
90  deviceType: 'mobile' | 'tablet' | 'desktop';
91}
92
93// Element stats condition
94interface ElementStatsCondition extends ConditionBase {
95  type: 'elementStats';
96  elementId: string;
97  stat: 'hoverCount' | 'clickCount' | 'dwellTimeMs' | 'firstInteractionAt' | 'lastInteractionAt';
98}
99
100// Playback status condition
101interface PlaybackStatusCondition extends ConditionBase {
102  type: 'playbackStatus';
103  check: 'isPlaying' | 'isPaused' | 'isMuted' | 'volume' | 'playbackRate';
104}
105
106// Expression condition
107interface ExpressionCondition extends ConditionBase {
108  type: 'expression';
109  expression: string;
110}
111
112// Union type (simplified - add more as needed)
113type Condition =
114  | VariableCondition
115  | TimeCondition
116  | ObjectCondition
117  | DeviceCondition
118  | ElementStatsCondition
119  | PlaybackStatusCondition
120  | ExpressionCondition
121  | ConditionBase;

1// Overlay type
2interface Overlay {
3  id: string;
4  name: string;
5  type: string;                     // Plugin type (e.g., "core:button")
6  zIndex: number;
7  opacity: number;
8
9  // Positioning
10  position: OverlayPosition;
11  size?: OverlaySize;
12
13  // Visibility
14  visibility: OverlayVisibility;
15
16  // Plugin configuration
17  config: Record<string, any>;
18
19  // Object binding (for attached overlays)
20  objectBinding?: OverlayObjectBinding;
21
22  // Engine-resolved crop of the playing video, drawn beneath this overlay's
23  // plugin. Independent of objectBinding: the overlay can be positioned by one
24  // object while its crop follows another.
25  videoRegion?: VideoRegion;
26
27  // Animation
28  animation?: OverlayAnimation;
29
30  // Events
31  eventHandlers?: Record<string, Action[]>;
32  eventRules?: Record<string, Rule[]>;
33}
34
35interface VideoRegion {
36  source: VideoRegionSource;
37  shape?: 'circle' | 'roundedRect' | 'none';
38  radius?: number | string;
39  fit?: 'cover' | 'contain';
40  opacity?: number | string;
41  /** Soft edge in px; 0 = hard edge */
42  feather?: number | string;
43  /** Named params, not a CSS filter string — native players map these too */
44  filter?: {
45    brightness?: number | string;
46    contrast?: number | string;
47    saturate?: number | string;
48    blur?: number | string;
49    invert?: number | string;
50    grayscale?: number | string;
51  };
52  border?: { width?: number | string; color?: string };
53}
54
55// Every field accepts a string as well as a number: a templated value
56// (e.g. "{{Shot.sx}}") resolves to a string, which the engine coerces.
57type VideoRegionSource =
58  | { mode: 'rect'; x: number | string; y: number | string;
59      w: number | string; h: number | string }
60  | { mode: 'object'; objectId: string; padding?: number | string };
61
62interface OverlayPosition {
63  type: 'fixed' | 'attached' | 'absolute';
64
65  // For fixed/absolute
66  x?: number;
67  y?: number;
68  anchor?: 'top-left' | 'top-center' | 'top-right' |
69           'center-left' | 'center' | 'center-right' |
70           'bottom-left' | 'bottom-center' | 'bottom-right';
71
72  // For attached (to object)
73  objectId?: string;
74  offset?: { x: number; y: number };
75  followObject?: boolean;
76}
77
78interface OverlaySize {
79  width: number | 'auto';
80  height: number | 'auto';
81  minWidth?: number;
82  maxWidth?: number;
83  minHeight?: number;
84  maxHeight?: number;
85  aspectRatio?: number;
86  scaleWithVideo?: boolean;
87}
88
89interface OverlayVisibility {
90  fromFrame?: number;
91  toFrame?: number;
92  showWhen?: Condition | RuleGroup;
93  hideWhen?: Condition | RuleGroup;
94  rules?: Rule[];
95}
96
97interface OverlayObjectBinding {
98  objectId: string;
99  position: 'above' | 'below' | 'left' | 'right' | 'center';
100  offset?: { x: number; y: number };
101  showOnHover?: boolean;
102  showOnClick?: boolean;
103  followPosition?: boolean;
104}
105
106interface OverlayAnimation {
107  enter?: AnimationConfig;
108  exit?: AnimationConfig;
109  idle?: AnimationConfig;
110}
111
112interface AnimationConfig {
113  type: 'fade' | 'slide' | 'scale' | 'bounce' | 'none';
114  duration?: number;
115  delay?: number;
116  easing?: string;
117  direction?: 'up' | 'down' | 'left' | 'right';
118}
119
120// Layer structure
121interface Layer {
122  id: string;
123  name: string;
124  order: number;
125  enabled: boolean;
126  blendMode: 'merge' | 'replace' | 'exclusive';
127
128  overlays: Overlay[];
129  rules?: LayerRule;
130  visibilityRules?: LayerVisibilityRule;
131
132  locked?: boolean;
133  color?: string;
134  collapsed?: boolean;
135}
136
137interface LayerVisibilityRule {
138  logic: 'ALL' | 'ANY' | 'NONE';
139  conditions: (RuleGroup | Condition)[];
140}

1// Common action types (69 total — see Actions Reference for complete list)
2type ActionType =
3  | 'seek'
4  | 'play'
5  | 'pause'
6  | 'goToScene'
7  | 'openUrl'
8  | 'navigate'
9  | 'showOverlay'
10  | 'hideOverlay'
11  | 'toggleOverlay'
12  | 'setVariable'
13  | 'setState'
14  | 'timerControl'
15  | 'counterControl'
16  | 'arrayControl'
17  | 'trackEvent'
18  | 'emitEvent'
19  | 'pluginAction'
20  | 'showNotification'
21  | 'showTracking'
22  | 'hideTracking'
23  | 'setPlaybackRate'
24  | 'setVolume'
25  | 'mute'
26  | 'unmute'
27  | 'wait'
28  | 'showCustomModal'
29  | 'closeCustomModal'
30  | 'setOverlayStyle'
31  | string;  // 69 types total — extensible
32
33// Base action
34interface ActionBase {
35  type: ActionType;
36  delay?: number;                   // Delay before execution (ms)
37  condition?: Condition;            // Only execute if condition met
38}
39
40// Seek action
41interface SeekAction extends ActionBase {
42  type: 'seek';
43  time?: number;                    // Seconds
44  frame?: number;                   // Frame number
45  relative?: boolean;               // Relative to current position
46}
47
48// Open URL action
49interface OpenUrlAction extends ActionBase {
50  type: 'openUrl';
51  url: string;
52  target?: 'blank' | 'self' | 'parent' | 'top';
53}
54
55// Overlay actions
56interface ShowOverlayAction extends ActionBase {
57  type: 'showOverlay';
58  overlayId: string;
59}
60
61interface HideOverlayAction extends ActionBase {
62  type: 'hideOverlay';
63  overlayId: string;
64}
65
66// Playback actions
67interface PauseAction extends ActionBase {
68  type: 'pause';
69  reason?: string;
70}
71
72interface PlayAction extends ActionBase {
73  type: 'play';
74}
75
76interface SetPlaybackRateAction extends ActionBase {
77  type: 'setPlaybackRate';
78  rate: number;                     // 0.25 - 2.0
79}
80
81interface SetVolumeAction extends ActionBase {
82  type: 'setVolume';
83  volume: number;                   // 0.0 - 1.0
84}
85
86// State action
87interface SetStateAction extends ActionBase {
88  type: 'setState';
89  key: string;
90  value: any;                       // Can be expression string
91}
92
93// Track event action
94interface TrackEventAction extends ActionBase {
95  type: 'trackEvent';
96  eventName: string;
97  properties?: Record<string, any>;
98}
99
100// Highlight object action
101interface HighlightObjectAction extends ActionBase {
102  type: 'highlightObject';
103  objectId: string;
104  duration?: number;                // ms
105  style?: {
106    color?: string;
107    borderWidth?: number;
108    animation?: string;
109  };
110}
111
112// Show notification action
113interface ShowNotificationAction extends ActionBase {
114  type: 'showNotification';
115  message: string;
116  variant?: 'info' | 'success' | 'warning' | 'error';
117  duration?: number;                // ms (0 = persistent)
118  position?: 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
119}
120
121// Plugin action
122interface CallPluginAction extends ActionBase {
123  type: 'callPlugin';
124  plugin: string;                   // pluginName.methodName
125  params?: Record<string, any>;
126}
127
128// Union type
129type Action =
130  | SeekAction
131  | OpenUrlAction
132  | ShowOverlayAction
133  | HideOverlayAction
134  | PauseAction
135  | PlayAction
136  | SetPlaybackRateAction
137  | SetVolumeAction
138  | SetStateAction
139  | TrackEventAction
140  | HighlightObjectAction
141  | ShowNotificationAction
142  | CallPluginAction
143  | { type: 'mute' }
144  | { type: 'unmute' };

1// Player component props
2interface MP4EPlayerProps {
3  // Source
4  src: string;
5  metadata?: MP4EMetadata | string;
6
7  // Playback
8  autoplay?: boolean;
9  muted?: boolean;
10  loop?: boolean;
11  preload?: 'none' | 'metadata' | 'auto';
12  playbackRate?: number;
13  startTime?: number;
14
15  // Display
16  width?: number | string;
17  height?: number | string;
18  aspectRatio?: '16:9' | '4:3' | '1:1' | 'auto';
19  objectFit?: 'contain' | 'cover' | 'fill';
20  poster?: string;
21
22  // Features
23  interactive?: boolean;
24  showObjects?: boolean;
25  showOverlays?: boolean;
26  showControls?: boolean;
27  objectGroups?: string[];
28
29  // Overrides
30  overrideVariables?: Record<string, any>;
31  overrideDisplaySettings?: DisplaySettings;
32
33  // Debug
34  debug?: boolean;
35  showDebugOverlay?: boolean;
36
37  // Callbacks - Lifecycle
38  onReady?: () => void;
39  onLoad?: (event: { duration: number }) => void;
40  onMetadataLoaded?: (view: MetadataView) => void;
41  onEngineReady?: (engine: MP4EEngine) => void;
42  onDestroy?: () => void;
43
44  // Callbacks - Playback
45  onPlay?: () => void;
46  onPause?: (event: { currentTime: number; reason?: string }) => void;
47  onEnded?: () => void;
48  onTimeUpdate?: (event: { currentTime: number; currentFrame: number }) => void;
49  onSeeking?: (event: { fromTime: number; toTime: number }) => void;
50  onSeeked?: (event: { currentTime: number }) => void;
51  onBufferStart?: () => void;
52  onBufferEnd?: () => void;
53  onVolumeChange?: (event: { volume: number }) => void;
54  onRateChange?: (event: { playbackRate: number }) => void;
55  onFirstPlay?: () => void;
56
57  // Callbacks - Objects
58  onObjectClick?: (event: ObjectEvent) => void;
59  onObjectHover?: (event: ObjectEvent) => void;
60  onObjectHoverEnd?: (event: ObjectEvent) => void;
61  onObjectVisible?: (event: ObjectEvent) => void;
62  onObjectHidden?: (event: ObjectEvent) => void;
63
64  // Callbacks - Plugins
65  onPluginEvent?: (event: { pluginId: string; eventName: string; data: any }) => void;
66
67  // Callbacks - Variables
68  onVariableChange?: (event: { variableName: string; previousValue: any; newValue: any }) => void;
69
70  // Callbacks - Actions
71  onAction?: (action: Action) => boolean | void;
72  onTrackEvent?: (event: { eventName: string; properties: Record<string, any> }) => void;
73
74  // Callbacks - Errors
75  onError?: (error: { message: string; code: string; details?: any }) => void;
76
77  // Styling
78  className?: string;
79  style?: React.CSSProperties;
80}
81
82interface ObjectEvent {
83  objectId: string;
84  objectLabel: string;
85  confidence: number;
86  boundingBox: { x: number; y: number; width: number; height: number };
87  objectData?: ObjectData;
88  clickX?: number;
89  clickY?: number;
90}
91
92// The loaded document's view (metadata:loaded, getEffectiveMetadata()).
93// Host overrides are already merged in. Objects, variables, rules,
94// scenes and plugins are not part of it.
95interface MetadataView {
96  schemaVersion: string;
97  videoDetails: { fps: number | null; width: number | null; height: number | null; durationSeconds: number | null };
98  layers: Array<{ id: string; name?: string; order?: number; overlays: MetadataViewOverlay[] }>;
99  overlays: Record<string, MetadataViewOverlay>; // normally {} — overlays live in layers[].overlays
100  audioTracks: any[];
101  media: Record<string, any> | null;
102  thumbnails: any | null;
103  objectCount: number;
104  // 'chunked' for a file exported with streamTimeline: object tracking is
105  // fetched while the video plays (timeline:* events)
106  timeline?: { mode: 'full' | 'chunked' };
107}
108
109interface MetadataViewOverlay {
110  id: string;
111  layerId?: string;
112  type?: string;
113  name?: string;
114  overlayCategory?: string;
115  position?: any;
116  size?: any;
117  config?: any;
118  opacity?: number;
119  zIndex?: number;
120}
121
122// Player ref methods
123interface MP4EPlayerRef {
124  // Playback control
125  play(): void;
126  pause(): void;
127  seek(time: number): void;
128  seekToFrame(frame: number): void;
129  setPlaybackRate(rate: number): void;
130  setVolume(volume: number): void;
131  mute(): void;
132  unmute(): void;
133
134  // State getters
135  getCurrentTime(): number;
136  getCurrentFrame(): number;
137  getDuration(): number;
138  getTotalFrames(): number;
139  isPaused(): boolean;
140  isMuted(): boolean;
141  getVolume(): number;
142  getPlaybackRate(): number;
143
144  // Objects
145  getVisibleObjects(): ObjectData[];
146  getAllObjects(): ObjectRegistry;
147  highlightObject(objectId: string, duration?: number): void;
148
149  // Variables
150  getVariable(name: string): any;
151  setVariable(name: string, value: any): void;
152  resetVariables(): void;
153
154  // Actions
155  executeAction(action: Action): void;
156  executeActions(actions: Action[]): void;
157
158  // Overlays
159  showOverlay(overlayId: string): void;
160  hideOverlay(overlayId: string): void;
161
162  // Scenes
163  goToScene(sceneId: string): void;
164  getCurrentScene(): string | null;
165
166  // Engine access
167  getEngine(): MP4EEngine | null;
168  getEffectiveMetadata(): MetadataView | null;
169
170  // Video element
171  getVideoElement(): HTMLVideoElement | null;
172}