Piik/docs/README.md

Piik Documentation

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

For using Piik, troubleshooting or self-hosting, start with the reader documentation · 中文文档中心. This page also indexes developer and maintainer references.

Guides And References

Task	Guide
Use Piik online	Open the online site · Online sharing guide
Watch a friend or share my first screen	Getting started
Choose an App mode or fix sound and connection trouble	First-use help
Page opens but video will not connect / 网页能打开，画面连不上	Connection troubleshooting · 中文排查
Run Piik App, check platform requirements, or build a package	App guide · 中文 App 指南
Try or change the source code	Run from source
Find a directory or the module responsible for a behavior	Repository layout and module map
Find the shared product, design and lifecycle rules	Standards index
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
Translate Piik or improve wording	Translation guide · 中文翻译教程
Check release and platform readiness	Current status

The introduction, getting-started, App, self-hosting, service-management and translation 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:go

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
Camera and Host microphone	Capture scope and limits
Text, reactions and floating room tools	Room-interaction design
Stereo verification and HDR-to-SDR assessment	Media fidelity

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.