@interactive-video-labs/react

Welcome to @interactive-video-labs/react — a lightweight React wrapper around the @interactive-video-labs/core engine for cue-driven interactive video experiences.

This wrapper makes it easy to embed interactive video players in React apps using familiar props and event handlers, while keeping close to the core API.

Introduction

@interactive-video-labs/react is a thin React component that provides a convenient way to integrate interactive video experiences into your React applications. It leverages the powerful @interactive-video-labs/core engine, allowing you to easily manage video playback, cue points, and analytics within a familiar React paradigm.

Features

• Easy Integration: Seamlessly embed interactive videos into your React components.
• Cue Point Management: Load and manage cue points for dynamic video interactions.
• Analytics Events: Receive detailed analytics events from the video player to track user engagement.
• Localization: Support for player localization through translations.
• Direct Core API Access: Provides a React-friendly interface while maintaining close alignment with the core IVLabsPlayer API.

Installation

You can install the package using npm or pnpm:

pnpm add @interactive-video-labs/react @interactive-video-labs/core react react-dom
# or
npm install @interactive-video-labs/react @interactive-video-labs/core react react-dom

Usage

To use the InteractiveVideo component, simply import it and pass the necessary props. The videoUrl prop is mandatory.

import React from 'react';
import { InteractiveVideo } from '@interactive-video-labs/react';

const MyVideoPlayer = () => {
  return (
    <div style={{ width: '100%', maxWidth: '800px', margin: '0 auto' }}>
      <InteractiveVideo
        videoUrl="https://interactive-video-labs.github.io/interactive-video-demos/videos/big_buck_bunny.mp4"
        autoplay={true}
        loop={false}
        controls={true}
        onAnalyticsEvent={(event, payload) => {
          console.log('Analytics Event:', event, payload);
          // Handle analytics events, e.g., send to a tracking service
        }}
        cues={[
          {
            id: 'segmentChange',
            time: 10,
            label: 'Segment Change',
            payload: {
              interaction: {
                type: 'choice-video-segment-change',
                title: 'Choose your path',
                description: 'Select a video segment to jump to.',
                question: 'Where would you like to go?',
                options: [
                  {
                    level: 'Segment A',
                    video:
                      'https://interactive-video-labs.github.io/assets/sample-interaction-1.mp4',
                  },
                  {
                    level: 'Segment B',
                    video:
                      'https://interactive-video-labs.github.io/assets/sample-interaction-2.mp4',
                  },
                ],
              },
            },
          },
        ]}
        translations={{
          en: {
            play: 'Play Video',
            pause: 'Pause Video',
          },
        }}
      />
    </div>
  );
};

export default MyVideoPlayer;

Props

The InteractiveVideo component accepts the following props:

• videoUrl (string, required): The URL of the video to be played.
• onAnalyticsEvent (function, optional): A callback function that is triggered when an analytics event occurs. It receives the event name and an optional payload.
  • event: PLAYER_LOADED, VIDEO_STARTED, VIDEO_PAUSED, VIDEO_ENDED, CUE_TRIGGERED, INTERACTION_COMPLETED, ERROR.
  • payload: An object containing event-specific data.
• cues (CuePoint[], optional): An array of cue points to load into the player. Each CuePoint object should conform to the @interactive-video-labs/core CuePoint interface.
• translations (Translations, optional): An object containing translations for player localization. This should conform to the @interactive-video-labs/core Translations interface.
• ...restOptions (PlayerConfig, optional): Any other valid PlayerConfig options from @interactive-video-labs/core (excluding videoUrl, cues, and translations). This allows for direct pass-through of core player configurations like autoplay, loop, controls, locale, etc.

Development

To set up the development environment:

1. Clone the repository.
2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm build

4. Run tests:

   pnpm test

5. Run examples:

   pnpm serve-examples

Contributing

We welcome contributions! Please see our CONTRIBUTING.md for more details.

License

This project is licensed under the MIT License. See the LICENSE file for details.