Seek Calculation

Purpose

This subtopic addresses the need for a smooth and intuitive fast-forward and rewind experience during media playback. When users engage in seeking—either by pressing fast forward or rewind controls repeatedly or holding them down—the system must determine how far to jump in the video timeline at each seek event. The seek calculation logic dynamically adjusts the seek interval based on how long the seeking action has been active, improving user control and responsiveness beyond fixed step sizes.

Functionality

The seek calculation mechanism computes the appropriate seek interval (in milliseconds) to apply on each seek command. It considers two main factors:

• Elapsed Time Since Seek Start: The longer the user continuously performs seek actions, the larger the interval for jumps becomes. This allows small jumps initially for fine control, and progressively larger jumps for faster navigation through longer videos.

• Seek Frequency: To avoid overwhelming the player with excessive seek commands, seek rates are throttled to a maximum frequency (e.g., 4 seeks per second).

Key Workflow

1. Seek Start: When seeking begins, the system notes the start timestamp.

2. Seek Rate Requests: On each subsequent seek event (e.g., button press or repeated input), the system:

   • Checks if enough time has passed since the last seek update (enforcing the seek frequency).

   • Calculates the elapsed time since the seek started.

   • Determines the seek interval based on predefined timing thresholds.

3. Seek Interval Output: Returns the interval (in milliseconds) to jump forward or backward.

Seek Rate Thresholds

• Initial Phase (0 to 1 second): No automatic seek to prevent sudden jumps.

• Short Interval (1 to 2 seconds): Small jumps of 8 seconds to allow precise navigation.

• Regular Interval (2 to 6 seconds): Medium jumps of 64 seconds for faster scrubbing.

• Long Interval (6+ seconds): Large jumps of 256 seconds for rapid skipping.

The direction (forward or rewind) modifies the sign of the jump externally; the [SeekCalculator](/projects/288/68383) provides positive intervals.

Code Illustration

// Returns seek interval based on seeking duration and throttling frequency
public static long getSeekRate(final long startTime, final long currentTime) {
    if (sLastUpdateTime == null) {
        sLastUpdateTime = startTime;
    }
    long intervalSinceLastUpdate = currentTime - sLastUpdateTime;
    if (intervalSinceLastUpdate < SEEK_FREQUENCY) {
        return 0; // Skip if called too frequently
    }
    sLastUpdateTime = currentTime;
    return getCurrentSeekRate(startTime, currentTime);
}

This snippet ensures seek commands are not processed more than 4 times per second and delegates to interval-based logic to determine the actual seek interval.

Relationship

Seek Calculation enhances the **Media Playback and UI Controls** subtopic by providing a refined user interaction model for seeking operations. While the parent topic defines foundational playback models and utilities, and other subtopics manage playback states and UI elements, this calculation logic uniquely focuses on the temporal dynamics of seeking inputs.

• It integrates with UserController or UI components such as PlayerControllerUI where seek commands are received.

• Playback controllers use the intervals computed here to adjust the player’s current playback position smoothly.

• Unlike static seek implementations, this dynamic approach improves user experience by adapting to the user's seek behavior over time.

• It complements the Device Playback Utils by providing consistent seek behavior regardless of device type or playback mode.

Diagram

flowchart TB
    A[User Starts Seeking] --> B[Record Seek Start Time]
    B --> C{Seek Event Received?}
    C -->|No| B
    C -->|Yes| D[Check Time Since Last Seek Update]
    D -->|Too Soon| E[Return 0 (No Seek)]
    D -->|Allowed| F[Calculate Elapsed Time Since Start]
    F --> G{Elapsed Time Range}
    G -->|< 1s| E
    G -->|1s - 2s| H[Return 8s Seek Interval]
    G -->|2s - 6s| I[Return 64s Seek Interval]
    G -->|> 6s| J[Return 256s Seek Interval]
    E --> K[Apply Seek Interval with Direction]
    H --> K
    I --> K
    J --> K
    K --> C

This flowchart illustrates how the seek interval adapts dynamically based on continuous user seek input timing, enforcing frequency limits and progressively increasing jump lengths.

This adaptive seek calculation provides a user-friendly and responsive fast-forward and rewind experience critical for efficient media navigation within the broader media playback system.