# barry-ran/qtscrcpy architecture

> Architecture diagram of the GitHub repository barry-ran/qtscrcpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barry-ran/qtscrcpy
- Repository: https://github.com/barry-ran/qtscrcpy

## Overview

QtScrcpy is a cross-platform desktop client for viewing and controlling Android devices over USB or Wi-Fi. The main workflow is to select/connect a device and start its service in the main dialog, then view and interact with its screen in a per-device window; group control can relay actions to other devices. The README also documents audio, recording, and key mapping. The tree omits QtScrcpyCore and key-map assets, so core device-service internals and key-map implementation are not expanded here; relationships are limited to shown references and documented behavior.

Main entry points: [`QtScrcpy/ui/dialog.cpp`](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/dialog.cpp) (Device dialog), [`QtScrcpy/ui/videoform.cpp`](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/videoform.cpp) (Device video window), [`QtScrcpy/main.cpp`](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/main.cpp) (App startup), [`QtScrcpy/groupcontroller/groupcontroller.cpp`](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/groupcontroller/groupcontroller.cpp) (Group control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["App startup<br/>[main.cpp]"]
  node_dialog["Device dialog<br/>[dialog.cpp]"]
end

subgraph group_device["Device workflow"]
  node_core["QtScrcpyCore"]
  node_adb["ADB tooling"]
  node_group["Group control"]
  node_audio["Audio output<br/>[audiooutput.cpp]"]
end

subgraph group_ui["Interface"]
  node_video["Device video window<br/>[videoform.cpp]"]
  node_renderer["OpenGL renderer"]
  node_metal["Metal renderer<br/>[metalvideowindow.h]"]
  node_tools["Device toolbar<br/>[toolform.cpp]"]
  node_preset["Encoder presets<br/>[encoderpreset.cpp]"]
  node_presetdialog["Preset settings"]
  node_magnetic["Magnetic widget<br/>[magneticwidget.cpp]"]
end

subgraph group_support["Runtime support"]
  node_config[("User configuration<br/>[config.cpp]")]
  node_single["Single instance<br/>[singleinstance.cpp]"]
  node_icons["Icon helper<br/>[iconhelper.cpp]"]
  node_mouse["Mouse event tap<br/>[mousetap.cpp]"]
  node_mouseplatform["Platform mouse taps"]
end

node_user(("Desktop user"))
node_android(("Android device"))

node_user -->|"launches"| node_main
node_main -->|"opens"| node_dialog
node_main -->|"loads settings"| node_config
node_main -->|"checks instance"| node_single
node_dialog -->|"reads settings"| node_config
node_dialog -->|"runs commands"| node_adb
node_dialog -->|"connects device"| node_core
node_adb -.->|"connects over USB/Wi-Fi"| node_android
node_core -.->|"starts service"| node_android
node_core -.->|"delivers video frames"| node_video
node_video -->|"renders frames"| node_renderer
node_video -->|"renders frames"| node_metal
node_video -->|"opens toolbar"| node_tools
node_video -->|"enables event tap"| node_mouse
node_mouse -->|"selects implementation"| node_mouseplatform
node_dialog -->|"manages group control"| node_group
node_group -->|"dispatches device actions"| node_core
node_group -->|"checks host window"| node_video
node_dialog -->|"starts audio"| node_audio
node_dialog -.->|"configures presets"| node_presetdialog
node_presetdialog -.->|"uses preset data"| node_preset
node_dialog -->|"creates device window"| node_video
node_video -->|"uses icons"| node_icons
node_tools -->|"supports group actions"| node_group
node_tools -->|"inherits widget behavior"| node_magnetic
node_dialog -->|"selects connection"| node_android

click node_main "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/main.cpp"
click node_dialog "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/dialog.cpp"
click node_config "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/config.cpp"
click node_single "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/singleinstance.cpp"
click node_video "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/videoform.cpp"
click node_renderer "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/render/qyuvopenglwidget.cpp"
click node_metal "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/render/metalvideowindow.h"
click node_tools "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/toolform.cpp"
click node_group "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/groupcontroller/groupcontroller.cpp"
click node_audio "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/audio/audiooutput.cpp"
click node_preset "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/encoderpreset.cpp"
click node_presetdialog "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/presetconfigdialog.cpp"
click node_icons "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/fontawesome/iconhelper.cpp"
click node_mouse "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/mousetap/mousetap.cpp"
click node_mouseplatform "https://github.com/barry-ran/qtscrcpy/tree/dev/QtScrcpy/util/mousetap"
click node_magnetic "https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/uibase/magneticwidget.cpp"

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_main,node_dialog,node_user toneBlue
class node_core,node_adb,node_group,node_audio toneAmber
class node_video,node_renderer,node_metal,node_tools,node_preset,node_presetdialog,node_magnetic toneMint
class node_config,node_single,node_icons,node_mouse,node_mouseplatform toneRose
class node_android toneIndigo
```

## Components

### Application

- [App startup](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/main.cpp): `QtScrcpy/main.cpp`
- [Device dialog](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/dialog.cpp): `QtScrcpy/ui/dialog.cpp`

### Device workflow

- **QtScrcpyCore**
- **ADB tooling**
- [Group control](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/groupcontroller/groupcontroller.cpp): `QtScrcpy/groupcontroller/groupcontroller.cpp`
- [Audio output](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/audio/audiooutput.cpp): `QtScrcpy/audio/audiooutput.cpp`

### Interface

- [Device video window](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/videoform.cpp): `QtScrcpy/ui/videoform.cpp`
- [OpenGL renderer](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/render/qyuvopenglwidget.cpp): `QtScrcpy/render/qyuvopenglwidget.cpp`
- [Metal renderer](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/render/metalvideowindow.h): `QtScrcpy/render/metalvideowindow.h`
- [Device toolbar](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/toolform.cpp): `QtScrcpy/ui/toolform.cpp`
- [Encoder presets](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/encoderpreset.cpp): `QtScrcpy/ui/encoderpreset.cpp`
- [Preset settings](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/ui/presetconfigdialog.cpp): `QtScrcpy/ui/presetconfigdialog.cpp`
- [Magnetic widget](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/uibase/magneticwidget.cpp): `QtScrcpy/uibase/magneticwidget.cpp`

### Runtime support

- [User configuration](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/config.cpp): `QtScrcpy/util/config.cpp`
- [Single instance](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/singleinstance.cpp): `QtScrcpy/util/singleinstance.cpp`
- [Icon helper](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/fontawesome/iconhelper.cpp): `QtScrcpy/fontawesome/iconhelper.cpp`
- [Mouse event tap](https://github.com/barry-ran/qtscrcpy/blob/dev/QtScrcpy/util/mousetap/mousetap.cpp): `QtScrcpy/util/mousetap/mousetap.cpp`
- [Platform mouse taps](https://github.com/barry-ran/qtscrcpy/tree/dev/QtScrcpy/util/mousetap): `QtScrcpy/util/mousetap`

### Other components

- **Desktop user**
- **Android device**

## Connections

- Desktop user → App startup: launches
- App startup → Device dialog: opens (evidence: `QtScrcpy/main.cpp`)
- App startup → User configuration: loads settings (evidence: `QtScrcpy/main.cpp`)
- App startup → Single instance: checks instance (evidence: `QtScrcpy/main.cpp`)
- Device dialog → User configuration: reads settings (evidence: `QtScrcpy/ui/dialog.cpp`)
- Device dialog → ADB tooling: runs commands (evidence: `QtScrcpy/ui/dialog.cpp`)
- Device dialog → QtScrcpyCore: connects device (evidence: `QtScrcpy/ui/dialog.cpp`)
- ADB tooling → Android device: connects over USB/Wi-Fi
- QtScrcpyCore → Android device: starts service
- QtScrcpyCore → Device video window: delivers video frames
- Device video window → OpenGL renderer: renders frames (evidence: `QtScrcpy/ui/videoform.cpp`)
- Device video window → Metal renderer: renders frames (evidence: `QtScrcpy/ui/videoform.cpp`)
- Device video window → Device toolbar: opens toolbar (evidence: `QtScrcpy/ui/videoform.cpp`)
- Device video window → Mouse event tap: enables event tap (evidence: `QtScrcpy/ui/videoform.cpp`)
- Mouse event tap → Platform mouse taps: selects implementation (evidence: `QtScrcpy/util/mousetap/mousetap.cpp`)
- Device dialog → Group control: manages group control (evidence: `QtScrcpy/ui/dialog.cpp`)
- Group control → QtScrcpyCore: dispatches device actions (evidence: `QtScrcpy/groupcontroller/groupcontroller.cpp`)
- Group control → Device video window: checks host window (evidence: `QtScrcpy/groupcontroller/groupcontroller.cpp`)
- Device dialog → Audio output: starts audio (evidence: `QtScrcpy/ui/dialog.cpp`)
- Device dialog → Preset settings: configures presets
- Preset settings → Encoder presets: uses preset data
- Device dialog → Device video window: creates device window (evidence: `QtScrcpy/ui/dialog.cpp`)
- Device video window → Icon helper: uses icons (evidence: `QtScrcpy/ui/videoform.cpp`)
- Device toolbar → Group control: supports group actions (evidence: `QtScrcpy/ui/toolform.cpp`)
- Device toolbar → Magnetic widget: inherits widget behavior
- Device dialog → Android device: selects connection
