AAA
799d6efb4a
## Problem and outcome / 问题与结果 Browser sharing can remain connected to a local encoding transport that never becomes usable, leaving viewers without frames. This phase bounds that startup at eight seconds and restores ordinary encoding through the existing failure path. It also keeps ready App services running after a browser-open failure, preserves user presentation/playback choices, and aligns room feedback, illustrated hints, metrics and documentation. 部分环境下，本机编码连接一直无法建立会让观众收不到画面。本轮在八秒后进入现有降级流程，同时修复客户端启动移交、播放状态和前端反馈的一致性问题，并更新官网与中英文教程。 Closes #399. Related: #396. The release contains relevant startup/error-handling repairs, but the reporting machine has not been retested. Keep this issue open for a current-build result. #401 (optional Windows capture-border hiding) remains deferred. Release / 发布版本：**v1.3.1**. ## Release notes ### 中文 - 客户端记住上次确认的启动模式；启动移交保留已保存的语言、纯视觉模式和主题选择。 - 系统浏览器未能自动打开时，客户端继续运行，并在终端保留页面地址、重试入口和具体错误。 - 改善浏览器共享画面的启动兜底，避免 App 媒体因短暂信令中断被误判为失败。 - 音轨变化保持现有视频与观众的本机暂停状态；连接恢复和暂停恢复不再重复播放电视开机动画。 - 修复昵称编辑及长昵称查看，减少重复的角色提示，统一人物选择和连接状态的区别。 - 完善房间准入、密码和邀请说明；复制反馈对应当前链接及当前操作，避免迟到结果覆盖新反馈。 - 修正采集参数、统计单位与采样区间的展示，未知参数不再用配置上限代替。 - 统一提示漫画、状态图标与动效，改善选源器还焦、键盘操作、剧场布局和触控目标尺寸。 - 服务端默认支持 20 位观众，可在配置中设为 1–20 位，房主不占观众名额。 - 更新官网、教程入口和中英文说明，清理过时预览及失用代码。 兼容说明：使用旧版 App 连接更新后的站点时，站点会优先保留自己的显示偏好。如需更改语言或主题，请在进入后的页面调整。 ### English - Remember the last confirmed App launch mode and preserve saved language, visual-mode and theme choices during launch handoff. - Keep the App running if the system browser fails to open, with the page address, retry action and error details available in the terminal. - Improve the browser sharing startup fallback and avoid treating brief signaling outages as App media failures. - Keep existing video and local pause state when audio tracks change. Reconnecting and resuming no longer replay the television startup animation over the picture. - Fix nickname editing and full-name access, remove redundant role hints, and distinguish participant selection from connection state. - Clarify room access, passwords and invitations. Copy feedback now belongs to the current link and operation, so late results cannot replace newer feedback. - Correct capture details, metric units and observation intervals. Unknown capture values are no longer replaced with configured ceilings. - Align illustrated hints, status icons and motion. Improve source-picker focus, keyboard operation, theater layout and touch targets. - Default the Server to 20 viewers, configurable from 1 to 20. The host does not count toward that limit. - Update the website, guide links and bilingual instructions, and remove obsolete previews and unused code. Compatibility: when an older App connects to an updated Site, the Site keeps its saved presentation preferences. Change language or theme on the destination page when using an older launcher. ## Verification / 验证 Non-publishing [CI candidate run 34919320511](https://github.com/TNTcraftHIM/Piik/actions/runs/34919320511) passed Go core, race, Web checks, Server/container verification and all three native App package checks at source 188376e8. Subsequent commits only update deployment documentation, status and TODO; documentation/hygiene checks passed. Product inputs are unchanged. - `npm run check`: TypeScript, 64 test files / 854 tests, and the Web production build passed. - `npm run check:client-core`: final Go source passed tests, formatting, vet and core target builds. Windows capture compilation and geometry checks passed earlier in this phase; later edits did not change native capture. - Website build, documentation checks, repository hygiene and diff checks passed. Existing documentation-size and bundle-size warnings remain. - Actual browser flows covered sharing, source changes, pause/resume, late audio, brief signaling loss, invitation/copy feedback, entry preferences, source-picker focus, and narrow layouts. - A local three-viewer P2P relay check covered quality-report expiry, recovery and cleanup without interrupting video. A controlled browser-helper failure returning `0xc0000005` left the real App launcher and Local service available. - Homepage checks covered Chinese/English, light/dark preferences and inline-film open/close after removing the separate-page entry. Limits: no new reporter-machine confirmation for #396 or the Windows URL-handler crash; physical Safari/mobile, macOS/Linux capture and wider public-network/endurance coverage remain deferred. Formal release artifacts will be built from the approved squash-merge revision. Hero-loop controls and video-adjacent tooltip placement remain open design items in TODO. ## Impact / 影响 Compatible patch; signaling, Native control and capture contracts are unchanged. Older App launch handoff keeps the updated Site's saved presentation preferences. The Server's default viewer limit is corrected to 20; an explicit 1–20 configuration remains valid. Service updates retain persisted room authority but restart active media sessions. Deploy the verified immutable Server artifact through the existing bounded health/recovery process. Public Demo remains open and P2P-only; deployment does not enable SFU or change infrastructure/configuration.
136 lines
7.5 KiB
Markdown
136 lines
7.5 KiB
Markdown
# Your first Piik room
|
|
|
|
English · [简体中文](./getting-started.zh-CN.md) · [Back to Piik](../../README.md)
|
|
|
|
Piik shares one person's screen with up to 20 invited viewers. This guide covers
|
|
watching, using Piik online, using Piik App and sharing through an existing site.
|
|
|
|
[Join a room](#join-a-friends-room) · [Use online](#use-piik-online) ·
|
|
[Piik App](#share-with-piik-app) · [Existing site](#share-from-your-browser) ·
|
|
[Troubleshooting](#when-something-gets-in-the-way)
|
|
|
|
Viewers need a browser and an invitation. To start sharing, download Piik App
|
|
and choose **Public invite**. To share without installing, open
|
|
[Piik online](https://demo.piik.tv) and create a room in your browser.
|
|
|
|
## Join a friend's room
|
|
|
|
1. Open the invitation link your friend sent in a desktop or mobile browser.
|
|
2. Wait for their screen to appear. If the browser blocks autoplay, press **Play**.
|
|
3. 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.
|
|
|
|
<details>
|
|
<summary>Playback controls, at a glance</summary>
|
|
|
|
| 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. |
|
|
|
|
</details>
|
|
|
|
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.
|
|
|
|
## Use Piik online
|
|
|
|
1. Open [demo.piik.tv](https://demo.piik.tv) in a desktop browser that supports
|
|
screen sharing.
|
|
2. Select **Start sharing**, choose a screen, window or tab, and enable audio if
|
|
needed and offered by the browser.
|
|
3. Confirm the preview and select **Copy invite link**. Open that link on a
|
|
second device or send it to a friend.
|
|
4. Select **Stop sharing** when finished.
|
|
|
|
The online version is provided by the project. Media travels only between participants (P2P);
|
|
restrictive networks may load the page but block video.
|
|
|
|
## Share with Piik App
|
|
|
|
1. Download a **`piik-app`** archive for your platform from
|
|
[GitHub Releases](https://github.com/TNTcraftHIM/Piik/releases) or the
|
|
[Gitee mirror](https://gitee.com/TNTcraftHIM/Piik/releases). Extract the whole
|
|
archive and keep its directory structure intact.
|
|
2. Open `piik-app.exe` on Windows, `Piik App.app` on macOS, or `./piik-app` on Linux.
|
|
The launcher opens in your system browser.
|
|
3. Choose **Public invite** for friends outside your local network, then select
|
|
**Open Piik**. Other modes are explained below.
|
|
4. Choose **Start sharing**, then select **Browser**, **Apps / Windows**, or
|
|
**Screens** as available. Pick the actual source and sound option.
|
|
5. 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](https://github.com/TNTcraftHIM/Piik/issues).
|
|
Linux native capture also needs [system components](../../native/capture/linux/README.md).
|
|
See the [App guide](../../cmd/piik-app/README.md) 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 entries appear under **Local invitation address**, 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](../../cmd/piik-app/README.md#modes) explains the connection setup.
|
|
|
|
## Share from your browser
|
|
|
|
You need an existing HTTPS site running Piik Server, provided by a friend or
|
|
administrator. You can also use [Piik online](#use-piik-online)
|
|
or [Piik App](#share-with-piik-app). Hosting a site yourself is an advanced option:
|
|
follow the [self-hosting guide](../operations/self-hosting.md) for server, HTTPS
|
|
and network setup.
|
|
|
|
1. Open your group's Piik site on your computer. Enter its site passphrase if asked.
|
|
2. Choose **Start sharing**. In the browser picker, select the screen, window or
|
|
tab you want friends to see, and enable audio if offered.
|
|
3. Check the preview, then choose **Copy invite link** and send it to your friends.
|
|
4. 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](../../cmd/piik-app/README.md#chromium-webrtc-connections) 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](../reference/configuration.md#diagnostics)
|
|
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](../operations/self-hosting.md).
|
|
For everything else, use the [documentation map](../README.md).
|