Architecture Design and Engineering Practices for Cross-Device Video Resumption

1. Background and Problem Definition

In a typical video platform feature list, you will usually find account login, HD playback, multi-device playback history synchronization, favorites, and interactive features like comments and likes. For users, the most “invisible” yet experientially crucial feature is cross-device playback resumption: watching half an episode on a phone during a commute and seamlessly continuing from the exact same spot on a TV at home; or clicking content on a web browser during the day and instantly finding it in the watch history on a client app at night.

This “continue watching on a different device” experience relies on a complete multi-device playback record synchronization system. It must answer three fundamental questions:

1. Collection: When, at what frequency, and in what format should the client report playback progress?
2. Resolution: When multiple devices report concurrently or with delays, which data does the server consider authoritative?
3. Distribution: How do other devices retrieve the latest progress with minimal latency?

These three questions correspond to client engineering, distributed consistency control, and API design, respectively. We will explore each in detail below.

2. Overall Architecture Design

A common synchronization system can be divided into four layers:

1. Client Collection Layer: The player kernel generates progress events. The client first persists them locally and then sends them according to a reporting strategy.
2. Access Layer: Responsible for login state validation (relying on a unified account system), user-level rate limiting, and parameter legality checks.
3. Storage and Compute Layer: Aggregates records using “user + content + episode” as the dimension, performs out-of-order resolution, and overwrites the record.
4. Distribution Layer: Delivers the latest state through watch history and resumption info APIs, supplemented by downstream push notifications for near-real-time refreshes when necessary.

The overall data flow is as follows:

Player progress event → Client local persistence → Strategy-based reporting (Key events + Heartbeat)
→ Access layer validation and rate limiting → Server-side version resolution → Overwrite to storage (hot data to cache)
→ Other devices pull or receive push → Merge with local data and refresh UI

The benefit of layering is that each layer can evolve independently: the reporting protocol can be rolled out via gray releases, storage can scale smoothly from a single database to sharded tables, and the external APIs remain stable.

3. Data Model Design

The core entity of a playback record is the “playback state of a user on a specific piece of content.” A typical record contains:

• User ID and Content ID: Locates the specific episode granularity (season + episode, or a business-defined content key).
• Playback State: Progress in seconds, total content duration, playback rate, resolution, etc.
• Metadata: Source device type, client version, reporting timestamp, incremental version number.

The schematic table structure is as follows:

CREATE TABLE play_record (
  user_id      BIGINT       NOT NULL,
  content_key  VARCHAR(64)  NOT NULL,
  episode_id   BIGINT       NOT NULL,
  progress_sec INT          NOT NULL,
  duration_sec INT          NOT NULL,
  client_type  TINYINT      NOT NULL,
  watched_at   BIGINT       NOT NULL,  -- Reporting timestamp (milliseconds)
  version      BIGINT       NOT NULL,  -- Monotonically increasing version number
  PRIMARY KEY (user_id, content_key, episode_id)
);

Several design points are worth emphasizing:

1. Using “user + content + episode” as the primary key makes writes naturally idempotent. Duplicate reports simply overwrite the same record, eliminating the need for extra deduplication logic.
2. Retaining the duration field is used to calculate “whether it was fully watched.” For example, when progress exceeds 95% of the total duration, the record can be migrated to a “watched” state, displaying a completion mark in the history list and removing it from “continue watching” candidates.
3. Retaining client_type helps troubleshoot online issues related to “which client’s reporting logic went wrong.”

On the read path, watch history is a typical read-heavy, write-light scenario, making it suitable for storing hot data in an in-memory key-value cache (with a key like uid:{user_id}:history), falling back to the database on a miss. List APIs should only return summary fields like content key, progress, cover image, and update time; details are fetched upon entering the page to avoid overly heavy single responses.

4. Reporting Strategy: Key Events First, Heartbeat Fallback

Reporting frequency is the core trade-off in the collection layer: reporting every second spikes server write pressure; reporting only on player exit means that if the app is killed by the OS or the device loses power, the episode’s progress will be stuck dozens of minutes in the past. In engineering practice, a hybrid strategy of “key events + heartbeat” is widely adopted:

1. Immediate Key Event Reporting: Start playback, pause, seek progress bar, switch episode, switch resolution or playback rate, exit player. User perception is highest at these nodes; losing even one can cause a noticeable deviation in the resumption position.
2. Periodic Heartbeat Reporting: Report current progress every 10 to 30 seconds during playback as a fallback for unexpected process termination. The period can be dynamically adjusted based on content duration.
3. Exit Guarantee: On occasions like player destruction or page unload, use synchronous requests or beacon-style reporting to try to send the final progress.

Schematic JSON payload:

{
  "content_key": "show_1001_s2e3",
  "episode_id": 20013,
  "progress_sec": 834,
  "duration_sec": 2640,
  "play_rate": 1.0,
  "definition": "1080p",
  "event": "heartbeat",
  "client_ts": 1718000000000,
  "client_type": 3
}

Here, event takes values like start / pause / seek / heartbeat / stop. The server can use this to distinguish “valid viewing” from “idle/AFK,” providing cleaner data sources for recommendations and analytics.

5. Out-of-Order and Conflict Resolution: Version Number Priority, Timestamp Assisted

Multi-device concurrent reporting inevitably introduces out-of-order delivery: Device A accumulates several progress records while offline and batches them upon network recovery. If the server uses a “first-come, first-served” approach, older progress will overwrite newer progress, causing the resumption position to jump backward. There are two common resolution strategies:

• Timestamp Comparison: The server only accepts records with a newer client timestamp. This is the simplest to implement but relies heavily on client clocks; device time drift can cause misjudgments.
• Version Number Comparison: The client maintains a locally monotonically increasing version number for the same content’s progress, incrementing it on each report. The server only accepts writes with a higher version number. The version number is returned by the server when delivering history, and the client increments it from there, ensuring causal ordering.

In practice, the two are usually combined: compare version numbers first; if the version numbers are equal, compare timestamps. Simultaneously, perform sanity checks on the progress itself (e.g., new progress cannot show abnormal speed increases exceeding the physical limit of the playback rate), blocking obviously abnormal data before writing.

Server-side resolution pseudo-code:

def on_report(uid, rec):
    old = store.get(uid, rec.content_key, rec.episode_id)
    if old is None or rec.version > old.version:
        store.put(uid, rec)
        return ACCEPTED
    if rec.version == old.version and rec.client_ts > old.watched_at:
        store.put(uid, rec)
        return ACCEPTED
    return STALE  # Stale data: discard, but return success to the client

The last line is particularly important: for reports judged as stale, a success response should still be returned to the client. If a failure is returned, the client will retry upon failure, repeatedly pushing stale data to the server and creating a “retry storm.”

6. Client Caching and Local Fallback

Playback records should not be heavily dependent on the network. The recommended approach is: write progress to a local embedded database or key-value store first, then report asynchronously. Play and persist normally during network disconnections; once the network recovers, backfill reports in version number order. The recommended data retrieval sequence on startup is:

1. Read local cache first, ensuring the history list and resumption position load instantly.
2. Then pull the latest records from the server, merge them with local data by version number, refresh the UI with the merged result, and write it back to the local database.

This way, even if the server is temporarily unavailable, users at least see the latest local progress, ensuring the core playback experience remains unaffected. This is a classic “offline-first” approach, with the only trade-off being an occasional progress jump backward (local data older than the server’s will be corrected).

7. Weak Network Tolerance and Security Validation

Designing the reporting link as a “best-effort” side-path logic involves several best practices:

1. Idempotency: Use (user, content, version number) as the idempotency key. Any retries will not produce dirty data.
2. Batch Compression Backfill: After network recovery, multiple heartbeat records for the same content can be compressed into a single latest record before backfilling, minimizing request volume.
3. Silent Failure: Reporting failures should only log and schedule a retry. Never pop up dialogs and never block the main playback flow.
4. Access Layer Validation: Rate limit by user dimension (e.g., accept at most one write per second for the same content), validate that progress does not exceed total duration, and check that speed increases do not violate the physical limits of the playback rate to filter malicious or abnormal reports.

8. Performance and Stability Practices

As scale grows, several engineering measures are needed to control costs and ensure stability:

1. Cold/Hot Tiering and Archiving: Store recently active records in cache and online databases; archive records unupdated for a certain number of days to cheaper storage. Migrate “watched” records out of the online table to keep the online table small and hot.
2. List Pagination and Incremental Fetching: History APIs should support pagination and incremental fetching based on update time cursors to avoid full table scans.
3. Monitoring Triad: Reporting success rate, write latency, and “version rollback rate” (proportion of STALE records). A sudden spike in version rollbacks for a specific client version often indicates a flaw in that version’s reporting logic, serving as a version quality alert signal.
4. Gray Release and Compatibility: For changes involving protocol semantics like version numbers, roll out by client version gradually, and retain backward-compatible reads for old protocols to prevent progress corruption caused by mutual overwrites between new and old versions.

9. Conclusion

Cross-device playback resumption may seem like just a small number in a history list, but behind it lies an entire suite of distributed system fundamentals: collection strategies, data modeling, storage and caching, conflict resolution, weak network tolerance, and monitoring. The core design trade-off remains constant: exchange the lowest possible reporting cost for the “closest to reality” playback progress on any device. By solidifying version number resolution, local fallback, and idempotent writes, supplemented by cold/hot tiering and version rollback monitoring, a multi-device synchronization system with consistent UX and controllable costs is fully equipped for production deployment.