Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

8.6 KB
Raw Blame

Piik App Development

Build, package and verify Piik App from the repository root. For installation, mode selection and diagnostics, use the App guide.

Run From Source

Use the Node/npm/Go versions in Run from source. The binary embeds the Browser assets, so build them from the repository root first:

npm ci
npm run build:web

On Linux or macOS:

go run ./cmd/piik-app

On Windows, build and run from a stable executable path for the system firewall:

go build -o build/dev/piik-app.exe ./cmd/piik-app
./build/dev/piik-app.exe

These commands build the App only. Choose Local room or open a Piik Site for Browser capture. Native capture and Public invite need their helpers; use --capture-process / --tunnel-process to select built helpers, or follow packaging for a complete bundle.

The repository-level entry used locally and by CI is:

npm run check:go

On Windows, its generated App, capture, and media-test executables are written to the ignored repository build/go-check directory and reused on the next run. This keeps the executable identity stable for the system firewall; the files are local build output and are never packaged or committed.

It runs Go formatting, unit tests, vet, and Windows/Linux cgo-free cross-builds. The Darwin App and peer gate build only on macOS with cgo enabled and an installed SDK; other hosts report that skipped platform explicitly. The pinned media dependency's Darwin CPU statistics use Mach APIs through cgo, so a Windows or Linux core check does not establish Darwin build acceptance. The check compiles the current platform's isolated capture process and validates its bounded capability response. macOS additionally encodes one in-memory hardware H.264 IDR; Linux probes the Portal/PipeWire/GStreamer adapter. Real capture, GPU attribution, Browser decode, and public-network paths remain explicit physical gates rather than environment-dependent unit tests.

App and Hosted share the Go room service. The Browser UI coordinates native capture and Viewer receive/relay through the App's local control service; Viewer receive/relay remains available without a supported native capture encoder. Use the module map and contract map to find the source owners. The candidate packager checks that capture helpers match the App's contract.

Packaged builds report the product version and source SHA in the terminal and diagnostics. Versioning explains build identity and update notices; GitHub operations describes automatic publication.

Packaging

From a clean revision, build the application release and run the platform's candidate wrapper on its native operating system. The wrapper builds capture, verifies the pinned public-link helper, and assembles and checks the App:

node scripts/package-server-release.mjs /outside/repository/app-release
node scripts/package-app-candidate.mjs /outside/repository/app-release windows-amd64 /outside/repository/app-candidate

Supported targets are windows-amd64, linux-amd64, linux-arm64, darwin-arm64 and darwin-amd64. Use the matching target name in the command above. Darwin assembly requires a native macOS runner with its SDK and enables cgo; Windows and Linux assembly keep cgo disabled. The result is a ZIP bundle and SHA-256 file. Manual sidecar assembly, explicit CI packaging, Release publication and updates are documented in deployment; creating a candidate does not publish it.

The App runtime contains the following files. On macOS they live inside Piik App.app/Contents/MacOS; move the whole .app when installing it.

piik-app[.exe]
REVISION
LICENSE
THIRD-PARTY-NOTICES.txt
runtime/native/piik-capture[.exe] # supported native-media packages
runtime/tunnel/cloudflared[.exe] # packages that support --link

The executable embeds the Browser assets of the consumed application release and carries that same full Git revision as the package REVISION. App/Site interoperability follows the public compatibility contract.

For a native Host smoke run, launch the App and select a window in the Host page, then open its invitation on another device. Choose the mode for that network as described in the App guide.

Optional Gamepad Drivers

App packaging does not download or include optional input SDKs or drivers. The Windows adapter calls an externally installed ViGEmBus through its public bus interface; Linux uses system uinput and macOS uses native virtual HID APIs. Driver availability and permission are checked by the platform adapter. See the gamepad setup guide for Host requirements and platform support.

Desktop Icons

The Windows App embeds the shared Piik mark through the cmd/piik-app/piik_windows_amd64.syso resource; the platform suffix keeps that Windows resource out of Linux and macOS builds. Linux packages include the standard share/applications desktop entry and hicolor icon. macOS packages include Piik App.app with an ICNS resource, the App executable and its helpers. For terminal use, the executable is "Piik App.app/Contents/MacOS/piik-app".

The editable badge is public/favicon.svg. Export it at 16/24/32/48/64/128/256 px as PNG entries in cmd/piik-app/piik.ico; the package builder derives Linux and macOS icons from those entries. Keep the website exports in sync: public/favicon.png at 96 px, and public/favicon.ico with 16/32/48 px entries. Check actual small sizes on light and dark backgrounds. Render the SVG at each target size so its small-icon styling applies. Then regenerate the Windows resource from the repository root:

go run github.com/akavel/[email protected] -ico cmd/piik-app/piik.ico -arch amd64 -o cmd/piik-app/piik_windows_amd64.syso

Gates

The Local gate starts the packaged process, loads a real built page in Chromium, proves bootstrap access and LAN invitation construction, and verifies complete process/profile cleanup. The loopback gate separately proves Site access with and without Chromium Local Network Access permission. Environment syntax below is POSIX; use equivalent variables on Windows. For the loopback gate, provide a reachable Piik Site and run once without PIIK_CLIENT_GATE_GRANT_LOOPBACK, then again with PIIK_CLIENT_GATE_GRANT_LOOPBACK=true to cover both permission states.

PIIK_CLIENT_LOCAL_GATE=true \
CHROME_PATH=/path/to/chrome \
PIIK_CLIENT_EXE=/path/to/piik-app \
PIIK_CLIENT_GATE_LAN_ADDRESS=192.168.1.10 \
npm run gate:app-local

PIIK_CLIENT_LOOPBACK_GATE=true \
CHROME_PATH=/path/to/chrome \
PIIK_CLIENT_EXE=/path/to/piik-app \
PIIK_CLIENT_GATE_SITE_URL=https://<test-site> \
npm run probe:app-loopback

PIIK_CLIENT_MEDIA_GATE=true \
CHROME_PATH=/path/to/chrome \
PIIK_CLIENT_GATE_STUN_URLS=stun:<stun-host>:3478 \
npm run gate:app-media

PIIK_CLIENT_NATIVE_HOST_GATE=true \
CHROME_PATH=/path/to/chrome \
PIIK_GO=/path/to/go \
npm run gate:app-native-host

PIIK_CLIENT_NATIVE_HOST_GATE=true \
PIIK_CLIENT_LINK_MEDIA_GATE=true \
CHROME_PATH=/path/to/chrome \
PIIK_GO=/path/to/go \
PIIK_CLOUDFLARED=/path/to/cloudflared \
PIIK_REMOTE_HOST=<public-test-host> \
PIIK_REMOTE_USER=<ssh-user> \
PIIK_REMOTE_SSH_KEY=/path/to/key \
npm run gate:app-native-host

PIIK_CLIENT_LINK_GATE=true \
PIIK_GO=/path/to/go \
PIIK_CLOUDFLARED=/path/to/cloudflared \
PIIK_REMOTE_HOST=<public-test-host> \
PIIK_REMOTE_USER=<ssh-user> \
PIIK_REMOTE_SSH_KEY=/path/to/key \
npm run gate:app-link

The Windows media gate proves one hardware-H.264 capture generation, shared Pion source, Browser decode, PLI recovery, and STUN candidate gathering. The native Host gate proves room creation and native video delivery through the current route; native audio is included when the capability probe and target OS support it. The one-link media variant carries signaling through the App's temporary public origin and requires direct video RTP delivery to an independent Linux peer, with a selected srflx or prflx candidate. SSH only runs the remote probe; media never travels through it. Without a remote host, this variant checks decoded media in a local Browser through the public invitation; that does not establish cross-network connectivity. Native P2P quality evidence and embedded SFU delivery have explicit gates. macOS and Linux capture still require physical desktop/media gates; CI compilation and package smoke do not substitute for them.