Custom Video Player Setup

Use this guide to add collaboration into your own custom video player.

Setup

Step 1: Set up Velt Components in your app

You will be using the following components:

• Velt Comments: Renders comments on the DOM.
• Velt Comment Tool: Enables or disables adding comments.
• Velt Reaction Tool: Enables or disables adding reactions.
• Velt Comment Player Timeline: Adds comments bubble over your player seek bar.
• Velt Comments Sidebar: Adds a sidebar that shows all comments. Users can also search, filter & navigate to the comments from here.
• Velt Sidebar Button: Toggles the sidebar on/off.

A) Add the Velt Comments component in the root of your app

Add the Velt Comments component to the root of your app.

React / Next.js

<VeltComments />

B) Add the Velt Comment Tool component wherever you want your render the comment tool.

Note you can also provide your own button to this component.

React / Next.js

<VeltCommentTool>
  <button>
    {/* your custom button (optional) */}
  </button>
</VeltCommentTool>

Disable Comment Tool You can disable the comment tool to temporarily or conditionally restrict comment creation while still allowing users to view existing comments.

See Example

React / Next.js

<VeltCommentTool disabled={true}>
  <button>
    {/* your custom button (optional) */}
  </button>
</VeltCommentTool>

C) Add the Velt Reaction Tool component wherever you want your render the reaction tool.

• Provide the video player ID on which you want the reactions to be added.
• Add an event handler to handle onReactionToolClick events.

React / Next.js

<VeltReactionTool videoPlayerId={videoPlayerId}
  onReactionToolClick={() => onReactionToolClick()}>
</VeltReactionTool>

D) Place the Velt Comment Player Timeline component as a sibling to your video player.

• To show comment bubbles on your player seek bar, add the Velt Comment Player Timeline component as a sibling to your video player component.
• It will auto adjust to the same width as your video player.

Right now we assume you have a maximum of one velt comment player timeline component and one sibling video player component per documentID

Ensure that the parent container of velt comment player timeline doesnt have CSS position value as ‘static’.

videoPlayerId is optional and helps support multiple players/timelines on the same page.

• If omitted, the timeline shows all comments for the current document (for the active version).
• If provided, the timeline shows only comments whose location.videoPlayerId matches the given videoPlayerId.

Tip: Use the same id on your player element and when setting location.videoPlayerId so the timeline can correctly associate comments with the player.

React / Next.js

<div>
  <YourVideoPlayer id="videoPlayerId"/>
  <VeltCommentPlayerTimeline videoPlayerId="videoPlayerId"/>
</div>

E) Add id to the video player or its parent element.

• If you don’t have access to the raw <video> player, you can add an id to the parent element of the video player.

React / Next.js

<div id="videoPlayerId">
  <YourVideoPlayer />
  <VeltCommentPlayerTimeline videoPlayerId="videoPlayerId"/>
</div>

F) Add the Velt Comments Sidebar component.

The Comments Sidebar displays all comments with search, filter, and navigation capabilities.

React / Next.js

<VeltCommentsSidebar />

Optional Properties:

• embedMode: Embed the sidebar in your existing component instead of floating mode

See Example

React / Next.js

{/* With optional properties */}
<VeltCommentsSidebar 
  embedMode={true} 
/>

G) Add the Velt Sidebar Button component.

This will open or close the Comment Sidebar.

React / Next.js

<VeltSidebarButton>
</VeltSidebarButton>

Step 2: Set the total media length on the Velt Comment Player Timeline

You can pass an integer to total media length using props to represent the total number of frames or seconds in the video:

React / Next.js

<VeltCommentPlayerTimeline videoPlayerId="videoPlayerId" totalMediaLength={120} />

Alternatively, you can set this using API method call. This is useful if you first need to grab the total frames from another method before setting it.

React / Next.js

const commentElement = client.getCommentElement();
commentElement.setTotalMediaLength(120);

Step 3: Detect Comment Tool Activation and Set Media Location

• Detect when the user activates the comment tool by adding an event handler to the onCommentModeChange event.
• Pause your player and set a new Location in the Velt SDK.
• This ensures that the comments are tied to that particular media frame or timestamp.
• You can pass in a key value pair object that represents the current state of your player.
• If you are using the Velt Comment Player Timeline component, ensure to set the current media frame or second in the special key currentMediaPosition.
• Use the same id in location.videoPlayerId that you used in VeltCommentPlayerTimeline.
  currentMediaPosition is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot

React / Next.js

<VeltCommentTool onCommentModeChange={(mode) => onCommentModeChange(mode)} />

const onCommentModeChange = (mode) => {
    // mode will be `true` if the user has activated the comment tool
    // If the comment tool is active, pause the player and set the "location".
    if (mode) {
        // pause player
        setLocation()
    }
});

const setLocation = async (client) => {
    
    // set currentMediaPosition property on a Location object to represent the current frame
    let location = {
      currentMediaPosition : 120,
      videoPlayerId : "videoPlayerId"
    }
    //set the Location using the client
    await client.setLocations([location])
    
}

Step 4: Detect Reaction Tool Activation and Set Media Location

• Detect when the user activates the reaction tool by adding an event handler to the onReactionToolClick event.
• Pause your player and set a new Location in the Velt SDK.
• This ensures that the reactions are tied to that particular media frame or timestamp.
• You can pass in a key value pair object that represents the current state of your player. If you are using the Velt Comment Player Timeline component, ensure to set the current rounded frame or second in the special key currentMediaPosition.
  currentMediaPosition is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot

React / Next.js

<VeltReactionTool videoPlayerId={videoPlayerId}
  onReactionToolClick={() => onReactionToolClick()}>
</VeltReactionTool>

const onReactionToolClick = () => {
    // pause player
    setLocation()
});

const setLocation = async () => {
    // set currentMediaPosition property on a Location object to represent the current frame
    let location = {
      currentMediaPosition : 120,
      videoPlayerId : "videoPlayerId"
    }
    //set the Location using the client
    await client.setLocations([location])
    
}

Step 5: Remove Velt Location when the player is played

Call unsetLocationsIds() so the video player can play without comments appearing in frames.

React / Next.js

const clearLocation = async () => {
    // Unset all locations, so the video player can play without comments appearing in frames
    await client.unsetLocationsIds()
}

Step 6: Navigate to the comment’s location in the player from the Sidebar or Timeline

Add the onCommentClick event handler on the Velt Comments Sidebar & Velt Comment Player Timeline components you added earlier. The event will give you back the location object that you had set on the comment.

Use this object to:

• update your player state
• update the SDK’s location so the comments associated with that location are rendered.

A) Handle click on the Velt Comments Sidebar

React / Next.js

<VeltCommentsSidebar embedMode={true} onCommentClick={(event) => onCommentClick(event)} />

const onCommentClick = async (event) => {
    if (event) {
      // Get the location object from the event.
      const { location } = event;
      if (location) {
          // Get the media position where the comment was added.
          const { currentMediaPosition } = location;
          if (currentMediaPosition) {
              // Pause the player.

              // Seek to the given comment media position.

              // Set the Velt Location to the clicked comment location.
              await client.setLocations([location]);
          }
      }
  }
}

B) Handle click on the Velt Comment Player Timeline

React / Next.js

<VeltCommentPlayerTimeline videoPlayerId="videoPlayerId" onCommentClick={(event) => onTimelineCommentClick(event)} />

const onTimelineCommentClick = async (event) => {
  if (event) {
      // Get the location object from the event.
      const { location } = event;
      if (location) {
          // Get the media position where the comment was added.
          const { currentMediaPosition } = location;
          if (currentMediaPosition) {
              // Pause the player.

              // Seek to the given comment media position.

              // Set the Velt Location to the clicked comment location.
              await client.setLocations([location]);
          }
      }
  }
}

The clicked Comment data will be in the following format:

property	type	description
documentId	string	The document ID where the comment was added
location	object	The location where the comment was added
targetElementId	string	The DOM ID of the target element on which the comment was added
context	Object	Any context data passed when the comment was added