0.1.0 • Published 11 months ago

@jd177/vp-player v0.1.0

Weekly downloads
-
License
MIT
Repository
github
Last release
11 months ago

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.

Files Structure

├── src/
│   ├── components/
│   │   └── VPPlayer/
│   │       ├── VPPlayer.stories.tsx  # VP Player stories for Storybook
│   │       ├── VPPlayer.tsx          # VP Player React component
│   │       ├── index.ts              # Export file for the VPPlayer component
│   │       └── ui/
│   │           ├── VPPlayerUI.tsx    # UI-specific logic or subcomponent for VPPlayer
│   │           └── index.ts          # Export file for VPPlayerUI
├── .storybook/                       # Storybook configuration (assumed, not shown in your output)
│   ├── main.ts                       # Storybook config file
│   ├── preview.ts                    # Global Storybook settings
├── .env                              # Environment variables (e.g., VITE_VP_API_KEY)
├── tsconfig.json                     # TypeScript configuration
├── README.md                         # Project documentation
├── package.json                      # Project dependencies and scripts

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
  customStyles?: CustomStyles; // Optional object to apply custom CSS styles to player elements
}

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.

customStyles?: CustomStyles

  • Optional object allowing custom CSS styles to be applied to specific player elements. Keys are CSS class names of player elements (e.g., "vp-play-pause"), and values are objects containing CSS properties (e.g., { position: "absolute", top: "10px" }). This enables fine-grained control over the player's visual layout, such as repositioning buttons or changing colors. Supports !important for overriding default styles.
  • Example: { "vp-play-pause": { position: "absolute", top: "5%", left: "50%", transform: "translateX(-50%)" } } centers the play/pause button near the top of the player.

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.

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="<UNIQUE_RANDOM_INT>"
  version="latest"
  videoUrl="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
/>
  1. Playlist with Files\ Props: config with video.playlist\ Behavior: Plays a playlist of videos defined statically in the config prop.
Usage:
<VPPlayer
  playerId="<UNIQUE_RANDOM_INT>"
  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
    },
  }}
/>
  1. 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="<UNIQUE_RANDOM_INT>"
  version="latest"
  videoId="vjsnuxxx"
  projectId="agmipxxx"
/>
  1. 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="<UNIQUE_RANDOM_INT>"
  version="latest"
  projectId="agmipxxx"
  playlistId="lzxikxxx"
/>
  1. Example with Hidden Classes and Custom Styles\
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
  customStyles={{
    "vp-play-pause": {
      position: "absolute !important",
      top: "5% !important",
      left: "50% !important",
      transform: "translateX(-50%) !important",
      backgroundColor: "rgba(0, 0, 0, 0.3) !important",
      borderRadius: "60% !important",
      width: "40px !important",
      height: "40px !important",
    },
    "vp-next": {
      position: "absolute !important",
      top: "calc(100% - 50px) !important",
      right: "5% !important",
      transform: "rotate(90deg) !important",
      backgroundColor: "rgba(0, 0, 0, 0.3) !important",
      borderRadius: "60% !important",
      width: "40px !important",
      height: "40px !important",
    },
  }}
  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" },
        ],
      },
    },
  }}
/>
reactvideo-playervp-player
0.1.0

11 months ago