AAA
9150e9d312
## Problem and outcome / 问题与结果 Machines with several local addresses could fail before opening Piik, and startup or connection failures were difficult to diagnose. This phase adds Local invitation-address selection and accessible diagnostics, preserves useful startup errors, and repairs media preparation and recovery without changing room authority or routing policy. It also aligns language handling, playback, public downloads and contributor documentation with the resulting behavior. ## Release notes ### 中文 - **多网卡也能正常选择启动方式。** 本地房间在需要时显示网卡名称与局域网地址，供你选择朋友所在的网络；公网邀请和连接已有站点不再因多个局域网地址而无法启动。 - **更容易排查启动和连接问题。** 启动页新增“诊断启动”，同时记录 App 与网页诊断；网页版也有独立诊断入口。启动失败会显示具体原因和重试方法，Windows 双击启动后的错误会停留等待确认。诊断模式下异常退出会保存报告，ZIP 由用户自行保留或清理。 - **减少连接准备中的无谓等待。** 普通候选发现不再等待可选端口映射；修正连接重启时旧候选与完成通知的处理，以及部分准备失败后的反馈。Native 媒体连接可在网络支持时使用 IPv6 直连，同时保留 IPv4 路径。 - **修正分享恢复中的状态问题。** 切换画面后重新计算首播保护所需的新帧；SFU 恢复时应用最新画质设置；一次应答发送失败不再使整个会话失去 Native 接收能力。密码错误提示也进行了去重。 - **改善播放与全屏交互。** 同步 Safari 原生全屏中的播放、音量与退出状态；可操作的视频画面显示手形光标。 - **统一语言匹配并完善翻译贡献。** 简体、繁体中文系统均默认显示简体中文，其余系统默认英文；保留中英文与纯视觉模式快捷切换，提供中英文社区翻译教程和额外语言接入方式。 - **整理下载与官网说明。** Release 附件集中展示三个平台的 App ZIP 和 Server 程序包，源码版本与校验值收进更新说明的折叠区。官网保留内嵌短片，并提供独立观看链接；教程、下载文案和运维指南同步更新。 **升级：** App 请完整解压对应平台的 ZIP 并保留目录结构。服务端按部署指南升级，保留现有配置与 SQLite 数据。此次更新不改变现有通信协议和存储格式。 **测试范围：** 主要验证 Windows App 与桌面浏览器。macOS、Linux 实机采集和移动端、跨公网 IPv6 的更广泛验证仍待完成，欢迎试用反馈。 ### English - **Choose how to start on machines with multiple network addresses.** Local rooms show interface names and invitation addresses when a choice is needed. Public invitations and connections to an existing Site no longer fail because several LAN addresses are available. - **Diagnose startup and connection problems more easily.** The launcher now offers Debug launch for both App and browser diagnostics, alongside a separate browser diagnostics control. Startup failures include their cause and retry guidance; Windows errors remain visible for confirmation after a double-click launch. Failed exits in diagnostic mode save a report. Exported ZIPs remain available until you move or delete them. - **Remove unnecessary connection setup waits.** Ordinary candidate discovery no longer waits for optional gateway mapping. Fixes cover stale candidates and completion signals during ICE restarts, and feedback from failed connection preparation. Native media can use direct IPv6 connections where available while retaining IPv4 paths. - **Keep sharing recovery aligned with the current source and settings.** Source changes count new frames for startup protection, SFU recovery uses the latest quality preferences, and one failed answer submission no longer disables Native receiving for the entire session. Duplicate password-error feedback has also been removed. - **Improve playback and fullscreen interaction.** Safari native fullscreen now synchronizes playback, volume and exit state. Interactive video surfaces show a pointer cursor. - **Align language selection and community translation guidance.** Simplified and Traditional Chinese system locales select Simplified Chinese; other systems default to English. Chinese, English and visual-mode shortcuts remain, with bilingual translation guides and a registration path for additional languages. - **Simplify release downloads and refresh the website.** Release attachments contain the three App ZIPs and the Server runtime archive; source identity and checksums appear in a collapsed section of the release notes. The website keeps its embedded introduction and adds a standalone viewing link, with updated setup, download and operations guidance. **Upgrading:** Extract the complete App ZIP for your platform and keep its directory structure. Follow the deployment guide for Server upgrades, preserving existing configuration and SQLite data. Existing wire contracts and storage formats are unchanged. **Test coverage:** Windows App and desktop browsers are the primary validated paths. Physical macOS/Linux capture, broader mobile coverage and IPv6 across separate public networks remain open; testing and feedback are welcome. ## Verification / 验证 - `npm run check`: PASS, including TypeScript, 807 tests in 60 files and the production Web build. - `npm run check:client`: PASS on Windows, including Go formatting/tests/vet, Windows/Linux core builds and native Windows capture compile/probe. Darwin requires the native macOS CI runner. - `npm run gate:client-media`: PASS with Chrome 152 and a real captured test window on Windows. Two receivers obtained video and audio; live and paused profile changes, recovery frames and cleanup passed. This is a single-machine test, not a public-NAT success-rate measurement. - `npm run gate:client-link`: PASS using the newly packaged Windows App. A separate remote machine fetched its temporary public page and completed the WebSocket upgrade; App exit closed the link and cleanup passed. - Server runtime and Windows App candidate packaging: PASS, including archive identity/checksums and execution from the extracted App ZIP. Native Linux/macOS package checks still run in the publishing pipeline before publication. - `node scripts/check-docs.mjs`, `scripts/check-project-state.ps1`, `git diff --check` and `npm run build:website`: PASS. Seven documentation-size gardening advisories and the existing Vite chunk-size advisory remain non-blocking. - Browser review: English/Chinese website setup and direct-download links, narrow layout and diagnostics/language controls checked. Native popover accessibility correctly exposes expanded/collapsed state without a duplicate attribute owner. - Independent audit found no P0/P1/P2 issues; focused race checks for portmapping and mediaedge passed. Diagnostic archive accumulation is retained by the owner's explicit choice. The currently unreachable language menu placement issue is a first-community-language prerequisite in TODO. Physical macOS/Linux capture, broader mobile behavior, restricted-network/endurance coverage and cross-network Native IPv6 remain explicitly outside this candidate's evidence. ## Impact / 影响 Compatible feature release, planned as v1.2.0 from v1.1.2. Browser/server v23, Native control v9, capture v7 and SQLite schema 2 remain unchanged. No new telemetry service, retry policy or configuration requirement is introduced. Public Demo remains open-entry and P2P-only. NAT-PMP dependency corrections are explicitly deferred to the next release and are not claimed here. The existing product, configuration, translation, research and operations owners were updated. Raw audits, handoffs, diagnostic logs and experimental sources are excluded from the PR.
7.6 KiB
Your first Piik room
English · 简体中文 · Back to Piik
Piik shares one person's screen with up to 20 invited viewers. This guide covers watching, trying the online demo, using Piik App and sharing through an existing site.
Join a room · Online demo · Piik App · Existing site · Troubleshooting
Viewers need a browser and an invitation. To try sharing, use the online demo or Public invite in Piik App.
If Piik shows icons only, choose EN in the header to show the labels used below. 中 switches to Chinese; ✦ returns to the illustrations.
Join a friend's room
- Open the invitation link your friend sent in a desktop or mobile browser.
- Wait for their screen to appear. If the browser blocks autoplay, press Play.
- Move the pointer over the picture or tap it to show the playback bar.
The playback bar controls only your own picture and sound. On a computer, click the picture to pause or resume; double-click to enter or leave fullscreen where supported. On a phone, tap the picture to show the bar and use its buttons. Safari may show system controls in video fullscreen.
Playback controls, at a glance
| Control | What it does |
|---|---|
| Theater mode | Expands the picture inside the browser tab. |
| Fullscreen | Fills your screen. |
| Picture in picture | Opens a floating video where supported. |
| Volume | Goes up to 200% with audio boost, or 100% otherwise. Lower it if the sound distorts. |
With just a four-digit room code, open the same Piik site and choose Join a room. You may need the site's passphrase and the room's password. The host decides whether code entry is available; ask for an invitation link if you cannot join by code.
If an old link no longer works, ask the host for the current invitation. App Local rooms and temporary public invitations end when that App run stops.
Try the online demo
- Open demo.piik.tv in a desktop browser that supports screen sharing.
- Select Start sharing, choose a screen, window or tab, and enable audio if needed and offered by the browser.
- Confirm the preview and select Copy invite link. Open that link on a second device or send it to a friend.
- Select Stop sharing when finished.
The project hosts this site for you. It uses direct media connections (P2P); restrictive networks may load the page but block video.
Share with Piik App
- Download a
piik-apparchive for your platform from GitHub Releases or the Gitee mirror. Extract the whole archive and keep its directory structure intact. - Open
piik-app.exeon Windows,Piik App.appon macOS, or./piik-appon Linux. The launcher opens in your system browser. - Choose Public invite for friends outside your local network, then select Open Piik. Other modes are explained below.
- Choose Start sharing, then select Browser, Apps / Windows, or Screens as available. Pick the actual source and sound option.
- Copy and send the room invitation. Keep both the App and sharing tab open.
| Filename contains | Platform |
|---|---|
windows-amd64 |
Windows x64 |
darwin-arm64 |
Apple silicon; native capture requires macOS 13+ |
linux-amd64 |
Linux x64 |
Windows App and browser sharing are the primary tested paths. The macOS and Linux apps have not yet been tested on physical devices; test results and feedback are welcome. Linux native capture also needs system components. See the App guide for package and runtime details.
Choose an App mode
| Mode | When to choose it | What to keep in mind |
|---|---|---|
| Local room | Friends are on the same local network. | If several Local invitation addresses appear, choose the interface and IP on your friends' network. Your computer must be reachable from theirs. A local site passphrase is optional. |
| Public invite | Friends are elsewhere and you want a temporary invitation. | Needs Internet access. The public address lasts for this App run. |
| Connect to Site | Your group already has a Piik site. | Enter its address; the App adds capture capabilities to the site's sharing page. |
A page that opens does not guarantee a video connection. Public invite gives your room a temporary web address; picture and sound still travel between participants. This mode has no media-server fallback, and the temporary address has no uptime guarantee. All modes need a working UDP media path. The App guide explains the connection setup.
Share from your browser
You need an existing HTTPS site running Piik Server, provided by a friend or administrator. If you do not have one, start with the demo or Piik App. Hosting a site yourself is an advanced option: follow the self-hosting guide for server, HTTPS and network setup.
- Open your group's Piik site on your computer. Enter its site passphrase if asked.
- Choose Start sharing. In the browser picker, select the screen, window or tab you want friends to see, and enable audio if offered.
- Check the preview, then choose Copy invite link and send it to your friends.
- Keep the sharing tab open. Use Pause sharing, Switch source, or Stop sharing when you need them.
Screen capture requires an HTTPS site or localhost. The sources and audio
offered by the picker depend on your browser and operating system.
Invitation links grant access to that room; share them with the people you want there.
When something gets in the way
| What you see | Try this |
|---|---|
| Picture but no sound | Unmute the video. The host should choose a source with shareable audio; if sound was disabled, stop and start sharing with it enabled. App window/screen capture keeps that setting when switching sources. |
| No screen picker | Allow the browser or App to record the screen when the OS asks. Browser capture needs HTTPS or localhost; try sharing from a desktop computer. |
| App startup fails | Read the reason on the page and in the terminal. Reopen the App and enable the chip-shaped Debug launch control after the theme button before trying again. A failed startup then exports a report; its path appears in the terminal. |
| Local invitation will not open | Check that both devices are on the same network and can reach each other. Guest Wi-Fi or firewall rules can block local access. |
| Page opens but video will not connect | Choose Reconnect in the playback bar. If it still fails, check WebRTC connection settings or try a site with media fallback. |
| Sharing stops after sleep or suspension | Wake the device and return to the sharing tab; start sharing again if needed. Browser and OS suspension can interrupt capture or playback. |
For a bug report, include the version, OS/browser, what you expected, and how to reproduce it. Diagnostics and export explains how to collect a local report and what to review before sharing it.
Ready to host a site for your group? Follow self-hosting. For everything else, use the documentation map.