# arjncx-lang/screenme architecture

> Architecture diagram of the GitHub repository arjncx-lang/screenme, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arjncx-lang/screenme
- Repository: https://github.com/arjncx-lang/screenme

## Overview

#### Purpose and Runtime

Screenme is a local-only Windows 10/11 desktop screen recorder. It captures display video through FFmpeg, records microphone and system audio, and writes MP4 recordings plus optional PNG step screenshots to local user folders. The application is Python 3.10+; FFmpeg is an external executable provisioned in portable releases or by `tools/download_ffmpeg.py`.

Primary entry point: `app/main.py`. Portable bootstrap and launch are `setup.bat` and `run_screenme.bat`.

#### Application Composition

The application coordinates four major subsystems:

- Runtime initialization, settings, logging, platform capability detection, and FFmpeg resolution: `app/main.py`, `app/core/settings.py`, `app/core/ffmpeg_finder.py`.
- Capture lifecycle orchestration—start, pause/resume, stop, abort, output-session creation, and FFmpeg process control: `app/capture/recorder.py`, `app/capture/audio_recorder.py`.
- UI controls and capture-safe overlay behavior: `app/ui/overlay.py`, `app/ui/win_exclude.py`, `app/ui/settings_dialog.py`.
- Global keyboard interaction and tray-oriented control flow: `app/core/hotkeys.py`, `app/main.py`.

#### Recording Pipeline

`app/capture/recorder.py` is the central recording boundary. It likely translates selected capture area, frame/encoder settings, and output paths into FFmpeg screen-capture commands using Windows `gdigrab`, then manages the long-running encoding process and lifecycle transitions.

`app/core/ffmpeg_finder.py` resolves the required `ffmpeg.exe`; `app/core/cpu_detect.py` supports choosing CPU/GPU-appropriate encoding behavior. FFmpeg is the material external dependency responsible for HD video capture and MP4 encoding.

Recordings are organized as timestamped session directories containing `recording.mp4`, under the user’s Screenme video location. Path conventions and user storage roots are centralized in `app/core/paths.py`.

#### Audio Capture and Device Selection

Audio is separated from video capture into dedicated capture modules. `app/capture/devices.py` enumerates/selects recording devices, including the preference for an external microphone where available. `app/capture/audio_recorder.py` manages microphone and WASAPI loopback/system-audio acquisition or its integration into the recording session.

This boundary isolates Windows audio-device concerns from UI state and FFmpeg/video process orchestration.

#### UI, Capture Exclusion, and Region Selection

`app/ui/overlay.py` implements the transparent floating recorder controls and recording state presentation. `app/ui/win_exclude.py` applies the Windows capture-exclusion behavior (`WDA_EXCLUDEFROMCAPTURE`) so the control bar is not included in the recorded display.

`app/ui/region_select.py` owns user-driven region selection and supplies capture geometry to the recorder. `app/ui/settings_dialog.py` exposes persistent user choices, while `app/ui/styles.py` provides presentation styling rather than capture logic.

#### Screenshots and Session Artifacts

`app/capture/screenshot.py` creates PNG screenshots independently of the video lifecycle. During a recording, it emits sequential `step_N.png` artifacts into that active recording’s session folder; while idle, screenshots go to the user Pictures/Screenme location.

This establishes a key routing boundary: the recorder owns active-session context, while screenshot capture consumes that context when present and otherwise uses idle-output paths from `app/core/paths.py`.

#### Control Flow and Persistence

`app/main.py` constructs application services, initializes logging/settings, creates the overlay and settings UI, and binds UI actions and global hotkeys to recorder transitions. `app/core/hotkeys.py` enables Start/Stop, Pause/Resume, and Abort without requiring overlay focus.

`app/core/settings.py` persists capture, device, hotkey, and related user preferences across launches. `app/core/logging_setup.py` establishes diagnostics for startup, device discovery, FFmpeg invocation, and recording failures.

Main entry points: [`app/capture/recorder.py`](https://github.com/arjncx-lang/screenme/blob/main/app/capture/recorder.py) (Recording orchestrator), [`app/main.py`](https://github.com/arjncx-lang/screenme/blob/main/app/main.py) (Application host), [`app/core/paths.py`](https://github.com/arjncx-lang/screenme/blob/main/app/core/paths.py) (Output paths), [`app/ui/overlay.py`](https://github.com/arjncx-lang/screenme/blob/main/app/ui/overlay.py) (Recorder overlay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & control"]
  node_bootstrap["Portable launch<br/>batch bootstrap<br/>[setup.bat]"]
  node_main["Application host<br/>Python entry point<br/>[main.py]"]
  node_settings[("Settings<br/>preference store<br/>[settings.py]")]
  node_logging["Diagnostics<br/>logging setup<br/>[logging_setup.py]"]
  node_hotkeys["Global hotkeys<br/>input service<br/>[hotkeys.py]"]
  node_ffmpeg_finder["FFmpeg resolver<br/>dependency resolver<br/>[ffmpeg_finder.py]"]
  node_cpu_detect["CPU/GPU detection<br/>capability detection<br/>[cpu_detect.py]"]
end

subgraph group_capture["Capture pipeline"]
  node_recorder["Recording orchestrator<br/>capture lifecycle<br/>[recorder.py]"]
  node_audio_recorder["Audio recorder<br/>audio capture<br/>[audio_recorder.py]"]
  node_devices["Audio devices<br/>device discovery<br/>[devices.py]"]
  node_screenshot["Screenshot capture<br/>PNG capture<br/>[screenshot.py]"]
  node_ffmpeg{{"FFmpeg<br/>external executable"}}
end

subgraph group_ui["UI"]
  node_overlay["Recorder overlay<br/>floating controls<br/>[overlay.py]"]
  node_region_select["Region selection<br/>capture geometry<br/>[region_select.py]"]
  node_win_exclude["Capture exclusion<br/>Windows display API<br/>[win_exclude.py]"]
  node_settings_dialog["Settings dialog<br/>preferences UI<br/>[settings_dialog.py]"]
end

subgraph group_storage["Local storage"]
  node_paths["Output paths<br/>storage routing<br/>[paths.py]"]
  node_session[("Recording session<br/>timestamped local folder")]
  node_idle_screenshots[("Idle screenshots<br/>local picture folder")]
end

node_bootstrap -->|"launches"| node_main
node_main -->|"loads"| node_settings
node_main -->|"initializes"| node_logging
node_main -->|"binds"| node_hotkeys
node_main -->|"creates"| node_overlay
node_main -->|"creates"| node_settings_dialog
node_hotkeys -->|"controls lifecycle"| node_recorder
node_overlay -->|"controls lifecycle"| node_recorder
node_overlay -->|"excludes controls"| node_win_exclude
node_region_select -->|"supplies geometry"| node_recorder
node_settings_dialog -->|"updates"| node_settings
node_recorder -->|"uses capture preferences"| node_settings
node_recorder -->|"resolves"| node_ffmpeg_finder
node_recorder -->|"selects encoder"| node_cpu_detect
node_recorder -->|"coordinates"| node_audio_recorder
node_audio_recorder -->|"selects inputs"| node_devices
node_recorder -->|"starts capture process"| node_ffmpeg
node_recorder -->|"creates output path"| node_paths
node_paths -->|"locates"| node_session
node_ffmpeg -->|"writes recording.mp4"| node_session
node_screenshot -->|"writes step_N.png when active"| node_session
node_screenshot -->|"uses idle route"| node_paths
node_paths -->|"locates"| node_idle_screenshots

click node_bootstrap "https://github.com/arjncx-lang/screenme/blob/main/setup.bat"
click node_main "https://github.com/arjncx-lang/screenme/blob/main/app/main.py"
click node_settings "https://github.com/arjncx-lang/screenme/blob/main/app/core/settings.py"
click node_logging "https://github.com/arjncx-lang/screenme/blob/main/app/core/logging_setup.py"
click node_hotkeys "https://github.com/arjncx-lang/screenme/blob/main/app/core/hotkeys.py"
click node_ffmpeg_finder "https://github.com/arjncx-lang/screenme/blob/main/app/core/ffmpeg_finder.py"
click node_cpu_detect "https://github.com/arjncx-lang/screenme/blob/main/app/core/cpu_detect.py"
click node_recorder "https://github.com/arjncx-lang/screenme/blob/main/app/capture/recorder.py"
click node_audio_recorder "https://github.com/arjncx-lang/screenme/blob/main/app/capture/audio_recorder.py"
click node_devices "https://github.com/arjncx-lang/screenme/blob/main/app/capture/devices.py"
click node_screenshot "https://github.com/arjncx-lang/screenme/blob/main/app/capture/screenshot.py"
click node_overlay "https://github.com/arjncx-lang/screenme/blob/main/app/ui/overlay.py"
click node_region_select "https://github.com/arjncx-lang/screenme/blob/main/app/ui/region_select.py"
click node_win_exclude "https://github.com/arjncx-lang/screenme/blob/main/app/ui/win_exclude.py"
click node_settings_dialog "https://github.com/arjncx-lang/screenme/blob/main/app/ui/settings_dialog.py"
click node_paths "https://github.com/arjncx-lang/screenme/blob/main/app/core/paths.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_main,node_settings,node_logging,node_hotkeys,node_ffmpeg_finder,node_cpu_detect toneBlue
class node_recorder,node_audio_recorder,node_devices,node_screenshot,node_ffmpeg toneAmber
class node_overlay,node_region_select,node_win_exclude,node_settings_dialog toneMint
class node_paths,node_session,node_idle_screenshots toneRose
```

## Components

### Runtime & control

- [Portable launch](https://github.com/arjncx-lang/screenme/blob/main/setup.bat): batch bootstrap · Sets up and launches the local desktop application. · `setup.bat`
- [Application host](https://github.com/arjncx-lang/screenme/blob/main/app/main.py): Python entry point · Composes services and binds controls to recorder transitions. · `app/main.py`
- [Settings](https://github.com/arjncx-lang/screenme/blob/main/app/core/settings.py): preference store · Persists capture, device, and hotkey choices. · `app/core/settings.py`
- [Diagnostics](https://github.com/arjncx-lang/screenme/blob/main/app/core/logging_setup.py): logging setup · `app/core/logging_setup.py`
- [Global hotkeys](https://github.com/arjncx-lang/screenme/blob/main/app/core/hotkeys.py): input service · `app/core/hotkeys.py`
- [FFmpeg resolver](https://github.com/arjncx-lang/screenme/blob/main/app/core/ffmpeg_finder.py): dependency resolver · `app/core/ffmpeg_finder.py`
- [CPU/GPU detection](https://github.com/arjncx-lang/screenme/blob/main/app/core/cpu_detect.py): capability detection · `app/core/cpu_detect.py`

### Capture pipeline

- [Recording orchestrator](https://github.com/arjncx-lang/screenme/blob/main/app/capture/recorder.py): capture lifecycle · Owns session creation and video process lifecycle. · `app/capture/recorder.py`
- [Audio recorder](https://github.com/arjncx-lang/screenme/blob/main/app/capture/audio_recorder.py): audio capture · Captures microphone and WASAPI loopback audio. · `app/capture/audio_recorder.py`
- [Audio devices](https://github.com/arjncx-lang/screenme/blob/main/app/capture/devices.py): device discovery · `app/capture/devices.py`
- [Screenshot capture](https://github.com/arjncx-lang/screenme/blob/main/app/capture/screenshot.py): PNG capture · Routes screenshots to an active session or idle picture storage. · `app/capture/screenshot.py`
- **FFmpeg**: external executable · Captures gdigrab video and encodes MP4 output.

### UI

- [Recorder overlay](https://github.com/arjncx-lang/screenme/blob/main/app/ui/overlay.py): floating controls · `app/ui/overlay.py`
- [Region selection](https://github.com/arjncx-lang/screenme/blob/main/app/ui/region_select.py): capture geometry · `app/ui/region_select.py`
- [Capture exclusion](https://github.com/arjncx-lang/screenme/blob/main/app/ui/win_exclude.py): Windows display API · Excludes recorder controls from captured displays. · `app/ui/win_exclude.py`
- [Settings dialog](https://github.com/arjncx-lang/screenme/blob/main/app/ui/settings_dialog.py): preferences UI · `app/ui/settings_dialog.py`

### Local storage

- [Output paths](https://github.com/arjncx-lang/screenme/blob/main/app/core/paths.py): storage routing · Defines user storage roots and session path conventions. · `app/core/paths.py`
- **Recording session**: timestamped local folder · Contains recording.mp4 and active-session step screenshots.
- **Idle screenshots**: local picture folder

## Connections

- Portable launch → Application host: launches
- Application host → Settings: loads
- Application host → Diagnostics: initializes
- Application host → Global hotkeys: binds
- Application host → Recorder overlay: creates
- Application host → Settings dialog: creates
- Global hotkeys → Recording orchestrator: controls lifecycle
- Recorder overlay → Recording orchestrator: controls lifecycle
- Recorder overlay → Capture exclusion: excludes controls
- Region selection → Recording orchestrator: supplies geometry
- Settings dialog → Settings: updates
- Recording orchestrator → Settings: uses capture preferences
- Recording orchestrator → FFmpeg resolver: resolves
- Recording orchestrator → CPU/GPU detection: selects encoder
- Recording orchestrator → Audio recorder: coordinates
- Audio recorder → Audio devices: selects inputs
- Recording orchestrator → FFmpeg: starts capture process
- Recording orchestrator → Output paths: creates output path
- Output paths → Recording session: locates
- FFmpeg → Recording session: writes recording.mp4
- Screenshot capture → Recording session: writes step_N.png when active
- Screenshot capture → Output paths: uses idle route
- Output paths → Idle screenshots: locates