AAA
d76e94eb71
## Problem and outcome / 问题与结果 Windows App users can now choose whether to show the capture border. The same border owner handles source previews and active capture; unsupported or denied requests keep normal capture available. The source picker distinguishes an absent/incompatible App, unavailable capture capability, failed enumeration and a genuinely empty list. Chrome's pending local-access permission no longer holds optional Viewer reception. This phase also reduces tooltip obstruction and contains a failed Linux encoder output within its own branch. Browser/server v23, Native control v9 and capture v7 remain compatible. Closes #401. ## Release notes ### 中文 这是一次分享体验更新，重点改进 Windows 采集边框、App 选源反馈和提示浮窗，并修复 Linux 采集输出的故障隔离。 - **采集边框可选。** Windows App 选源器新增「显示采集边框」，位于声音开关左侧，默认关闭。支持的系统上，来源预览也会隐藏边框。 - **找不到窗口时，提示更明确。** 区分 App 未连接、版本不兼容、采集不可用和读取失败；授权后可以刷新列表重试。改善 Chrome 首次访问时的观看连接，避免本机授权等待拖慢入座。 - **提示浮窗更顺手。** 统一 500 毫秒悬停延迟，减少对画面和控件的遮挡，改善触屏长按和关闭操作；只用于说明的控件使用普通鼠标光标。 - **Linux 分享更稳。** 修复单路编码输出失败可能连带中断其他输出的问题。 - **排查文档更完整。** 补充 App 来源列表、Windows 10 黄框及浏览器 WebRTC 设置的排查说明。 使用新的采集边框开关，请更新 Windows App 并刷新已打开的网页。Windows 10 没有对应的系统接口，边框仍由系统显示；文档中心提供可选处理方法。系统权限或其他采集会话也可能要求保留边框。 ### English This sharing update improves Windows capture borders, App source selection and tooltips, and fixes failure isolation between Linux capture outputs. - **Choose whether to show the capture border.** The Windows App source picker adds a **Show capture border** switch to the left of audio, off by default. Source previews also hide the border on supported systems. - **Clearer source-selection feedback.** The picker distinguishes an unavailable or incompatible App, unsupported capture and a failed source list. Refresh after granting access to retry. Pending local-access permission in Chrome no longer delays Browser reception for Viewers. - **Less intrusive tooltips.** A consistent 500 ms hover delay, improved placement and touch-hold behavior make guidance easier to read and dismiss. Help-only controls use the ordinary cursor. - **More resilient Linux sharing.** A failed encoder output no longer interrupts healthy sibling outputs. - **More useful troubleshooting.** The documentation covers App source lists, Windows 10 capture borders and browser WebRTC settings. Update the Windows App and refresh open pages to use the capture-border switch. Windows 10 lacks the corresponding system API and retains its system border; an optional procedure is available in the documentation center. System permission or another capture session may also require the border to remain visible. ## Verification / 验证 - `npm run check`: TypeScript, 998 tests and production Web build passed. - `npm run check:go`: Go formatting/tests/vet/target builds and Windows native capture checks passed. macOS cgo builds require their native CI runner. - Documentation, repository hygiene and website build passed. - Real Chrome 152 profiles: first-use local permission, recovery after consent and source-list refresh; optional Viewer discovery before/after consent; App Local without cross-address-space consent. - Public invitation gate: link creation, remote page and WebSocket access, App exit and link retirement passed. - Windows 11 border on/off, source preview and concurrent-capture checks have physical evidence. Tooltip hover, keyboard, touch-hold, dismissal and narrow-layout checks passed. - [Candidate CI](https://github.com/TNTcraftHIM/Piik/actions/runs/35157993032) passed at `1d159831`: Server/container, Windows/Linux/macOS packages, Go race checks and frontend validation. Publication was skipped. - Local Windows ZIP passed packaged startup, capture probing, embedded Web, helper identity/notices and clean-shutdown checks. - Windows H.264 and VP8 Host gates passed live/paused settings, background recovery, source replacement, source-end/restart, decoded Viewer frames and complete resource cleanup. - Final `0b370e6a` differs from the CI candidate only in TODO/status closure. Full Web/Go/native checks and website build passed again. The access/privacy gate passed credential-leak and cleanup checks. ## Impact / 影响 Compatible feature update for **v1.5.0**. No wire or storage version change. Older Apps retain their existing capture behavior through capability negotiation. Publication and matching deployments follow the release workflow. The independent Windows x86 experiment is excluded. Physical 32-bit Windows, macOS/Linux capture, unsupported Windows border control, and actual border-permission denial remain outside this candidate's acceptance evidence. The original missing-window, public-link timeout and URL-handler crash reports still need affected-machine diagnostics.
9.0 KiB
Troubleshooting
English · 简体中文 · Documentation
Find the symptom below and try the suggested checks. Stop when it works; collect a diagnostic report if the problem persists.
Common problems
| 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. |
| No App windows or screens listed | Check the message in the source picker, then follow App source troubleshooting. Browser → Browser picker also offers browser capture. |
| Yellow outline around the shared window or screen | This is Windows' capture indicator. See capture borders for Windows 11 controls and an optional Windows 10 workaround. |
| 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 | Use Reconnect if available, or refresh the viewing page. See connection troubleshooting if it still fails. |
| 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.
App windows or screens are missing
Keep Piik App running on the computer where you are sharing. Open the current site from the App; for a hosted site, use the App's Site mode with that site's address. If the browser asks for local-network access, allow it, then refresh the source list. If access was previously blocked, review this site's browser permissions first.
The source picker distinguishes these outcomes:
| Message | Next step |
|---|---|
| Cannot connect to Piik App | Confirm the App is running and opened this site. Close unused Piik tabs using the App, then refresh the list; up to two pages can use the App's native capture or viewing at once. |
| Piik App and this page are incompatible | Update Piik App and reload the page. |
| Piik App capture is currently unavailable | Check the App diagnostics for capture or encoder availability. Review your encoding setting or use browser capture. |
| Could not read the screen and window list | Refresh to retry. If it keeps failing, export both the App and browser Debug reports. |
| No sources available | The list was read successfully, but this tab has no selectable sources. Check the other source tabs. |
Local-network permission lets the page contact the App. It is separate from the WebRTC media settings described below. An unreachable App alone does not prove that permission was denied.
Yellow capture border on Windows
Windows draws this outline to identify the window or display being captured. On supported Windows versions, the App source picker offers Show capture border, off by default. Windows permissions or another active capture can still require the border. Windows 10 does not provide this control for its capture API.
Optional Windows 10 workaround
DWM Custom Projection Border is a third-party Windhawk mod for x64 Windows that can hide the border while keeping the same capture method. It changes Windows' desktop compositor and affects other apps' capture indicators too. The author shows it working on Windows 10 21H2; this procedure has not been tested with Piik on a Windows 10 device.
- Install Windhawk from its official website.
- In Windhawk's global Settings → Advanced settings → More advanced settings,
append
dwm.exeto Process inclusion list and save. Keep existing entries. - Find and install DWM Custom Projection Border. In the mod's settings, turn on Disable border and save.
- Stop and restart sharing in Piik, then check whether the border disappears.
To undo this, disable the mod and restart sharing. Remove the dwm.exe entry
if you added it only for this mod. If desktop problems appear or a Windows
update breaks compatibility, disable the mod first.
See the mod author's instructions and Windhawk's process settings for current setup details.
When video will not connect
No media route available means Piik has not found a working path to deliver the picture to your device. Loading the page and receiving media use different connections, so one can work while the other fails.
NAT (Network Address Translation) lets several devices share an Internet address. Routers and providers differ in how they map addresses and admit incoming traffic; some combinations make direct connections difficult. Firewalls and browser policies can also block media. The message alone does not identify the cause.
Try these in order, stopping when the picture arrives:
- Retry the viewing page. Choose Reconnect if it is available. If it is disabled or does not help, refresh the viewing page or reopen the invitation. Let each connection attempt finish. One or two fresh attempts can be worth trying; repeated refreshes cannot remove a network restriction.
- Check WebRTC settings in the viewing browser. A browser setting or VPN/privacy extension that disables WebRTC or non-proxied UDP can prevent viewing, even while the page loads. Merely hiding local IP addresses does not necessarily block WebRTC. Try the same invitation in a browser profile without those extensions, or review the specific WebRTC setting, then reload Piik. See browser connection settings for examples and the privacy tradeoff; keep unrelated protections enabled.
- Try another network. For example, test a phone hotspot. If you use a VPN or proxy, check its UDP policy; ask the administrator on a managed network.
- Enable usable IPv6. Check that your provider, router and device support it. When both peers have working IPv6, Piik can try that direct path alongside IPv4. It does not bypass firewall rules; keep IPv4 enabled too.
- Check your own router, if you manage it. On a trusted home network, supported UPnP, PCP or NAT-PMP settings can let the App's native media path request a port mapping. Browser-only capture does not request these mappings. If a modem and router both perform NAT, follow your model's bridge/AP-mode instructions to remove the extra layer. Carrier-grade NAT is upstream of your router; ask your provider about available public IPv4 or IPv6 service. Back up settings before changing the router's operating mode.
- Invite a friend on another network. A Viewer who can receive the picture and has spare forwarding capacity may give Piik another path to you. Piik chooses this automatically; extra people help only when those connections work.
- Use a site with media fallback. Its operator must enable SFU forwarding,
and the Host must turn off Privacy mode before sharing. The public
demo.piik.tvsite and the App's Public invite mode do not provide SFU. Self-hosting is an advanced option. Both P2P and SFU media currently use UDP; a network that blocks UDP entirely still needs a different network or an administrator's help.
Router menus vary by model. These manufacturer guides explain IPv6 prerequisites, UPnP, and double NAT with a modem and router. The WebRTC connection guide explains discovery and connection checks in more technical detail.
If these steps do not help, collect a Debug report from the affected Viewer and, if possible, the Host for the same attempt. Include the time, Piik version and network type when reporting the problem.
Ready to host a site for your group? Follow self-hosting. For other guides, return to the documentation home.