02-api.mdx

title	slug	sidebar_class_name	pagination_next	hide_title	displayed_sidebar
API	api	tabbed-page	guides/playback-a-video-stream	true	mySidebar

import Tabs from "./_tabs.mdx"; import CodeBlock from "@theme/CodeBlock"; import CodeBlockTabs from "@site/src/components/CodeBlockTabs"; import CodeBlockTabItem from "@site/src/components/CodeBlockTabItem";

:::note

The viewership API is still in development. Currently, viewer count metrics are only available for on demand assets. The count registers start views with deduping logic that prevents users from attempting to inflate view counts. In the future, we'll support additional viewership and engagement metrics so you can better understand popularity and performance.

Let us know if you have any particular feature requests related to metrics.

:::

Using Livepeer Player

Step 1: Register viewership metrics

To collect and register viewership metrics, you first need to configure your player. We recommend that you use the Livepeer player to get viewership metrics, as it comes fully configured. You can follow this guide to set it up.

Step 2: Get the asset.id of an existing asset

Get the asset.id of an existing asset. An asset.id can be found in the response object of any API call working with assets. If you haven't created an asset yet, you can follow the upload a video asset guide to do so.

Step 3: Retrieve viewership data

Once you have the asset.id, you can make a request to get the viewership data.

const response = await fetch(
  "https://livepeer.studio/api/data/views/{assetId}/total",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
  }
);

const { startViews } = (await response.json())[0]

curl --location --request GET https://livepeer.studio/api/data/views/{assetId}/total \
    -H "Authorization: Bearer $API_TOKEN"

Using Custom Player

Step 1: Register viewership metrics

We also support viewership metrics for applications using custom players. In order for metrics to be tracked by Livepeer, you will need to configure your player using addMediaMetrics.

Here's how to configure your player:

import { addMediaMetrics } from 'livepeer'

const source = 'https://livepeercdn.com/recordings/bd600224-d93a-4ddc-a6ac-2d71e3c36768/index.m3u8'
const video = document.getElementById('my-video')

// setup your player before calling addMediaMetrics

addMediaMetrics(video, source, (e) => console.error('Error adding metrics', e))

import { addMediaMetrics } from 'livepeer'
import React, { useEffect, useRef, useState } from 'react'

export default function VideoPlayer() {
  const videoRef = useRef(null)
  const [source, setSource] = useState(
    'https://livepeercdn.com/recordings/bd600224-d93a-4ddc-a6ac-2d71e3c36768/index.m3u8'
  )

  useEffect(() => {
    if (videoRef.current) {
      // set up other stuff in your player before calling addMediaMetrics
      const metrics = addMediaMetrics(videoRef.current, source, (e) =>
        console.error('Error adding metrics', e)
      )
      return metrics?.destroy
    }
  }, [videoRef, source])

  return (
    <video
      controls
      ref={videoRef}
      src={source}
      style={{ width: '100%', maxWidth: '500px' }}
    />
  )
}

Step 2: Get the asset.id of an existing asset

Get the asset.id of an existing asset. An asset.id can be found in the response object of any API call working with assets. If you haven't created an asset yet, you can follow the upload a video asset guide to do so.

Step 3: Retrieve viewership data

Once you have the asset.id, you can make a request to get the viewership data.

const response = await fetch(
  "https://livepeer.studio/api/data/views/{assetId}/total",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
  }
);

const { startViews } = (await response.json())[0]

curl --location --request GET https://livepeer.studio/api/data/views/{assetId}/total \
    -H "Authorization: Bearer $API_TOKEN"