Get a livestream thumbnail

Learn how to retrieve thumbnails for a live stream

For live streams, we provide a single updating thumbnail URL - it will return the first frame of the most recent segment of video.

Create a stream

Follow our previous guide on creating a stream to get a stream key. A creator can then start a stream.

Fetch playback info

After <1 minute of the stream ingest starting, a thumbnail URL should be returned from the playback info API endpoint.

Example response:

{
  "type": "live",
  "meta": {
    "live": 0,
    "source": [
      {
        "hrn": "HLS (TS)",
        "type": "html5/application/vnd.apple.mpegurl",
        "url": "https://livepeercdn.studio/hls/{playbackId}/index.m3u8"
      },
      {
        "hrn": "WebRTC (H264)",
        "type": "html5/video/h264",
        "url": "https://livepeercdn.studio/webrtc/{playbackId}"
      },
      {
        "hrn": "Thumbnail (PNG)",
        "type": "image/png",
        "url": "https://recordings-cdn-s.lp-playback.studio/hls/{playbackId}/{ID}/source/latest.png"
      }
    ]
  }
}

You should see an entry in the source array with the type image/png. This URL will always return the latest thumbnail of your stream.

The thumbnail will always have a hrn of Thumbnail (PNG) and type of image/png.

This thumbnail is also used in the Player - it is automatically parsed in getSrc and passed as the video poster attribute, and updated every few seconds.

Examples

A common use for this feature is to show a live preview URL which constantly updates with the latest frame from the stream.

function PreviewComponent() {
  // Update to your thumbnail URL
  const thumbnailUrl =
    "https://recordings-cdn-s.lp-playback.studio/hls/61482gtjzi49cyvb/6cf39a0f-8b68-4ff8-8c7b-b105d6a6a9ed/source/latest.png";

  const [randomValue, setRandomValue] = useState(Date.now());

  // We will append a random value to the URL to force the browser to fetch the latest image (at least every 5 seconds)
  useEffect(() => {
    const interval = setInterval(() => {
      setRandomValue(Date.now()); // Update the randomValue every 5 seconds
    }, 5000);

    return () => clearInterval(interval); // Clean up the interval on unmount
  }, []);

  return <img src={`${thumbnailUrl}?refresh=${randomValue}`} />;
}