SeekCalculator.java

Overview

`SeekCalculator` is a utility class designed to support dynamic seek interval calculations during media playback. Its primary role is to compute the appropriate seek jump length (in milliseconds) based on the duration for which the user has been seeking (e.g., holding fast-forward or rewind buttons) and the frequency of seek events. This adaptive behavior enables a smooth and intuitive seeking experience by progressively increasing seek intervals the longer the user continuously seeks, while also throttling seek updates to avoid overwhelming the playback engine.

This class is part of the media playback utilities and interacts primarily with user input handling components and playback controllers to determine how far the video should jump forward or backward during seeking operations.

Class: SeekCalculator

Package

package com.tubitv.media.utilities;

Constants

Fields

Methods

public static long getSeekRate(long startTime, long currentTime)

Calculates the current seek interval based on the total elapsed seek duration and enforces a maximum frequency of seek events.

• Parameters:

  • startTime - The timestamp (in milliseconds) when the seeking action started.

  • currentTime - The current timestamp (in milliseconds) at which the seek rate is requested.

• Returns:

  • A long representing the seek interval in milliseconds. It returns 0 if the request is too soon after the last seek update based on SEEK_FREQUENCY. Otherwise, it returns a positive interval indicating how far to jump.

• Usage:

  long seekRate = SeekCalculator.getSeekRate(seekStartTime, System.currentTimeMillis());
  if (seekRate > 0) {
      long newPosition = currentPosition + (seekRate * direction);
      player.seekTo(newPosition);
  }
  

• Description:

  • On the first call, initializes sLastUpdateTime with startTime.

  • If the time since the last update is less than SEEK_FREQUENCY (250 ms), returns 0 to throttle excessive seek commands.

  • Updates sLastUpdateTime and delegates to getCurrentSeekRate to determine the seek interval based on elapsed time.

private static long getCurrentSeekRate(long startTime, long currentTime)

Determines the seek interval based on the elapsed time since the seek started.

• Parameters:

  • startTime - The timestamp when seeking began.

  • currentTime - The current timestamp.

• Returns:

  • A positive long value indicating the seek jump interval (in milliseconds) based on elapsed time thresholds.

  • Returns 0 if elapsed time is less than FIRST_SPEED_INTERVAL (1 second).

• Implementation Details:

  • If elapsed time < 1 second → return 0 (no seek)

  • If 1s ≤ elapsed time < 2s → return 8,000 ms (short interval)

  • If 2s ≤ elapsed time < 6s → return 64,000 ms (regular interval)

  • If elapsed time ≥ 6s → return 256,000 ms (long interval)

Important Implementation Details

• The class throttles seek requests to at most 4 times per second to prevent flooding the playback engine with too many seek operations.

• Seek intervals increase progressively the longer the user continuously seeks, allowing finer control initially and faster skipping later.

• The seek interval returned is always positive; the caller applies the direction multiplier (FORWARD_DIRECTION or REWIND_DIRECTION) externally.

• The class maintains a static last update timestamp (sLastUpdateTime) to track frequency of seek events across the application lifecycle.

Interaction with Other Components

• User Input Handlers / UI Controllers:
  Components like UserController or UI elements handling seek gestures call getSeekRate() repeatedly during continuous user input (e.g., button hold or repeated presses).

• Playback Controllers / Player Logic:
  The computed seek intervals are used to calculate new playback positions and invoke the media player's seekTo() method accordingly.

• Device Adaptation Utilities:
  While SeekCalculator is device-agnostic, it complements utilities like PlayerDeviceUtils by ensuring consistent seek behavior regardless of hardware.

• Media Playback Models:
  Though not directly interacting with media models like MediaModel, the class supports smooth navigation across media timelines represented by those models.

Usage Example

long seekStartTime = System.currentTimeMillis();
int direction = SeekCalculator.FORWARD_DIRECTION; // or REWIND_DIRECTION

// Called repeatedly as user continues to seek
while(seeking) {
    long currentTime = System.currentTimeMillis();
    long seekInterval = SeekCalculator.getSeekRate(seekStartTime, currentTime);

    if (seekInterval > 0) {
        long newPosition = currentPlaybackPosition + (seekInterval * direction);
        player.seekTo(newPosition);
    }

    // Sleep or wait for next input event...
}

Mermaid Class Diagram

classDiagram
    class SeekCalculator {
        <<utility>>
        - static final int FORWARD_DIRECTION = 1
        - static final int REWIND_DIRECTION = -1
        - static final long FAST_SEEK_INTERVAL = 15000
        - static final long SEEK_INTERVAL_SHORT = 8000
        - static final long SEEK_INTERVAL_RERGUAR = 64000
        - static final long SEEK_INTERVAL_LONG = 256000
        - static final long FIRST_SPEED_INTERVAL = 1000
        - static final long SECOND_SPEED_INTERVAL = 2000
        - static final long THIRD_SPEED_INTERVAL = 6000
        - static final int SEEK_FREQUENCY = 250
        - static Long sLastUpdateTime
        + static long getSeekRate(long startTime, long currentTime)
        - static long getCurrentSeekRate(long startTime, long currentTime)
    }

Summary

`SeekCalculator` enables adaptive, frequency-controlled seek intervals that improve user experience during fast-forward and rewind operations in media playback. By escalating seek intervals over time and throttling update frequency, it balances responsiveness with smooth navigation, making it a crucial utility in the playback control subsystem.