{"id":51621137,"url":"https://github.com/nexuls/scrcpy-gui","last_synced_at":"2026-07-12T19:43:32.918Z","repository":{"id":341371887,"uuid":"1169784103","full_name":"nexuls/scrcpy-gui","owner":"nexuls","description":"Windows-first scrcpy desktop GUI built with Wails (Go + React), featuring device discovery, rich launch options, live session logs, and bundled scrcpy/adb packaging for easy distribution.","archived":false,"fork":false,"pushed_at":"2026-03-01T12:49:30.000Z","size":20275,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-12T19:43:28.929Z","etag":null,"topics":["cross-platform","desktop-app","scrcpy","scrcpy-gui","scrcpy-ui","wails"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nexuls.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-01T07:49:44.000Z","updated_at":"2026-03-08T12:51:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nexuls/scrcpy-gui","commit_stats":null,"previous_names":["neuronexul/scrcpy-gui","nexuls/scrcpy-gui"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/nexuls/scrcpy-gui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexuls%2Fscrcpy-gui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexuls%2Fscrcpy-gui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexuls%2Fscrcpy-gui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexuls%2Fscrcpy-gui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nexuls","download_url":"https://codeload.github.com/nexuls/scrcpy-gui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nexuls%2Fscrcpy-gui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35401732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cross-platform","desktop-app","scrcpy","scrcpy-gui","scrcpy-ui","wails"],"created_at":"2026-07-12T19:43:32.386Z","updated_at":"2026-07-12T19:43:32.904Z","avatar_url":"https://github.com/nexuls.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# scrcpy-gui\n\nDesktop GUI for [scrcpy](https://github.com/Genymobile/scrcpy), built with Wails (Go backend + React frontend), with Windows and Linux runtime support.\n\n![App Screenshot](./frontend/src/assets/405_1x_shots_so.jpeg)\n\nThis app focuses on a practical workflow:\n- detect `scrcpy` + `adb`\n- verify bundled runtime files\n- select device/connection mode\n- launch one or more scrcpy sessions\n- stream live logs per running session\n\n---\n\n## Features\n\n- **Environment checks** for `scrcpy` and `adb` paths\n- **Bundle health checks** using `required-files.txt`\n- **Device discovery** via `adb devices -l`\n- **Multi-instance sessions** (start/stop individual or stop all)\n- **Live stdout/stderr logs** with bounded in-memory history\n- **Structured launch options** for display/camera/audio/window/input/recording/diagnostics\n- **Platform-aware runtime bundle checks** for Windows and Linux\n- **Windows packaging path** with bundled binaries and NSIS installer support\n\n---\n\n## Tech Stack\n\n- **Backend:** Go 1.23 + Wails v2\n- **Frontend:** React + TypeScript + Vite + Bun\n- **Desktop shell:** Wails (frameless window)\n\n---\n\n## Prerequisites\n\nInstall these tools before development:\n\n1. **Go 1.23+**\n2. **Wails CLI v2**\n3. **Bun** (used by this repo for frontend install/build in `wails.json`)\n4. **Desktop runtime prerequisites**\n\t- Windows: WebView2 runtime (normally present on modern Windows; installer can bootstrap if needed)\n\t- Linux: GTK/WebKit dependencies required by Wails WebView\n\nFor device interaction:\n\n- Android device with USB debugging enabled\n- Appropriate USB drivers (if required by your device/vendor)\n\n---\n\n## Runtime Bundle (Required for Packaging)\n\nThe app is designed to ship `scrcpy` and `adb` with the build output/installer.\n\nPut runtime files in:\n\n- `bundle/\u003cos\u003e/bin/` (`\u003cos\u003e` is `windows` or `linux`)\n\nRequired baseline files:\n\n- Windows: `scrcpy.exe`, `adb.exe`\n- Linux: `scrcpy`, `adb`\n\nAdditional required files are defined in:\n\n- `bundle/\u003cos\u003e/bin/required-files.txt`\n\nCurrent manifest includes:\n\n- `AdbWinApi.dll`\n- `AdbWinUsbApi.dll`\n- `SDL2.dll`\n\nIf required files are missing, launch is blocked with a bundle health error.\n\n---\n\n## Quick Start (Development)\n\nFrom project root:\n\n```powershell\nwails dev\n```\n\nWails will run frontend install/build/watch using Bun as configured in `wails.json`.\n\nDuring first run, confirm:\n\n- status badges show `scrcpy: ok`, `adb: ok`, `bundle: ok`\n- at least one Android device appears in the device selector\n\n---\n\n## Building for Windows\n\nUse the provided script to ensure bundled files are copied correctly.\n\n### Standard app build\n\n```powershell\n./scripts/build-windows.ps1\n```\n\n### NSIS installer build\n\n```powershell\n./scripts/build-windows.ps1 -NSIS\n```\n\n## Building for Linux\n\nUse the provided script to ensure Linux bundled files are copied correctly.\n\n### Standard app build\n\n```bash\n./scripts/build-linux.sh\n```\n\n### Custom Linux platform build\n\n```bash\n./scripts/build-linux.sh --platform linux/arm64\n```\n\n## GitHub Actions Release (No Per-Commit Runs)\n\nThis repository includes a release workflow at [.github/workflows/release-windows.yml](.github/workflows/release-windows.yml).\n\nIt is intentionally configured to run only:\n\n- on tag pushes matching `v*` (example: `v1.0.0`)\n- when manually triggered from the Actions tab (`workflow_dispatch`)\n\nIt does **not** run on normal branch commits.\n\nWorkflow output:\n\n- builds a Windows NSIS installer\n- generates `SHA256SUMS.txt`\n- uploads both as workflow artifacts\n- publishes a GitHub Release automatically on tag builds\n\nWhat the script does:\n\n1. Validates `bundle/windows/bin/scrcpy.exe` and `bundle/windows/bin/adb.exe`\n2. Runs `wails build --platform windows/amd64` (plus `--nsis` when requested)\n3. Copies `bundle/windows/bin/*` to `build/bin/bin/`\n\nLinux build script behavior (`scripts/build-linux.sh`):\n\n1. Validates `bundle/linux/bin/scrcpy` and `bundle/linux/bin/adb`\n2. Runs `wails build --platform linux/amd64` (or custom value from `--platform`)\n3. Copies `bundle/linux/bin/*` to `build/bin/bin/`\n\nInstaller behavior (`build/windows/installer/project.nsi`):\n\n- copies app files\n- copies `bundle/windows/bin/*` into `$INSTDIR\\\\bin`\n\n---\n\n## How Executables Are Resolved\n\nBackend executable discovery checks these locations first, then falls back to `PATH`:\n\n1. Directory of the running executable\n2. `\u003cexe-dir\u003e/bin`\n3. `\u003cexe-dir\u003e/resources/bin`\n4. Current working directory\n5. `\u003ccwd\u003e/bin`\n6. `\u003ccwd\u003e/build/bin`\n7. `\u003ccwd\u003e/bundle/\u003cruntime-os\u003e/bin`\n8. System `PATH`\n\nAt launch, the backend also prepends the resolved `adb` directory to `PATH` for the scrcpy process.\n\n---\n\n## Launch Options Coverage\n\nThe UI maps structured options to scrcpy CLI args. Main groups:\n\n- **Device Selection**: serial / USB / TCP-IP, capture source (display/camera)\n- **Video Settings**: max size, bitrate, fps, codec, encoder, orientation, display buffer/id\n- **Camera Mode**: camera id/facing/size/fps/aspect/high-speed\n- **Audio Settings**: source, bitrate, codec, encoder, buffer, duplication\n- **Window Behavior**: title, fullscreen, always-on-top, borderless, position/size\n- **Recording**: enable, format, time limit, no-playback, no-window\n- **Input Control**: no-control, touches, stay-awake, screen behavior, keyboard/mouse/gamepad/otg\n- **Display Features**: print fps\n- **Diagnostics**: require-audio, no-downsize-on-error, extra args\n\nThe backend deduplicates repeated arguments while preserving order.\n\n---\n\n## App Events (Wails Runtime)\n\nFrontend subscribes to these backend events:\n\n- `environment:updated`\n- `devices:updated`\n- `instance:updated`\n- `instance:log`\n\nThese drive live badge updates, device refresh, session tabs, and log streaming.\n\n---\n\n## Project Structure\n\nKey paths:\n\n- `main.go` – Wails app bootstrap\n- `app.go` – backend state, process lifecycle, environment and bundle checks\n- `launch_options.go` – typed launch options + argument builder\n- `frontend/src/App.tsx` – main desktop UI shell\n- `frontend/src/features/launch/` – launch option models and panel\n- `bundle/windows/bin/` – bundled Windows runtime files\n- `bundle/linux/bin/` – bundled Linux runtime files\n- `scripts/build-windows.ps1` – repeatable Windows build script\n- `scripts/build-linux.sh` – repeatable Linux build script\n- `scrcpy-docs/` – local reference notes for scrcpy capabilities\n\n---\n\n## Troubleshooting\n\n### `scrcpy: missing` or `adb: missing`\n\n- Place binaries in `bundle/\u003cruntime-os\u003e/bin/` (for packaged flow), or\n- ensure they are available in one of the discovery paths or system `PATH`\n- click **Refresh** in app\n\n### `bundle: issues`\n\n- Open `bundle/\u003cruntime-os\u003e/bin/required-files.txt`\n- add/correct required runtime files from your scrcpy distribution\n- ensure files exist in `bundle/\u003cruntime-os\u003e/bin/`\n\n### No devices found\n\n- verify USB debugging is enabled on device\n- run `adb devices -l` manually to validate connection\n- check driver/authorization prompts on device\n\n### Launch fails with argument errors\n\n- reset unusual option combinations\n- clear diagnostics/extra args\n- verify selected capture source matches chosen settings\n\n---\n\n## Notes\n\n- Current implementation supports runtime launch on **Windows and Linux**.\n- The repository includes a generated `wailsjs` bridge for Go↔TS calls.\n- Frontend package metadata requires a modern Node runtime, but this project uses **Bun** for Wails frontend tasks.\n\n---\n\n## Local Reference Docs\n\nSee `scrcpy-docs/` for topic-specific notes (audio, video, input, recording, etc.) used while shaping option support.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexuls%2Fscrcpy-gui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnexuls%2Fscrcpy-gui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnexuls%2Fscrcpy-gui/lists"}