@type option() ::
  {:time_provider, (-> Membrane.Time.t())}
  | {:proxy, boolean()}
  | {:proxy_for, pid() | nil}

Options accepted by start_link/2 and start/2 functions.

They are the following:

• time_provider - function providing the reference time in milliseconds
• proxy - determines whether the Clock should work in proxy mode
• proxy_for - enables the proxy mode and sets proxied Clock to pid

Check the moduledoc for more details.

@type ratio() :: Ratio.t()

Ratio of the Clock time to the reference time.

@type ratio_message() :: {:membrane_clock_ratio, clock :: pid(), ratio()}

Ratio message sent by the Clock to all its subscribers. It contains the ratio of the custom clock time to the reference time.

@type t() :: pid()

Clock is a Membrane utility that allows elements to measure time according to a particular clock, which can be e.g. a soundcard hardware clock.

Internally, Clock is a GenServer process that can receive updates (see update_message/0), which are messages containing amount of time until the next update. For example, a sink playing audio to the sound card can send an update before each write to the sound card buffer (for practical reasons that can be done every 100 or 1000 writes). Although it might be more intuitive to send updates with the time passed, in practice the described approach turns out to be more convenient, as it simplifies the first update.

Basing on updates, Clock calculates the ratio/0 of its time to the reference time. The reference time can be configured with :time_provider option. The ratio is broadcasted (see ratio_message/0) to subscribers (see subscribe/2)

• processes willing to synchronize to the custom clock. Subscribers can adjust their timers according to received ratio - timers started with Membrane.Element.Action.start_timer/0 action in elements do it automatically. Initial ratio is equal to 1, which means that if no updates are received, Clock is synchronized to the reference time.

Proxy mode

Clock can work in proxy mode, which means it cannot receive updates, but it receives ratio from another clock instead, and forwards it to subscribers. Proxy mode is enabled with proxy_for: pid or proxy: true (no initial proxy) option, and the proxy is set/changed using proxy_for/2.

@type update_message() ::
  {:membrane_clock_update,
   milliseconds ::
     non_neg_integer()
     | ratio()
     | {numerator :: non_neg_integer(), denominator :: pos_integer()}}

Update message received by the Clock. It should contain the time till the next update.