Piik/docs/README.md

Piik Documentation

About Piik · 中文介绍 · 中文上手指南

Guides And References

Task	Guide
Try the online demo	Online demo · Demo steps
Watch a friend or share my first screen	Getting started
Choose an App mode or fix sound and connection trouble	First-use help
Run Piik App, check platform requirements, or build a package	App guide
Try or change the source code	Run from source
Find a directory or the module responsible for a behavior	Repository layout and module map
Host a site for my group	Self-hosting · 中文部署
Keep a server running with systemd or Docker	Service management
Set passwords, ports, or room storage	Configuration
Update my server	Server updates
Build, publish or recover a maintained release	Maintainer release tooling
Send a useful bug report	Diagnostics and export
Check release and platform readiness	Current status

The introduction, getting-started and self-hosting guides are available in English and Chinese. Technical references keep one shared version.

Run from source

You can try the Browser application locally with Node from .node-version, npm from package.json, and Go 1.26 from go.mod. Run these commands from the repository root.

Start the web UI:

npm ci
npm run dev

In a second terminal, start the server. For a POSIX shell:

PORT=8788 PUBLIC_BASE_URL=http://localhost:8787 go run ./cmd/piik-server

Or in PowerShell:

$env:PORT = '8788'
$env:PUBLIC_BASE_URL = 'http://localhost:8787'
go build -o build/dev/piik-server.exe ./cmd/piik-server
./build/dev/piik-server.exe

The fixed Windows executable path avoids repeated firewall prompts from go run. Open localhost:8787, start sharing, and open the invitation in another browser tab to try watching. This localhost invitation stays on your computer; remote invitations need a reachable origin as described in configuration. Browser capture requires localhost or HTTPS.

For the self-contained App, follow App development and packaging, including the platform's native capture requirements.

Work on Piik

Contributing covers the workflow and choosing focused checks. The main verification commands are:

npm run check
npm run check:client

Use the naming and copy guide for product names, commands, role labels and Chinese/English voice. Piik-owned code uses MIT; see the licensing guide for third-party components.

For the public website, see the introduction design and website preview and publishing.

Understand the product

Topic	Its reference
Invitations, room codes and passwords	Rooms and access
How viewers connect	Routing and transport
Screen capture, quality controls and sound	Media quality
Host and viewer behavior	Presentation and lifecycle
Why a design was chosen	Architecture decisions
Measurements and platform limits	Research and verification status

Shared conventions

When changing…	Follow this owner
Module responsibilities or interfaces	Engineering and contract map
Product/tool names, role labels or copy	Naming and copy
UI colour, illustration, motion or layout	Visual language
Overlays, titles or state indicators	Media status
Releases, protocols or stored formats	Versions and compatibility
Main protection or automatic publishing	GitHub operations
Documentation or a duplicated rule	Documentation ownership
Checks, PRs, integration or cleanup	Contributing

For ongoing work, use TODO. Project memory provides the compact product map; status indexes current source and deployment boundaries. Completed work lives in Git history and pull requests.