annie.pages.videoclock
======================

.. py:module:: annie.pages.videoclock

.. autoapi-nested-parse::

   Frame-accurate control of one HTML5 ``<video>`` element (UI, browser-gated).

   The Event-annotation task drives a single ``ui.video`` from Python: play/pause, seek to a
   time or a frame, step frame-by-frame, and jump ±5 s. HTML5 video exposes only a **time**
   cursor (``currentTime`` in seconds), not a frame cursor, so every frame operation converts
   through the video's ``fps``:

       frame  ->  currentTime = frame / fps + half_frame_nudge
       time   ->  frame       = round(currentTime * fps)

   **Documented limitation.** Because seeking is time-based, the landed frame is
   ``round(currentTime * fps)``. On constant-fps media — which Annie's convert pipeline
   produces (see :mod:`annie.media.convert`) — this is exact. On a variable-fps source it can
   be off by one frame. That is the accepted trade-off for smooth playback *with audio*, which
   a torchcodec frame-by-frame decoder cannot give; an exact confirm is a possible later
   refinement, deliberately out of scope here.

   This module is a thin bridge: each function returns the JavaScript that acts on the element,
   run via :func:`nicegui.ui.run_javascript`. It holds no state — the task owns the model. It
   is exercised in the browser, not unit-tested, like the other ``ui.video`` paths.



Functions
---------

.. autoapisummary::

   annie.pages.videoclock.element_id
   annie.pages.videoclock.play
   annie.pages.videoclock.pause
   annie.pages.videoclock.toggle
   annie.pages.videoclock.seek_seconds
   annie.pages.videoclock.seek_frame
   annie.pages.videoclock.step_frames
   annie.pages.videoclock.nudge_seconds
   annie.pages.videoclock.current_time
   annie.pages.videoclock.set_playhead_x
   annie.pages.videoclock.set_scrollbar
   annie.pages.videoclock.set_pending_band


Module Contents
---------------

.. py:function:: element_id(client_id: str) -> str

   Return the stable DOM id given to the task's video element for a client.

   :param client_id: The NiceGUI client id (``context.client.id``).

   :returns: A DOM id unique to that client's Event-annotation video.


.. py:function:: play(element_id_: str) -> None

   Start playback of the video element.


.. py:function:: pause(element_id_: str) -> None

   Pause the video element.


.. py:function:: toggle(element_id_: str) -> None

   Toggle play/pause on the video element.


.. py:function:: seek_seconds(element_id_: str, seconds: float) -> None

   Seek the video to an absolute time in seconds (clamped at zero).

   :param element_id_: The video element's DOM id.
   :param seconds: The target time; negative values clamp to the start.


.. py:function:: seek_frame(element_id_: str, frame: int, fps: float) -> None

   Seek the video to a specific frame via its time, with a half-frame nudge.

   :param element_id_: The video element's DOM id.
   :param frame: The target frame index (clamped at zero).
   :param fps: Frames per second; a non-positive fps seeks to the start.


.. py:function:: step_frames(element_id_: str, delta: int, fps: float) -> None

   Pause and move the cursor by ``delta`` frames (positive forward, negative back).

   :param element_id_: The video element's DOM id.
   :param delta: Number of frames to move; sign gives the direction.
   :param fps: Frames per second; a non-positive fps is a no-op.


.. py:function:: nudge_seconds(element_id_: str, delta: float) -> None

   Jump the cursor by ``delta`` seconds (the ±5 s buttons), clamped at the start.

   :param element_id_: The video element's DOM id.
   :param delta: Seconds to move; sign gives the direction.


.. py:function:: current_time(element_id_: str) -> collections.abc.Awaitable[float]

   Read the video's current time in seconds from the browser.

   Used when ``I``/``O`` capture the playhead: the caller awaits this, converts to a frame,
   and writes the event boundary. Returns ``0.0`` if the element is gone.

   :param element_id_: The video element's DOM id.

   :returns: An awaitable resolving to the current time in seconds.


.. py:function:: set_playhead_x(timeline_id: str, x_fraction: float | None) -> None

   Move the timeline playhead line to a horizontal fraction without a full re-render.

   The playhead is a single SVG line inside the timeline element; the poll updates only its
   position so playback stays cheap (no server round-trip re-draw of the event boxes).

   :param timeline_id: DOM id of the timeline's SVG element.
   :param x_fraction: Playhead position as a fraction ``[0, 1]`` of the visible window, or
                      ``None`` when the playhead is outside it — the line is then hidden, never pinned
                      to an edge.


.. py:function:: set_scrollbar(scroll_id: str, left: float, width: float) -> None

   Move the pan scrollbar's thumb without rebuilding it (so a drag is not interrupted).

   :param scroll_id: DOM id of the scrollbar track.
   :param left: The thumb's left edge as a fraction of the track.
   :param width: The thumb's width as a fraction of the track.


.. py:function:: set_pending_band(timeline_id: str, start_fraction: float, end_fraction: float) -> None

   Resize the amber capture band without a full re-render, while a start is armed.

   Mirrors :func:`set_playhead_x`: the band is one ``.annie-pending`` rect, and the poll
   updates only its ``x``/``width`` from two ``[0, 1]`` fractions so it grows with the
   playhead cheaply. Fractions are ordered and clamped, so a playhead left of the start still
   yields a valid (leftward) band.

   :param timeline_id: DOM id of the timeline's SVG element.
   :param start_fraction: The band's start edge as a fraction of the timeline width.
   :param end_fraction: The band's end edge (the live playhead) as a fraction of the width.