Preview on Hover

The preview on hover feature transforms the timeline scrubber into an intuitive navigation tool by displaying video frames as you move your cursor along the progress bar. This visual preview helps users identify and jump to specific moments in the video without the trial-and-error process of traditional seeking.

Understanding Timeline Preview

Timeline preview solves a fundamental navigation challenge in video players: finding specific moments when you only know what they look like, not when they occur. Traditional scrubbing requires repeatedly clicking, watching, and adjusting until you find the right frame. Timeline preview eliminates this inefficiency by showing you exactly what's at each position before you click.

The feature works by detecting when your cursor hovers over the progress bar. As you move along the timeline, the player dynamically loads and displays the corresponding video frame in a small popup above your cursor. This instant visual feedback allows you to identify specific scenes, moments, or content sections at a glance.

Technical Implementation: For HLS streams, the player intelligently uses the lowest quality variant to generate previews. This optimization ensures fast loading times and minimal bandwidth consumption while maintaining enough visual clarity for identification purposes. The lower quality is imperceptible in the small preview window but significantly improves performance, especially on slower connections or mobile networks.

Enabling and Disabling Preview

The preview on hover feature is enabled by default, providing enhanced navigation out of the box. You can control this behavior through the enablePreviewOnHover prop.

Default Configuration

When no explicit configuration is provided, preview on hover is automatically enabled:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function VideoPlayer() {
  return (
    <CustomVideoPlayer
      src="https://example.com/video.m3u8"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      // enablePreviewOnHover is true by default
    />
  );
}

This configuration provides timeline preview functionality without any additional setup. Users can immediately benefit from visual navigation as soon as they hover over the progress bar.

Explicit Enabling

You can explicitly enable the feature to make your intentions clear in the code:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function VideoPlayer() {
  return (
    <CustomVideoPlayer
      src="https://example.com/video.m3u8"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      enablePreviewOnHover={true}
    />
  );
}

Explicit enabling doesn't change the behavior but improves code readability, especially in teams where configuration decisions should be obvious from the code.

Disabling Preview

Disable the preview feature when it's not appropriate for your use case:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function VideoPlayer() {
  return (
    <CustomVideoPlayer
      src="https://example.com/video.mp4"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      enablePreviewOnHover={false}
    />
  );
}

This configuration disables the preview functionality entirely. Hovering over the progress bar will not trigger frame loading or display preview thumbnails.

How Preview Works with Different Video Formats

The preview feature's behavior and performance vary depending on the video format you're using.

HLS Streaming Preview

HLS streams provide the ideal foundation for timeline preview functionality. The segmented nature of HLS allows the player to load specific portions of the video without downloading the entire file.

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function HLSVideoPlayer() {
  return (
    <CustomVideoPlayer
      src="https://example.com/video/master.m3u8"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      type="hls"
      enablePreviewOnHover={true}
    />
  );
}

For HLS streams, the preview system automatically selects the lowest available quality variant. This intelligent selection balances preview clarity with loading performance. A 720p or 1080p stream might use 240p or 360p for previews, reducing bandwidth requirements by 70-90% while maintaining recognizable visual content.

Performance Benefits: HLS preview loading is nearly instantaneous because the player only requests small segment files rather than seeking through a large monolithic video file. The segment-based architecture naturally aligns with the preview feature's needs.

Quality Selection: The player scans available quality levels in the HLS manifest and automatically chooses the lowest resolution. This happens transparently without requiring any configuration. If your HLS stream only has one quality level, that level is used for previews.

Standard Video Format Preview

Standard formats like MP4, WebM, and OGG handle preview differently due to their monolithic file structure.

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function MP4VideoPlayer() {
  return (
    <CustomVideoPlayer
      src="https://example.com/video.mp4"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      type="mp4"
      enablePreviewOnHover={false} // Recommended for MP4
    />
  );
}

For MP4 and similar formats, generating previews requires seeking to specific positions in a single large file. This process is less efficient than HLS's segment-based approach. The browser must download and decode portions of the file to extract frames, which can cause delays or stuttering, particularly with large files or slower connections.

Stability Considerations: Note that preview is "not stable in mp4 like formats." This refers to potential performance issues rather than broken functionality. The feature works but may exhibit lag, frame loading delays, or increased bandwidth consumption with MP4 files. For production applications with MP4 content, consider disabling preview to ensure smooth user experience.

User Experience Considerations

Implementing preview on hover effectively requires understanding how users interact with the feature and what makes their experience smooth and intuitive.

Visual Clarity

The preview thumbnail displays actual video frames at the hover position, providing instant visual context. The thumbnail size is optimized for recognizability without obscuring other interface elements or feeling too small to be useful.

Preview Display Behavior:
- Cursor enters progress bar → Preview appears after brief delay
- Cursor moves along timeline → Preview updates continuously
- Cursor exits progress bar → Preview fades out smoothly

The preview follows your cursor as you scrub along the timeline, updating in near real-time to show the corresponding frame. This creates an intuitive connection between cursor position and video content.

Positioning Logic: The preview popup appears above the progress bar, centered on your cursor position. Near the edges of the player, the preview automatically adjusts to remain fully visible rather than extending beyond the player boundaries. This edge detection ensures previews remain accessible regardless of where you hover.

Loading Behavior

The first time you hover over a specific section of the timeline, there may be a brief delay as the player loads the corresponding video segment or frame. Subsequent hovers over the same area display instantly because the frame is cached.

Loading Sequence:
1. Hover at 1:30 → Brief loading, frame displays
2. Move to 2:00 → Brief loading, new frame displays
3. Return to 1:30 → Instant display (cached)

This caching behavior improves the experience when users hover back and forth over the same sections while searching for specific content. The player maintains a frame cache for recently previewed positions, significantly reducing redundant loading.

Network Efficiency: The player intelligently manages preview loading to minimize bandwidth usage. It only loads frames when you pause your cursor movement or slow down significantly, avoiding wasteful loading of frames you're quickly scrubbing past. This smart loading prevents bandwidth saturation while maintaining responsiveness.

Interaction Patterns

Users interact with timeline preview in several distinct patterns, each serving different navigation needs.

Exploratory Scrubbing: Slowly moving the cursor along the timeline to survey content. Users employ this pattern when they're uncertain about video structure or looking for a specific scene they'll recognize visually.

Target Seeking: Quickly moving to a known approximate position, then fine-tuning with preview. This pattern emerges when users know roughly when something occurs but need visual confirmation to pinpoint the exact moment.

Section Verification: Hovering briefly over specific points to confirm content. Users employ this when they've used timeline markers or memory to navigate and want quick visual confirmation before clicking.

Understanding these patterns helps you decide whether preview on hover suits your use case. Educational content, tutorials, and narrative videos benefit strongly from preview. Audio-focused content, podcasts with video components, or simple presentations may not justify the feature's overhead.

Conditional Preview Configuration

Some applications need to enable or disable preview based on dynamic conditions like video format, user preferences, or device capabilities.

Format-Based Configuration

Automatically enable or disable preview based on the detected video format:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function AdaptiveVideoPlayer({ videoUrl }) {
  // Detect if the video is HLS format
  const isHLS = videoUrl.endsWith(".m3u8");

  return (
    <CustomVideoPlayer
      src={videoUrl}
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      type={isHLS ? "hls" : "mp4"}
      enablePreviewOnHover={isHLS} // Only enable for HLS
    />
  );
}

This implementation provides preview functionality only when it will perform optimally, automatically disabling it for formats where performance might be suboptimal.

User Preference Control

Allow users to toggle preview based on their preferences:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";
import { useState } from "react";

function UserControlledPlayer() {
  const [previewEnabled, setPreviewEnabled] = useState(true);

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={previewEnabled}
          onChange={(e) => setPreviewEnabled(e.target.checked)}
        />
        Enable timeline preview
      </label>

      <CustomVideoPlayer
        src="https://example.com/video.m3u8"
        poster="https://example.com/poster.jpg"
        icons={playerIcons}
        enablePreviewOnHover={previewEnabled}
      />
    </div>
  );
}

This pattern respects user preferences and allows users to disable preview if they find it distracting or if they're on a limited bandwidth connection.

Device-Based Configuration

Disable preview on devices where it might impact performance or isn't necessary:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";
import { useState, useEffect } from "react";

function ResponsiveVideoPlayer() {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const checkMobile = () => {
      setIsMobile(window.innerWidth < 768);
    };

    checkMobile();
    window.addEventListener("resize", checkMobile);
    return () => window.removeEventListener("resize", checkMobile);
  }, []);

  return (
    <CustomVideoPlayer
      src="https://example.com/video.m3u8"
      poster="https://example.com/poster.jpg"
      icons={playerIcons}
      enablePreviewOnHover={!isMobile} // Disable on mobile
    />
  );
}

Mobile devices often have limited bandwidth and smaller screens where preview thumbnails are less useful. This configuration optimizes the experience for each device type.

Troubleshooting Preview Issues

If timeline preview isn't working as expected, check these common issues and solutions.

Preview Not Appearing

If hovering over the timeline doesn't show any preview:

Verify Preview is Enabled: Check that enablePreviewOnHover is either not set or explicitly set to true. If set to false, preview is disabled and won't function.

Check Video Format: Ensure you're using a compatible video format. HLS provides the best experience. If using MP4, preview may be slow or unstable.

Confirm Video Loading: Preview requires the video to be at least partially loaded. If the video hasn't begun loading or is encountering errors, preview won't function. Check browser console for loading errors.

Browser Compatibility: Timeline preview requires modern browser features. Ensure you're using a recent version of Chrome, Firefox, Safari, or Edge. Very old browsers may not support the necessary APIs.

Slow or Laggy Preview

If preview displays but feels slow or stuttery:

Check Format: MP4 and similar formats naturally have slower preview loading than HLS. Consider converting to HLS for better performance.

Verify Network Speed: Slow network connections delay frame loading. Use browser developer tools to monitor network activity and identify bandwidth bottlenecks.

Inspect Video Size: Extremely large video files take longer to seek and extract frames. Consider optimizing video files or using more aggressive compression.

Device Performance: Older devices or those with limited resources may struggle with real-time frame extraction. This is expected behavior rather than a bug.

Preview Quality Issues

If preview thumbnails appear blurry or pixelated beyond usability:

HLS Quality Selection: For HLS streams, the player automatically uses the lowest quality variant. If your stream's lowest quality is very low, previews will reflect that. Ensure your HLS encoding includes a reasonable minimum quality level like 240p or 360p.

Format Limitations: MP4 preview quality depends on browser decoding capabilities and may vary across devices. This is a limitation of the format rather than the player.

Display Scaling: On high-DPI displays, preview thumbnails may appear slightly soft due to scaling. This is normal and doesn't typically impact usability.

Integration with Other Features

Timeline preview works seamlessly with other player features, creating a cohesive navigation experience.

Preview and Keyboard Navigation

Keyboard shortcuts and preview complement each other perfectly. Use keyboard controls for precise seeking, then verify position with preview:

Combined Navigation Workflow:
1. Press J to jump backward 10 seconds
2. Hover over timeline to visually verify position
3. Press arrow keys to fine-tune if needed
4. Hover to confirm final position
5. Click to seek, or press Space to play

This workflow combines the speed of keyboard navigation with the visual confirmation of timeline preview, creating the most efficient navigation experience.

Preview and Captions

Timeline preview displays video frames without caption overlays, showing the pure visual content. This clean preview helps you identify scenes based on visual elements rather than dialogue, which is often more effective for spatial or action-based content.

Preview and Custom Themes

Timeline preview automatically adapts to your custom theme. The preview thumbnail border, shadow, and positioning inherit styling from your theme configuration, ensuring visual consistency throughout the player interface.

Best Practices

Follow these guidelines to implement timeline preview effectively in your applications.

Enable for HLS, Disable for MP4: The performance difference is significant. HLS provides smooth, instant previews while MP4 can feel sluggish. Match the feature to the format for optimal experience.

Consider User Context: Preview is most valuable for long-form content, educational videos, and narrative content where visual identification of scenes matters. For short clips, podcasts, or audio-focused content, the feature adds overhead without significant benefit.

Provide User Control: In applications with varied content types, let users toggle preview based on their current needs. Some viewing sessions benefit from preview while others don't.

Test on Target Devices: Preview performance varies significantly across devices. Test on your target hardware to ensure acceptable performance before deploying.

Monitor Bandwidth Usage: In bandwidth-sensitive contexts, preview adds to overall data consumption. Consider disabling it in applications where bandwidth conservation is critical.

Next Steps

With timeline preview configured, explore these related features:

Keyboard Shortcuts: Learn how keyboard navigation combines with visual preview for efficient content navigation.

Theming: Discover how preview styling integrates with custom themes to maintain visual consistency.

Props: Review all configuration options to understand how preview fits into the broader player configuration.

Timeline preview represents a significant enhancement to video navigation, transforming the timeline from a simple position indicator into an intuitive visual browsing tool. When used appropriately with HLS content, it dramatically improves the user's ability to find and navigate to specific moments in video content.