@vcomm/fvv-player

v1.0.2

Published

6 months ago

FVV Player HTML Component with remote control and radar plugin support

0High
0Medium
0Low

Interactive Free Viewpoint Video Technology

is a system for creating and viewing natural video from various points of view on events, allowing the user to interactively control the viewpoint and generate new views of dynamic scenes from any 3D position.

View video

FVV Player - Interactive HTML Component for Free Viewpoint Video

<fvv-player> is a powerful and flexible Web Component that allows you to embed an interactive Free Viewpoint Video (FVV) experience into any webpage. Turn passive viewers into active operators by giving them full control over the viewpoint, zoom, and height within a 3D scene.

This component is built from the ground up using modern web technologies (WebGL, Web Components) and features a unique Filmscript engine, enabling users to record and share their unique viewing scenarios.

Demo

🌟 Key Features

Complete Viewpoint Freedom: An interactive 3D spherical radar for intuitive viewpoint control.
Intelligent Switching: Smooth, "cinematic" transitions between cameras without blurring or artifacts.
Digital Zoom & Height Control: Full control over the virtual camera in 3D space.
Filmscript Engine: A unique ability to record, save, load, and share custom viewing scenarios. Every viewer is a director!
Remote Control: Instantly turn any smartphone into an advanced joystick by scanning a QR code.
Flexibility & Customization: Easily customize the player's appearance using CSS Custom Properties.
Modular Architecture: The ability to plug in custom plugins for the radar and other UI elements.
High Performance: WebGL-based rendering ensures smooth performance even with high-resolution videos.

🚀 Installation and Usage

1. Installation

The project is distributed as an npm package. Install it in your project:

npm install @vcomm/fvv-player

Then, import the component in your main JavaScript file:

import '@vcomm/fvv-player';

2. Content Preparation

You will need three things:

A folder with video files: A set of synchronized videos captured from different angles.
manifest.json: A file describing the list of videos.
cameramap.json: A file with the spatial coordinates of each camera.

manifest.json (example):

{
  "tracks": [
    { "id": "cam01", "url": "/vids/cam01.mp4" },
    { "id": "cam02", "url": "/vids/cam02.mp4" },
    { "id": "cam03", "url": "/vids/cam03.mp4" },
    { "id": "cam04", "url": "/vids/cam04.mp4" }
  ]
}

cameramap.json (example): The pos coordinates are defined as [azimuth, elevation, height].

{
  "layout": [
    { "id": "north-pole", "pos": [0, 0, 0]  }, 
    { "id": "south-pole", "pos": [180, 0, 0] },
    { "id": "cam01", "pos": [ -45, -30, 0 ] },
    { "id": "cam02", "pos": [ 45, -30, 0 ] },
    { "id": "cam03", "pos": [ -45, 30, 0 ] },
    { "id": "cam04", "pos": [ 45, 30, 0 ] }
  ]
}

2.5. Setting up the Pairing Server

The remote control functionality requires a running public Firebase or your own WebSocket server. You can use our ready-made pairing server.

Clone the server repository:

git clone https://github.com/your-repo/fvv-pairing-server.git
cd fvv-pairing-server

Install dependencies:
```
npm install
```
Run the server:
```
node server.js
```
Deploy it to a hosting service (e.g., Render, Heroku) to get a public wss:// URL, which you will use in the pairing-service-url attribute.

3. Usage in HTML

Insert the <fvv-player> tag into your page, providing all the necessary attributes:

<fvv-player
    src="path/to/manifest.json"
    camera-map="path/to/cameramap.json"
    pairing-service-url="wss://your-pairing-server.com"
    remote-url="https://your-app.com"
    radar-plugin-src="path/to/fvv-radar-sphere.js"
    simulation-mode>
</fvv-player>

🛠️ API and Attributes

Attributes

src: (Required) Path to manifest.json.
camera-map: (Required) Path to cameramap.json.
pairing-service-url: (Required) URL of your WebSocket server for remote pairing.
remote-url: (Required) The base URL where the remote.html page is hosted.
radar-plugin-src: (Optional) Path to the radar plugin's JS file.
simulation-mode: If present, the player will use internal simulations instead of real video files. Ideal for debugging.

Customization (CSS Custom Properties)

You can easily change the player's appearance by overriding CSS variables.

fvv-player {
  /* Set new dimensions */
  --fvv-width: 100%;
  --fvv-height: 90vh;

  /* Change radar colors */
  --fvv-radar-point-color: hotpink;
  --fvv-radar-crosshair-color: white;
}

Player HTML example `index.html`

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8">
  <title>Free Viewpoint Video Player</title>
  <style>
    body { 
      background-color: #f0f0f0; 
      display: flex;
      justify-content: center;
      align-items: center;
      flex-direction: column;
      height: 100vh; 
      margin: 0; 
      font-family: sans-serif;
    }
    
    fvv-player {
      --fvv-width: 1280px; 
      --fvv-height: 720px; 
      --fvv-radar-point-color: #FF69B4; /* Hot Pink */
      --fvv-radar-point-active-color: white;
      --fvv-radar-crosshair-color: #00FF7F; /* Spring Green */
    }
  </style>
  
  <script src="node_modules/@vcomm/fvv-player/dist/fvv-player.js" type="module"></script>
</head>
<body>
  <h1>Testing Free Viewpoint Video (FVV) Player</h1>

    <fvv-player
        pairing-provider="firebase"
        src="manifest.json"
        camera-map="cameramap.json"
        radar-plugin-src="/node_modules/@vcomm/fvv-player/dist/fvv-radar-sphere.js"
        simulation-mode>
    </fvv-player>
</body>
</html>

Remote HTML example `remote.html`

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
    <title>FVV Remote</title>
    <script src="https://www.gstatic.com/firebasejs/9.22.2/firebase-app-compat.js"></script>
    <script src="https://www.gstatic.com/firebasejs/9.22.2/firebase-database-compat.js"></script>
    <style>
        body { font-family: sans-serif; text-align: center; background: #333; color: white; touch-action: none; display: flex; flex-direction: column; justify-content: center; align-items: center; height: 100vh; margin: 0; }
        .joystick-zone { display: flex; justify-content: space-around; width: 100%; align-items: center; }
        .joystick-wrapper { display: flex; flex-direction: column; align-items: center; }
        .joystick-container { position: relative; width: 150px; height: 150px; background: rgba(255,255,255,0.1); border-radius: 50%; }
        .joystick-handle { position: absolute; width: 50px; height: 50px; background: rgba(255,255,255,0.8); border-radius: 50%; top: 50px; left: 50px; }
        #status { font-size: 20px; position: absolute; top: 20px; }
        label { margin-bottom: 10px; }
    </style>
</head>
<body>
    <p id="status">Connection ...</p>
    <div class="joystick-zone">
        <div class="joystick-wrapper"> <label for="move-joystick">Rotation</label> <div id="move-joystick" class="joystick-container"><div id="move-handle" class="joystick-handle"></div></div> </div>
        <div class="joystick-wrapper"> <label for="zoom-joystick">Zoom/Height</label> <div id="zoom-joystick" class="joystick-container"><div id="zoom-handle" class="joystick-handle"></div></div> </div>
    </div>
    <script src="/node_modules/@vcomm/fvv-player/dist/remote.js" type="module"> </script>
</body>
</html>

⚠️ Limitations and System Requirements

To ensure high performance and correct functionality, <fvv-player> has the following requirements:

Minimum Browser Requirements

The component relies on modern web technologies. Please ensure your users' browsers support them:

WebGL: Required. This is the core of the video rendering engine. Almost all modern desktop and mobile browsers support WebGL 1.0.
Web Components (Custom Elements & Shadow DOM): Required. Supported in all evergreen browsers (Chrome, Firefox, Safari, Edge). Polyfills may be required to support older browsers (e.g., IE11).
Fullscreen API: Highly recommended for the best user experience.
WebRTC or/and Websocket (for remote control): Necessary for the remote control functionality. Supported by all major browsers.

In general, the player will work in Chrome 67+, Firefox 63+, Safari 10.1+, Edge 79+.

Content Limitations

Video Synchronization: The source video files must be perfectly synchronized frame-by-frame. A desync of even 1-2 frames will result in noticeable stuttering when switching cameras. It is recommended to use professional synchronization methods (Genlock, Timecode) during recording.
Performance: The player decodes multiple video streams simultaneously (at least one, more may be needed for transitions). This places a significant load on the CPU/GPU. A modern and reasonably powerful device is required for smooth playback of high-resolution (4K) content.
CORS: When loading videos from a different domain than the one hosting the player, the server must be configured to send the correct CORS headers (Access-control-Allow-Origin: *).

💡 The Future

We plan to expand functionality by adding support for VR/AR and WebRTC for live streaming. Our next big step is to build a cloud platform for content hosting and sharing filmscripts.

🌟 How to Support

This project thrives on community enthusiasm. If you'd like to support our work and accelerate the development of the cloud infrastructure, please consider making a donation.

Support the project via PayPal: [email protected]