Playback Handler

app.ui.handlers.playback_handler

View source code

Playback control handler for video playback operations.

`PlaybackHandler`

Bases: QObject

Manages video playback controls and timer-based frame rendering.

Responsibilities

Handle play, pause, next frame, and previous frame actions.
Manage playback timer for periodic frame updates during playback.
Coordinate frame seeking and rendering.
Emit frame render requests to update the UI.

Note

Signal flow: Receives signals from transport control panel (play, pause, seek buttons). Emits render_frame_requested signal to trigger frame updates. Uses QTimer to trigger periodic on_playback_tick() calls during playback.

PARAMETER	DESCRIPTION
`controller`	Provides playback operations, transport controls, and frame rendering. TYPE: `UIController`

`render_frame_requested = Signal(object)` `class-attribute` `instance-attribute`

Emitted when a frame needs to be rendered. Payload: SessionId.

`selected_s_id: SessionId` `property`

Retrieves the selected session ID from the session list.

RETURNS	DESCRIPTION
`SessionId`	Identifier of the selected session, or the empty identifier when none is selected.

`init(controller: UIController) -> None`

`on_fit_view_requested() -> None`

Reset the preview viewport to fit the image within its available area.

`on_next_frame() -> None`

Advance to the next frame in the selected session.

Note

Triggered by transport panel next_btn.clicked signal.

Flow: on_next_frame() [this slot] ├── Stop current playback if active ├── Load next frame via App └──> Emit render_frame_requested(s_id)

`on_pause() -> None`

Stop video playback for the selected session.

Note

Triggered by transport panel pause_btn.clicked signal.

Action: Calls stop_playback() to halt the playback timer and app playback view_state.

`on_play() -> None`

Start video playback for the selected session.

Note

Triggered by transport panel play_btn.clicked signal.

Flow: on_play() [this slot] ├── Validate session is selected └──> Call _start_session_playback(s_id) ├── Start App playback ├── Calculate frame interval └──> Start playback QTimer

`on_playback_tick() -> None`

Periodic timer callback to update frame during playback.

Note

Triggered by _playback_timer.timeout signal at regular intervals.

Flow: on_playback_tick() [this slot] ├── Check if session is still selected ├── Check if at last frame (stop if true) ├── Check if buffered frame is available ├── If available: render frame └── If not: skip frame to maintain sync (buffer underrun)

Why this matters: Called every 16ms (or configured interval) during playback. Pulls pre-buffered frames from VideoDecodeWorker. Skips frames if buffer underruns to prevent stutter. Stops playback automatically at end of video.

`on_previous_frame() -> None`

Advance to the previous frame in the selected session.

Note

Triggered by transport panel previous_btn.clicked signal.

Flow: on_previous_frame() [this slot] ├── Stop current playback ├── Load previous frame via App └──> Render frame via Controller

`on_rotate_requested(delta_degrees: int) -> None`

Rotate the selected video's preview by the requested number of degrees.

PARAMETER	DESCRIPTION
`delta_degrees`	Rotation increment requested by a transport control. TYPE: `int`

`on_seek(frame_index: int) -> None`

Seek to a specific frame index via slider movement.

Note

Triggered by transport panel seek_slider sliderMoved signal.

Flow: on_seek(frame_index) [this method] ├── Stop any active playback ├── Load frame at frame_index via App └──> Render frame via Controller

`stop_playback() -> None`

Stop video playback and reset playback timer.

Note

Flow: stop_playback() ├── Stop the QTimer (stops on_playback_tick() calls) ├── Notify App to stop all playback └──> Update UI status bar

Playback Handler