Skip to content

Latest commit

 

History

History
69 lines (45 loc) · 3.67 KB

TIMESYNCApi.md

File metadata and controls

69 lines (45 loc) · 3.67 KB

HandyAPI::TIMESYNCApi

All URIs are relative to https://www.handyfeeling.com/api/handy/v2

Method HTTP request Description
get_server_time GET /servertime Get current server time.

get_server_time

get_server_time

Get current server time.

Provides the server time that you must use when calculating the client-server-offset (cs_offset), which is used when calculating a client-side-estimated-server-time (Tcest).

Client-server-offset

The client-server-offset (cs_offset) can be calculated the following way:
  1. Collect X server time (Ts) samples using this endpoint. A higher number of samples will results in longer estimation time but a more accurate result. A good sample size is 30 (X = 30).
  2. Track the round-trip-delay (RTD) for each sample by recording the request send time (Tsend) and response received time (Treceive). Calculate RTD = Treceive – Tsend.
  3. Calculate the estimated server time when the response is received (Ts_est) by adding half the RTD time to the received server time value (Ts). Ts_est = Ts + RTD/2.
  4. Calculate the offset between estimated server time (Ts_est) and client time (Tc). Upon receive Tc == Treceive => offset = Ts_est - Treceive.
  5. Add the offset to the aggregated offset value (offset_agg). offset_agg = offset_agg + offset.
  6. When all samples have been received calculate the average offset (cs_offset) by dividing aggregated offset (offset_agg) values by the number of samples (X). cs_offset = offset_agg / X
The process above gives you a good estimate of the client-server-offset (cs_offset).

Normally you calculate the cs_offset once, and use it whenever you need to calculate client-side-estimated-server-time (Tcest).
However, if the synchronization between device and the service (eg. video/script synchronization) is off (maybe due to changing network topology, clock drift, bad initial calculation, etc.), it might help to re-calculate the cs_offset.

Client-side-estimated-server-time

The client-side-estimated-server-time (Tcest) value is required in some of the API endpoints (eg. /hssp/play).

The Tcest is calculated the following way:

   Tcest = Tc + cs_offset

where Tc is the current client time and cs_offset is the client-server-offset.

Examples

require 'time'
require 'handy_api'

api_instance = HandyAPI::TIMESYNCApi.new

begin
  # Get current server time.
  result = api_instance.get_server_time
  p result
rescue HandyAPI::ApiError => e
  puts "Error when calling TIMESYNCApi->get_server_time: #{e}"
end

Using the get_server_time_with_http_info variant

This returns an Array which contains the response data, status code and headers.

<Array(, Integer, Hash)> get_server_time_with_http_info

begin
  # Get current server time.
  data, status_code, headers = api_instance.get_server_time_with_http_info
  p status_code # => 2xx
  p headers # => { ... }
  p data # => <ServerTimeResponse>
rescue HandyAPI::ApiError => e
  puts "Error when calling TIMESYNCApi->get_server_time_with_http_info: #{e}"
end

Parameters

This endpoint does not need any parameter.

Return type

ServerTimeResponse

Authorization

No authorization required

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json