Skip to content

Session Service

app.application.services.session_service

View source code

Session lifecycle management and worker coordination service.

See Also

Layer: Application. Context: Coordinates domain state and infrastructure to complete application use cases.

SessionService

Bases: QObject

Facade that orchestrates session open/switch/playback/settings flows.

Responsibilities:

  • Open videos and create sessions from file paths
  • Handle active session switching (delegates worker lifecycle to VideoDecodeWorkerManager)
  • Check worker states (detection, tracking, buffering) via Session properties
  • Update session settings with type validation

Architecture:

  • Owned by App (via parent relationship)
  • Delegates actual session creation to App
  • Delegates VideoDecodeWorker activation/deactivation to VideoDecodeWorkerManager
  • Does NOT create detection/tracking workers (delegates to respective services)

Worker Management:

  • VideoDecodeWorkerManager.switch_active_session is the single canonical entry-point for worker view_state transitions.
  • Only active session's VideoDecodeWorker is truly active (buffering frames)
  • Inactive sessions' workers are paused to save CPU/memory
  • When switching sessions: old worker paused → new worker resumed
PARAMETER DESCRIPTION
app

Application that owns this Qt service and receives active-session change notifications.

TYPE: Application

__init__(app: Application)

handle_active_session_changed(old_s_id: SessionId | None, new_s_id: SessionId) -> None

Coordinate worker view_state when switching to a different session.

Parameters:

  • old_s_id — Previously active session ID (may be None on startup)
  • new_s_id — New active session ID

Flow:

Delegates entirely to VideoDecodeWorkerManager.switch_active_session, which is the canonical owner of the old→new decode-worker transition:

switch_active_session(old_s_id, new_s_id)
  ├── Guard: if old == new, return immediately (no duplicate churn)
  ├── If old session exists: pause its VideoDecodeWorker
  └──> Resume VideoDecodeWorker for new session

Purpose:

  • Pauses old worker to save CPU (stops buffering frames)
  • Resumes new worker to start buffering its frames
  • Only one worker should be buffering at a time

open_videos(paths: Iterable[str]) -> list[str]

Open video files and create sessions for each file.

Parameters:

  • paths — Iterable of file path strings (e.g., list of absolute paths)

Returns:

List of successfully opened paths (excludes duplicates that were already open)

Behavior:

  • Iterates through provided paths
  • Skips paths that are already open (SessionAlreadyExistsException)
  • Raises error if NO new sessions were opened
  • Sets first new session as active if none currently active

Error Handling:

  • Raises NoNewOpenedSessionsException if all paths are duplicates
  • Logs info/warning for skipped paths, does not stop processing

session_by_id_has_buffered_frame(s_id: SessionId) -> bool

Check if a pre-decoded frame is available in the buffer for the session.

Parameters:

  • s_id — Session ID to check

Returns:

True if next frame is buffered and ready, False if buffer miss (worker behind)

Use Case:

During playback, check if the next frame is ready before rendering to avoid stutter.

session_by_id_has_running_detection_worker(s_id: SessionId) -> bool

Check if a detection worker is currently running for the session.

Parameters:

  • s_id — Session ID to check

Returns:

True if DetectionWorker exists and is actively running, False otherwise

Use Case:

Prevent starting another detection if one is already in progress.

session_by_id_has_running_tracking_worker(s_id: SessionId) -> bool

Check if a tracking worker is currently running for the session.

Parameters:

  • s_id — Session ID to check

Returns:

True if TrackingWorker exists and is actively running, False otherwise

Use Case:

Prevent starting another tracking if one is already in progress.

start_session_playback(s_id: SessionId) -> None

Start session playback.

PARAMETER DESCRIPTION
s_id

Identifier of the session whose playback state should become active.

TYPE: SessionId

update_session_settings(s_id: SessionId, **kwargs) -> None

Update session settings by attribute name with type validation.

Parameters:

  • s_id — Session ID
  • **kwargs — Keyword arguments where key is setting name, value is new value Examples: min_detection_confidence=0.5, blur_enabled=True, draw_boxes=False

Behavior:

  • Validates that the setting key exists; logs a warning and skips unknown keys.
  • Validates that the value type is compatible with the existing field type; logs a warning and skips type-mismatched updates.
  • int values are accepted for float fields (numeric widening).
  • Applies the update via setattr when all checks pass.

Example:

python service.update_session_settings(s_id, blur_strength=25, draw_boxes=True)