Streamit Laravel - Documentation
Streamit Laravel

How Smart Seek Works?

1. Overview

Smart Seek adds hover and drag preview thumbnails to the video seek bar, providing the same familiar experience found on platforms such as Netflix and YouTube.

As viewers move along the progress bar, a preview image appears showing the scene at that point in the episode before they release the seek control.

This makes it easier to navigate through an episode without relying only on timestamps, which is particularly useful for short-drama content where viewers frequently skip ahead to find a specific scene.

2. Key Highlights

Instant Scene Preview

Viewers see a preview thumbnail while dragging or hovering over the progress bar instead of only seeing a timestamp.

Built for Vertical Video

Preview tiles are generated in portrait orientation by default, matching the 9:16 format commonly used by short-drama content.

Scales to Episode Length

The system automatically determines an appropriate number of preview frames based on the episode duration.

Short episodes receive enough frames for smooth navigation, while longer episodes are capped to avoid unnecessary processing.

Zero Impact on Initial Load Time

Preview images and timing data are fetched only when the viewer first interacts with the seek bar. They are not loaded during the initial player page load.

Independent of Playback Quality

Smart Seek operates separately from the main video playback system.

It does not affect:

  • Adaptive streaming
  • Video quality
  • Buffering
  • Playback performance
  • The main video engine

Retroactive Processing

Administrators can enable Smart Seek for an already-published episode and process only the preview data without re-encoding the original video.

Standards-Based Implementation

Smart Seek uses a sprite sheet + WebVTT approach, making the generated preview data lightweight, easy to inspect, and straightforward to extend.

3. How It Works

Smart Seek processing follows these steps:

Step 1: Trigger

After the episode’s video, audio, and subtitle processing is completed, Smart Seek generation runs as an additional processing step when the feature is enabled for the episode.

Step 2: Sample Frames

The server extracts still frames from the video at regular intervals.

The default interval is approximately 3 seconds, with adjustments for short clips and a maximum frame limit for very long episodes.

Step 3: Generate the Preview Sprite Sheet

The extracted frames are combined into a single sprite-sheet image instead of being stored and delivered as individual image files.

Step 4: Generate WebVTT Timing Data

A WebVTT file maps each point in the video timeline to the corresponding rectangular area of the sprite sheet.

This allows the player to determine which portion of the preview image should be displayed for a specific timestamp.

Step 5: Publish Preview Assets

The generated sprite sheet and WebVTT timing file are stored with the episode’s processed output and served alongside the video stream.

Step 6: Display the Preview

When a viewer first hovers over or drags the seek bar:

1. The browser loads the WebVTT timing data.

2. The player determines the appropriate preview frame.

3. The corresponding section of the sprite sheet is displayed.

4. The viewer sees the scene preview together with the current timestamp.

Because the frames are stored in a single sprite sheet, the player does not need to request a separate image for every preview point.

4. Setup & Usage

Smart Seek uses the same FFmpeg installation required by the Short Drama transcoding system.

No additional server-side software is required.

If FFmpeg is already configured correctly for transcoding, Smart Seek can be enabled without installing additional dependencies.

Enabling Smart Seek on an Episode

1. Go to Short Drama → Episodes → Create or edit an existing episode.

2. Under Processing Options, enable:Enable smart seek (timeline hover previews)

3. Save the episode.

  • For a new episode, Smart Seek runs as part of the normal processing workflow.
  • For an existing published episode, saving triggers lightweight preview processing without re-encoding the video.

4. Wait for processing to complete.

5. Open the episode’s watch page and move the cursor over or drag the seek bar.

6. Confirm that the preview thumbnail appears at different points on the timeline.

Viewer Experience

No additional action is required from viewers.

When Smart Seek is enabled for an episode:

  • Desktop users can hover over the progress bar.
  • Users can drag the progress bar to preview different scenes.
  • A preview thumbnail is displayed together with the corresponding timestamp.

5. Configuration Settings

Smart Seek provides optional .env configuration values.

The feature works with the default values if these settings are not customized.

Setting (.env key)DefaultDescription
SHORT_DRAMA_SMART_SEEK_INTERVAL3 secondsInterval between captured preview frames. Lower values create more granular previews but increase processing requirements.
SHORT_DRAMA_SMART_SEEK_MIN_FRAMES24Minimum number of preview frames generated, including for very short episodes.
SHORT_DRAMA_SMART_SEEK_MAX_FRAMES120Maximum number of preview frames generated to limit processing time for long episodes.
SHORT_DRAMA_SMART_SEEK_ORIENTATIONverticalPreview tile orientation. vertical is recommended for portrait short-drama content.
SHORT_DRAMA_SMART_SEEK_WIDTH108 pxWidth of each preview tile.
SHORT_DRAMA_SMART_SEEK_HEIGHT192 pxHeight of each preview tile. The default dimensions provide a 9:16 aspect ratio.
SHORT_DRAMA_SMART_SEEK_COLUMNS4Number of preview tiles placed in each row of the sprite sheet.
SHORT_DRAMA_SMART_SEEK_QUALITY4JPEG quality setting used when generating preview frames. Lower values provide higher quality with the configured FFmpeg behavior.
SHORT_DRAMA_SMART_SEEK_CLEANUP_FRAMEStrueRemoves individual sampled frames after they have been combined into the sprite sheet, retaining only the final preview assets.

6. Limitations & Notes

Per-Episode Configuration

Smart Seek must be enabled individually for each episode.

There is currently no global switch for automatically enabling Smart Seek across the entire catalog.

FFmpeg Dependency

Smart Seek depends on the same FFmpeg installation used by the Short Drama transcoding system.

If FFmpeg is not configured correctly, Smart Seek processing will fail in the same way as other FFmpeg-based processing tasks.

Previously Processed Episodes

Episodes processed before Smart Seek was enabled will not automatically contain preview assets.

However, Smart Seek can be enabled later and processed without re-encoding the original video.

Very Short Episodes

Very short episodes are subject to the configured minimum frame count.

As a result, preview frames may be generated closer together than the configured interval.

Additional Storage

The generated sprite sheet and WebVTT timing file add a small amount of storage per episode.

With the default configuration, the combined preview assets are typically well under 1 MB per episode, depending on the episode content and generated image data.

7. Processing Flow

8. Storage & Playback Behavior

Smart Seek generates two primary assets:

Sprite Sheet

Contains multiple preview frames arranged into a single image.

WebVTT File

Contains the timing information required to associate each video timestamp with a specific region of the sprite sheet.

During playback, these assets remain separate from the primary video stream.

Therefore, enabling Smart Seek does not modify the original video files or adaptive streaming playlists.

9. Performance Considerations

Smart Seek is designed to keep additional processing and playback overhead low.

During Processing

The system:

  • Extracts only the required number of preview frames.
  • Limits the total number of frames using the configured maximum.
  • Combines frames into a sprite sheet.
  • Removes temporary individual frames when cleanup is enabled.

During Playback

The system:

  • Does not load preview assets during the initial page load.
  • Loads the timing information when the viewer interacts with the seek bar.
  • Uses a single sprite sheet instead of requesting individual images for every timestamp.

This keeps Smart Seek independent from the main streaming and playback pipeline.

10. Troubleshooting

Preview Does Not Appear

Check the following:

1. Confirm that Enable smart seek is enabled for the episode.

2. Confirm that episode processing has completed successfully.

3. Verify that FFmpeg is configured correctly.

4. Check whether the Smart Seek processing job completed successfully.

5. Clear the browser cache and reload the watch page.

6. Verify that the generated WebVTT and sprite-sheet assets exist in the episode’s processed output.

Processing Fails

If Smart Seek processing fails:

1. Check the application logs.

2. Verify FFmpeg availability.

3. Verify that the processed video file exists and is readable.

4. Check storage permissions.

5. Verify available disk space.

6. Confirm that the configured Smart Seek values are valid.

Video Playback Is Unaffected

A Smart Seek processing failure does not require re-encoding the original video.

Smart Seek is an additional preview feature and operates independently of the primary video playback pipeline.

11. Conclusion

Smart Seek provides a platform-grade scrubbing experience for Short Drama episodes by displaying visual scene previews while viewers navigate the timeline.

It:

  • Uses the existing FFmpeg infrastructure.
  • Supports portrait 9:16 preview tiles.
  • Generates lightweight sprite-sheet preview assets.
  • Uses WebVTT for timeline mapping.
  • Loads preview data only when required.
  • Does not affect adaptive streaming or playback quality.
  • Can be enabled retroactively for existing episodes.
  • Requires no additional server software.

Smart Seek can therefore be enabled across the catalog without modifying or re-encoding the original video content, while giving viewers a significantly more intuitive way to navigate through episodes.