Login

Add timeline hovers using spritesheet

Adding timeline hovers using spritesheets allows developers to display key video frames on hover, enhancing user interaction by providing a visual preview of the video timeline. FastPix makes this process efficient by enabling developers to easily generate spritesheets with precise metadata that can be leveraged to create interactive video hovers.


Understanding timeline hover in video

This feature is commonly used on streaming platforms, video-sharing sites, and social media to help users quickly identify sections they are interested in watching.

When users hover over different points on the video timeline, thumbnail images from specific frames are displayed, giving them a quick visual cue of the video’s content at that time.


Timeline hover previews can improve your user engagement by:

  • Reducing skip time: Users can quickly preview a section, reducing random skipping and enhancing overall watch time.
  • Improving content discovery: For longer videos, users can discover key sections without playing the entire video, making it easier to access relevant content.
  • Encouraging interactive experiences: Timeline previews make the video interaction feel seamless and user-friendly, often leading to better engagement metrics.

FastPix lets you implament timeline hover previews by providing an API that generates spritesheets—single image files containing multiple frames from a video. These frames are organized in a grid-like format, enabling fast and efficient access to individual video thumbnails.


What is a spritesheet?

A spritesheet is a powerful tool in video playback and gaming applications, designed to store multiple frames or images within a single file. In the context of video hover previews, spritesheets consolidate key frames from a video, making it easy to display any frame from the timeline with minimal server requests.

Using spritesheets for timeline hovers offers several advantages. Rather than loading multiple image files, spritesheets groups frames into a single file, which saves bandwidth and reduces server load. This streamlined approach also enables faster loading times, as an entire set of frames can be accessed with a single HTTP request, which significantly enhances the speed of hover previews. Additionally, spritesheets provide consistent frame quality across previews, since each frame is predefined and encoded within the same file, maintaining uniform visual quality and creating a seamless user experience.



Spritesheet structure and metadata

Spritesheets used for timeline hovers are typically organized into a grid, with rows and columns representing different frames. FastPix provides additional metadata, such as x-axis and y-axis coordinates for each frame, allowing precise positioning and easy access to individual frames within the spritesheet.

In addition, FastPix offers metadata in both WebVTT (Web Video Text Tracks) and JSON formats, which helps to retrieve and display frames according to hover position along the video timeline.


This metadata includes:

  • Timecodes for frames: Each frame is assigned a timecode, so you know exactly which part of the video each frame represents.
  • Coordinates for frame positioning: The x and y coordinates of each frame within the spritesheet help position it accurately on the hover interface.

By combining spritesheets with metadata, FastPix enables developers to create smooth, responsive timeline hovers that enhance the user's ability to navigate video content.


Generating spritesheets with FastPix


Step 1: Upload your video

Start by uploading your video to the FastPix platform to prepare it for on-demand viewing and spritesheet generation. Here’s how:

  • Create an on-demand video: Use the FastPix API to upload your video. The API supports uploads from various sources, including direct uploads from client devices or servers.
  • Check media status: Once the upload is complete, the video will be processed. Wait for the media status to update to "ready" before proceeding. This ensures that the video is fully processed and prepared for playback and other operations.

📘

Documentation references

For quick start, check out FastPix's setup guide here


Step 2: Requesting the spritesheet

To get a spritesheet for your video, send an HTTP request to FastPix using your video's unique playback ID. This request will return a spritesheet image in the specified format, providing visual snapshots of the video at set intervals.

Use the following URL format to request a spritesheet:

https://image.fastpix.io/{PLAYBACK_ID}/spritesheet.{png|jpg|webp}


Output Formats:

  • PNG: Ideal for high-quality images with transparency.
  • JPG: Suitable for images where file size is a concern.
  • WEBP: Offers superior compression and quality, ideal for web applications.

📘

PLEASE NOTE

FastPix automatically adjusts the number of tiles based on video length:

  • Video under 15 minutes produce a spritesheet with 50 tiles
  • Video over 15 minutes generate a spritesheet with with 100 titles.

Step 3: Spritesheet metadata and tile structure

Each spritesheet comes with metadata that contains detailed coordinates for each frame, allowing for accurate positioning of images on a timeline. This metadata is essential for creating an interactive hover effect.

A metadata file accompanies each spritesheet and can be used as a text track for video timelines. This file contains each tile’s x and y coordinates and the associated time range within the video. Additionally, the metadata is available in both JSON and WebVTT formats for easy integration.


WebVTT metadata example


Request typeGET
Request URLhttps://images.fastpix.io/{PLAYBACK_ID}/spritesheet.{vtt/json}
OperationGet spritesheet metadata from a video

Path parameters

Parameter nameMandatoryData typeDescription
PLAYBACK_IDYESStringPlayback_id of the media

Query parameters

ParametersTypeDescription
FormatstringBy default the image format in json and vtt request will be jpg. You can also change it to png or webp by changing the URL to ?format=png

Example request:

GET https://images.fastpix.io/{PLAYBACK_ID}/spritesheet.vtt?format=jpg


Here’s the output of the request below:

00:00:00.000 --> 00:00:00.200 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=0,0,256,160 
 
00:00:00.200 --> 00:00:00.400 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=256,0,256,160 
 
00:00:00.400 --> 00:00:00.600 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=512,0,256,160 
 
00:00:00.600 --> 00:00:00.800 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=768,0,256,160 
 
00:00:00.800 --> 00:00:01.000 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=1024,0,256,160 
 
00:00:01.000 --> 00:00:01.200 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=0,160,256,160 
 
00:00:01.200 --> 00:00:01.400 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=256,160,256,160 
 
00:00:01.400 --> 00:00:01.600 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=512,160,256,160 
 
00:00:01.600 --> 00:00:01.800 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=768,160,256,160 
 
00:00:01.800 --> 00:00:02.000 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=1024,160,256,160 
 
00:00:02.000 --> 00:00:02.200 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=0,320,256,160 
 
00:00:02.200 --> 00:00:02.400 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=256,320,256,160 
 
00:00:02.400 --> 00:00:02.600 
https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg#xywh=512,320,256,160 

……. 

JSON metadata example



Request typeGET
Request URLhttps://image.fastpix.io/{PLAYBACK_ID}/spritesheet.{json}
OperationGet spritesheet metadata from a video

Path parameters

Parameter nameMandatoryData TypeDescription
PLAYBACK_IDYESStringPlayback_id of the media

Query parameters

ParametersTypeDescription
formatstringBy default the image format in json and vtt request will be jpg. You can also change it to png or webp by changing the URL to ?format=png

Example request:

GET https://images.fastpix.io/{PLAYBACK_ID}/spritesheet.json?format=png


Here’s the output of the request below:

{ 
  "url": "https://images.fastpix.io/494b254f-e444-4f41-bb19-400770fc9b0d/spritesheet.jpg", 
  "tile_width": 256, 
  "tile_height": 160, 
  "duration": 10.0, 
  "tiles": [ 

    { "start": 0.0, "x": 0, "y": 0 }, 
    { "start": 0.20000000298023224, "x": 256, "y": 0 }, 
    { "start": 0.4000000059604645, "x": 512, "y": 0 }, 
    { "start": 0.6000000238418579, "x": 768, "y": 0 }, 
    { "start": 0.800000011920929, "x": 1024, "y": 0 }, 
    { "start": 1.0, "x": 0, "y": 160 }, 
    { "start": 1.2000000476837158, "x": 256, "y": 160 }, 
    { "start": 1.4000000953674316, "x": 512, "y": 160 }, 
    { "start": 1.6000001430511475, "x": 768, "y": 160 }, 
    { "start": 1.8000001907348633, "x": 1024, "y": 160 }, 
    { "start": 2.000000238418579, "x": 0, "y": 320 }, 
    { "start": 2.200000286102295, "x": 256, "y": 320 }, 
    { "start": 2.4000003337860107, "x": 512, "y": 320 }, 
    { "start": 2.6000003814697266, "x": 768, "y": 320 }, 
    { "start": 2.8000004291534424, "x": 1024, "y": 320 }, 
    { "start": 3.000000476837158, "x": 0, "y": 480 }, 
    { "start": 3.200000524520874, "x": 256, "y": 480 }, 
    { "start": 3.40000057220459, "x": 512, "y": 480 }, 
    { "start": 3.6000006198883057, "x": 768, "y": 480 }, 
    { "start": 3.8000006675720215, "x": 1024, "y": 480 }, 
    { "start": 4.000000476837158, "x": 0, "y": 640 }, 
    { "start": 4.200000286102295, "x": 256, "y": 640 }, 
  
  ] 
} 

Each tile object specifies the frame’s start time in the video and its x/y coordinates within the spritesheet. This format makes it easy to retrieve frames for timeline hovers by referencing the time intervals and coordinates.