VP Player Component Documentation

The VPPlayer component is a React-based video player built using the VP Player library from https://host.vpplayer.tech.

It supports multiple ways to configure and play videos, including single files, playlists with direct files, single videos fetched via API, and playlists fetched via API. This document outlines the component's interface, configuration, and usage.

Overview

The VPPlayer component dynamically loads the VP Player script (vpplayer.js) and initializes it with a configuration object. The configuration is built based on the provided props, which determine the source and type of video data to play.

Source Files Structure

├── src/
│   ├── components/
│   │   └── VPPlayer/
│   │       ├── index.ts
│   │       └── ui/
│   │           ├── index.ts
│   │           ├── styled.tsx
│   ├── config/
│   │   ├── index.ts
│   │   ├── vpPlayerConfig.ts
│   ├── constants/
│   │   ├── index.ts
│   │   ├── vpPlayer.ts
│   ├── contexts/
│   │   ├── VPPlayerContext.tsx
│   │   ├── index.ts
│   ├── features/
│   │   ├── VPPlayer.tsx
│   │   ├── stories/
│   │   │   ├── ads/
│   │   │   │   ├── Ads.stories.tsx
│   │   │   ├── context/
│   │   │   │   ├── Context.stories.tsx
│   │   │   ├── playback/
│   │   │   │   ├── Playback.stories.tsx
│   ├── fixtures/
│   │   ├── index.ts
│   │   ├── playlist.ts
│   ├── hooks/
│   │   ├── index.ts
│   │   ├── useVPPlayerLogic.ts
│   │   ├── useVPPlayerScript.ts
│   │   ├── useVideoData.ts
│   ├── interfaces/
│   │   ├── config.ts
│   │   ├── index.ts
│   │   ├── instance.ts
│   │   ├── props.ts
│   │   ├── styles.ts
│   ├── types/
│   │   ├── api.types.ts
│   │   ├── index.ts
│   ├── utils/
│   │   ├── index.ts
│   │   ├── vpPlayerConfigBuilder.ts
│   │   ├── vpPlayerUtils.ts
│   ├── App.css
│   ├── App.tsx
│   ├── index.css
│   ├── main.tsx
│   ├── vite-env.d.ts

Interface

The component accepts props defined by the VPPlayerProps interface:

interface VPPlayerProps {
  playerId: string; // Unique identifier for the player instance, might be random integer,
                       but must be unique, for multiple VPPlayer instances use different values
  videoId?: string; // Unique identifier for the video or a placeholder
  version?: string | null; // Optional version e.g. "v2.1.1" of the VP Player script (defaults to 'latest')
  videoUrl?: string; // Direct URL to a single video file (e.g., .mp4, .m3u8)
  projectId?: string; // Project ID for API calls (used with videoId or playlistId)
  playlistId?: string; // Playlist ID for fetching a playlist from API
  config?: Partial<VPPlayerConfig>; // Optional partial configuration to override defaults
  apiKey?: string; // Optional API key for VP player requests; falls back to VP_API_KEY from .env if not provided.
  isReels?: boolean; // Optional flag to enable Reels/iShorties mode (defaults to false)
  thumbnailUrl?: string; // Optional URL to a thumbnail image for Reels mode
  hiddenClasses?: string[]; // Optional array of CSS class names to hide specific player elements
  className?: string; // Optional CSS class name for additional styling of the player
  onClose, // Handler function triggered when the player is closed.
  isPlayerVisible, // Flag indicating whether the player is currently visible.
}

Props Description

playerId: string

• Unique identifier for the player instance. Must be unique across multiple VPPlayer instances to avoid conflicts.

videoId?: string

• Optional identifier for a single video to fetch from the API. Used in conjunction with projectId for API-based video playback.

version?: string | null

• Optional version of the VP Player script (e.g., "v2.1.1"). Defaults to "latest" if not specified.

videoUrl?: string

• Optional direct URL to a video file (e.g., .mp4, .m3u8) for single-file playback without API involvement.

projectId?: string

• Optional project ID for API calls. Required when using videoId or playlistId to fetch video data from the API.

playlistId?: string

• Optional playlist ID for fetching a playlist from the API. Used with projectId to retrieve a dynamic playlist.

config?: Partial

• Optional partial configuration object to override the default VPPlayerConfig. Allows customization of player behavior and settings.

apiKey?: string

• Optional API key for VP Player API requests. Falls back to VITE_VP_API_KEY from .env if not provided. A warning is logged if missing for API-based configurations.

isReels?: boolean

• Optional flag to enable Reels/iShorties mode, optimizing the player for short vertical video playback (e.g., 9:16 aspect ratio). Defaults to false.

thumbnailUrl?: string

• Optional URL to a thumbnail image displayed in Reels mode before playback starts. Enhances the visual preview for short videos.

hiddenClasses?: string[]

• Optional array of CSS class names corresponding to player elements that should be hidden. Elements with these classes will have display: none applied, effectively removing them from the visible UI without affecting their underlying functionality (unless explicitly disabled). Useful for customizing the player's appearance by hiding unwanted controls.
• Example: ["vp-icon-share", "vp-icon-fullscreen"] hides the share and fullscreen buttons.

className?: string

• Optional CSS class name for additional styling of the player. This prop allows you to apply custom styles to the entire player component or its internal elements by targeting specific CSS classes (e.g., vp-play-pause, vp-control-bar). Styles must be defined in an external CSS file, and you can use !important to override default styles if needed. This provides flexibility to customize the player's appearance, such as changing colors, repositioning buttons, or adjusting layout.
• Example: "custom-player" can be used to apply styles defined in an external CSS file like .custom-player { border: 2px solid red; } or .custom-player .vp-play-pause { display: none; }.

onClose?: => void;

• Optional handler function triggered when the player is closed. This callback is invoked when the user closes the player, typically via a close button or an overlay dismissal.

isPlayerVisible?: boolean;

• Optional flag indicating whether the player is currently visible. Controls the visibility of the player component, typically used to show or hide the player in a modal, overlay, or inline context.

Configuration

The player configuration is defined by the VPPlayerConfig interface, which is partially overridden by the config prop and dynamically built based on the input types.

1. Script Loading: Loads the VP Player script (https://host.vpplayer.tech/player/${PLAYER_VERSION}/vpplayer.js) asynchronously if not already present.

2. Player Setup: Once the script is loaded and the DOM element is rendered, the vpPlayer function is called with the element's ID and the final configuration.

API Key Usage

The API key can be provided via the apiKey prop or the VITE_VP_API_KEY environment variable, with props taking precedence, and a warning is logged if neither is supplied for API requests.

• Source:
  • Props (apiKey) or .env (VITE_VP_API_KEY).
• Priority:
  • Props > .env.
• Fallback:
  • Optional, e.g., 'FALLBACK_TEST_KEY'.
• Warning:
  • Logged if missing for API calls.

Setting up the API Key

Step 1: Create a .env File

In the root of your project, create a .env file (or update an existing one) and add the following line:

VITE_VP_API_KEY=YOUR_API_KEY_HERE

Replace YOUR_API_KEY_HERE with your actual API key.

The VPPlayer component will automatically use the VITE_VP_API_KEY environment variable if the apiKey is not provided via props:

import { VPPlayer } from "@dvxx/vp-player";

const MyComponent = () => (
  <VPPlayer
    playerId="my-player"
    videoId="abcdefgh123"
    projectId="ijklmnop456"
    // apiKey will be read from VITE_VP_API_KEY since it is not passed
  />
);

Supported Data Input Types

Supported Data Input Types

The VPPlayer component supports multiple types of video data inputs, determined by the props provided:

1. Single Video File
   Props: videoUrl
   Behavior: Plays a single video directly from the provided URL.

Usage:

<VPPlayer
  playerId="player-1" // Must be a unique string (e.g., "player-1", "123", etc.)
  version="latest"
  videoUrl="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
/>

2. Playlist with Files
   Props: config with video.playlist
   Behavior: Plays a playlist of videos defined statically in the config prop.

Usage:

<VPPlayer
  playerId="player-2"
  version="latest"
  config={{
    projectId: 'vp-player-projectId', // optional placeholder
    video: {
      file: playlist.videos[0].file, // Initial video file, first in the queue
      playlist: playlist, // Pass the full playlist array object
    },
  }}
/>

3. Single Video via API (VideoId)
   Props: projectId, videoId
   Behavior: Fetches the playbackUrl from the API endpoint https://vp-api.gjirafa.tech/api/v2/projects/{projectId}/videos?search={videoId} and plays the video.

Usage:

<VPPlayer
  playerId="player-3"
  version="latest"
  videoId="vjsnuxxx"
  projectId="agmipxxx"
/>

4. Playlist via API (PlaylistId)
   Props: projectId, playlistId
   Behavior: Fetches a playlist from the API endpoint https://vp-api.gjirafa.tech/api/projects/{projectId}/playlists/{playlistId}/videos and builds a playlist object dynamically.

Usage:

<VPPlayer
  playerId="player-4"
  version="latest"
  projectId="agmipxxx"
  playlistId="lzxikxxx"
/>

5. Example with hiddenClasses and className\

Usage:

<VPPlayer
  playerId="player-5"
  isReels={true}
  thumbnailUrl="https://images.pexels.com/videos/4678261/pexels-photo-4678261.jpeg?auto=compress&cs=tinysrgb&w=600"
  hiddenClasses={["vp-icon-share", "vp-icon-fullscreen"]} // Hides share and fullscreen buttons
  className="custom-player" // Defined class for custom styling
  config={{
    video: {
      playlist: {
        state: true,
        playlistVideoIndex: 0,
        videos: [
          { videoId: "1", file: "https://videos.pexels.com/video-files/4678261/4678261-hd_1080_1920_25fps.mp4" },
          { videoId: "2", file: "https://videos.pexels.com/video-files/4678261/4678261-hd_1080_1920_25fps.mp4" },
        ],
      },
    },
  }}
/>

# e.g.
/* Define custom styles in your CSS file */
.custom-player {
  /* Your own styles here */
}