Foreground Tracker

Track the active Windows foreground application and persist completed foreground and idle intervals.

Foreground window inspection

source

get_foreground_window_info

def get_foreground_window_info()->tuple[str, int, int, str]:

Return the foreground window title, handle, process ID, and process name.

Streaming-specific idle thresholds

source

is_streaming_app

def is_streaming_app(
    title:str, # Foreground window title to inspect
    streaming_app_min_idle_time:dict[str, int | float], # Title substrings mapped to idle thresholds in seconds
)->int | float | None:

Return the idle threshold for the first configured title match, or None.

Foreground interval monitoring

source

start_foreground_app_monitoring

def start_foreground_app_monitoring(
    session_id:str, # Monitoring session receiving foreground intervals
    stop_event:object, # Stop signal providing an `is_set()` method
    time_interval:int | float=2, # Seconds between foreground samples
    min_idle_time_gap:int | float=60, # General idle threshold in seconds
    streaming_app_min_idle_time:dict[str, int | float]={'youtube': 600, 'netflix': 600, 'twitch': 600}, # Title-specific idle thresholds
)->None:

Sample foreground state until stopped and record each completed interval.

  • stop_event is documented only as an object providing is_set(). The code does not establish whether it must specifically be a threading.Event or may be another compatible stop signal.

  • is_streaming_app returns the first case-insensitive substring match. Therefore dictionary insertion order determines the result when several configured strings match the same title. Confirm that this priority rule is intentional.

  • start_foreground_app_monitoring calls is_streaming_app twice whenever a streaming-title match is found. This is redundant but has been preserved to avoid changing behaviour.

  • Raw foreground window titles are passed to log_fg_app_events. The current implementation does not consult SHOW_WINDOW_TITLES or apply title-cleaning or privacy rules. Confirm that retaining raw titles is acceptable for the present MVP.

  • KeyboardInterrupt is caught inside the monitoring function. If this function normally runs in a worker thread, confirm whether that exception handling is expected to be effective there.