Welcome to @interactive-video-labs/svelte
β a lightweight Svelte wrapper around the @interactive-video-labs/core
engine for cue-driven interactive video experiences.
This wrapper enables seamless integration of interactive video players into Svelte applications using idiomatic props and DOM events, while staying close to the underlying core engine API.
on:analyticsEvent
on the component.@interactive-video-labs/core
player instance.Install the package and its peer dependencies:
# With pnpm
pnpm add @interactive-video-labs/svelte @interactive-video-labs/core svelte
# With npm
npm install @interactive-video-labs/svelte @interactive-video-labs/core svelte
# With yarn
yarn add @interactive-video-labs/svelte @interactive-video-labs/core svelte
Hereβs a simple example of how to use the <InteractiveVideo />
component in a Svelte app.
<script lang="ts">
import InteractiveVideo from '@interactive-video-labs/svelte';
import '@interactive-video-labs/core/dist/style.css'; // Import styles
let videoUrl = 'https://example.com/my-video.mp4';
type CuePoint = {
time: number;
payload: any;
};
let cues: CuePoint[] = [
{ time: 10, payload: { type: 'text', content: 'This is a timed message!' } },
{ time: 25, payload: { type: 'quiz', question: 'What is Svelte?' } }
];
function handleAnalyticsEvent(event: CustomEvent<{ event: string; payload?: any }>) {
console.log('Analytics Event:', event.detail.event, event.detail.payload);
}
</script>
<InteractiveVideo
{videoUrl}
{cues}
autoplay
loop
on:analyticsEvent={handleAnalyticsEvent}
/>
Prop | Type | Required | Default | Description |
---|---|---|---|---|
videoUrl |
string |
true |
β | The URL of the video to be loaded. |
cues |
CuePoint[] |
false |
[] |
An array of cue points for interactive events. Reactive/updated at runtime. |
translations |
Translations |
false |
{} |
Translations for the player UI. |
autoplay |
boolean |
false |
false |
Whether the video should start playing automatically. |
loop |
boolean |
false |
false |
Whether the video should loop. |
locale |
string |
false |
'en' |
The locale to be used for the player (e.g., 'en' , 'es' ). |
bind:playerRef |
Player (@interactive-video-labs/core ) |
false |
β | Two-way bind to access the underlying core player instance. |
Any additional attributes supported by
@interactive-video-labs/core
will be forwarded to the player configuration.
Player analytics/events are dispatched as a Svelte DOM event named analyticsEvent
.
Dispatched detail
shape:
type AnalyticsDetail = {
event: 'PLAYER_LOADED' | 'VIDEO_STARTED' | 'VIDEO_PAUSED' | 'VIDEO_ENDED' |
'CUE_TRIGGERED' | 'INTERACTION_COMPLETED' | 'ERROR';
payload?: any;
};
Available Events:
PLAYER_LOADED
VIDEO_STARTED
VIDEO_PAUSED
VIDEO_ENDED
CUE_TRIGGERED
INTERACTION_COMPLETED
ERROR
Example:
<script lang="ts">
function onAnalytics(e: CustomEvent<{ event: string; payload?: any }>) {
const { event, payload } = e.detail;
if (event === 'CUE_TRIGGERED') {
console.log('Cue at:', payload?.cue?.time);
} else if (event === 'ERROR') {
console.error('Player error:', payload?.error);
}
}
</script>
<InteractiveVideo on:analyticsEvent={onAnalytics} />
If you need to call methods on the underlying core player:
<script lang="ts">
import { onMount } from 'svelte';
import InteractiveVideo from '@interactive-video-labs/svelte';
import type { Player } from '@interactive-video-labs/core';
let playerRef: Player | null = null;
onMount(() => {
// `playerRef` is now bound to the core player instance
playerRef?.play();
});
</script>
<InteractiveVideo
videoUrl="https://example.com/my-video.mp4"
bind:playerRef
/>
For detailed development setup, project structure, testing, build, and publishing instructions, please refer to our Developer Guide (DEVELOPER.md
).
Contributions are welcome! Please read our Contributing Guidelines to get started.
This project is licensed under the MIT License. See the LICENSE file for details.