AAA
a9b7507488
## Problem and outcome / 问题与结果 Add camera sharing and Host microphone commentary to the existing Host workflow, with shared source cards, device selection, input gain and grouped sharing settings. Browser and native capture keep one outgoing audio track and the existing room/media owners. Include optional password-free invitations, public-tunnel protocol fallback, capture retirement and App-discovery feedback fixes. This is the complete capture maintenance phase; interaction, x86 capture and 4K experiments are excluded. ## Release notes ### 中文 这次更新让分享多了两种表达方式：用摄像头展示现场，用麦克风边分享边讲解。 分享设置也重新整理，并修复了公网邀请、音视频切换和采集退出中的一些问题。 #### 新功能与使用改进 - **摄像头分享**：在原有选源器中选择摄像头，支持设备选择和画面预览；支持摄像头访问的手机浏览器也可使用。 - **房主麦克风**：浏览器分享和 App 原生采集均可混入房主声音，支持选择麦克风、静音和输入音量调节。观众仍使用原有音量控件收听。 - **更集中的分享设置**：画质、声音和详细连接选项集中在画面下方，常用操作保持直接可用，并调整了窄屏播控与等待提示的布局。 - **邀请链接可选择是否免密加入**：关闭后，链接不再附带免密邀请；接收者按当前站点和房间的准入设置加入。 - **更清晰的启动设置**：可选站点口令默认收起，已有站点地址提供 `demo.piik.tv` 建议，并澄清 NAT 增强选项的含义。 #### 修复 - 公网邀请在 UDP 受限但 TCP 可用的网络中，可使用隧道组件原有的协议回退，减少这类启动失败。 - 调整音频时保留健康的视频发送；修复旧采集事件干扰当前分享的情况。 - 停止或取消原生采集时，先正常释放采集会话，超时才强制退出；修复本地复现的强制终止后 Windows 黄框残留问题。 - 从 App 打开的页面无法连接 App 时，选源器保留明确提示，不再只剩浏览器和摄像头选项而缺少原因说明。 #### 使用说明 摄像头和音频能力取决于系统、浏览器与设备。Windows 仍可能因权限或其他采集要求显示边框。 使用新增的 App 麦克风功能，请更新 App；连接自部署站点时，也请更新站点以获得对应页面功能。 ### English This update adds camera sharing and Host microphone commentary, alongside a clearer sharing-settings layout. It also fixes several public-invitation, audio/video transition and capture-shutdown issues. #### Features and usability - **Camera sharing:** choose a camera in the existing source picker, with device selection and thumbnail previews. Phone browsers with camera access can share too. - **Host microphone:** add commentary to Browser sharing or App-native capture, with device selection, mute and input gain. Viewers listen through their existing volume controls. - **Grouped sharing settings:** picture quality, sound and detailed connection options sit below the picture, while frequent actions remain directly available. Narrow-screen playback and waiting layouts are refined. - **Optional password-free invitations:** turn this off to copy a link without an invitation credential. Recipients then follow the site's and room's current admission settings. - **Clearer startup settings:** optional site-password settings are collapsed, the existing-site field suggests `demo.piik.tv`, and the NAT enhancement option has a clearer description. #### Fixes - Public invitations can use the tunnel component's existing protocol fallback when UDP is blocked but TCP is available, reducing startup failures on those networks. - Audio changes preserve healthy video sending. Retired capture events no longer affect an active share. - Stopping or cancelling native capture releases the capture session before enforcing the shutdown deadline. This fixes a locally reproduced case where forced termination left a Windows capture border behind. - Pages opened from the App keep a clear connection warning in the source picker when the App cannot be reached, instead of showing only Browser and Camera without an explanation. #### Usage notes Camera and audio support depend on the OS, browser and device. Windows may still require a border because of permissions or another active capture. Update the App to use its new microphone feature; update self-hosted sites as well to receive the matching page controls. ## Verification / 验证 - npm run check: 74 files / 1054 tests passed, TypeScript and production Web build passed. - npm run check:go: Go tests, vet, target builds and Windows native compile/regressions passed. - npm run gate:app-native-host: actual Windows H264 Host/Viewer, live/paused profile changes, quiet-source recovery, source replacement/failure, subsequent share and cleanup passed. - Windows 11 capture-border check: parent cancellation retires the actual WGC session and clears its border; subprocess tests verify normal, concurrent and timed-out retirement. - Website build, scripts typecheck, documentation and repository hygiene passed. - Native macOS/Linux packaging and Linux race checks run in CI before publication. Physical phone camera and real audio-level/echo/multiple-device coverage remain recorded limits; the owner authorized release with those limits. No universal NAT/border fix is claimed. ## Impact / 影响 Compatible feature release **v1.6.0**, explicitly approved by the owner. Browser/Server v23, Native control v9 and capture v7 stay unchanged; new App microphone commands use capability negotiation. No new dependency, port, media route, room lifecycle or storage migration. Published Server cutover retains configuration and room storage and uses bounded health checks with the previous executable available for rollback. Source, tests and owned documentation ship together; exact artifact/deployment identities remain outside the repo.
10 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 source sound | Unmute the video. The host should choose a source with shareable audio and enable sound in the source picker. |
| Cannot hear the host's voice | The host can enable Microphone below the picture, then check the selected input and its volume in Sharing settings → Sound. Check the device connection and microphone permission. If the control is unavailable, update the App and refresh the page. |
| 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.
Windows 11: the border is still visible
- Select Apps / Windows or Screens in Piik and leave Show capture border off. A Browser-selected source uses the browser's own capture indicator.
- Stop other apps or tabs capturing the same window/display, then restart sharing.
- If Windows denied borderless capture, review Screenshot borders in Windows
privacy settings. Its settings page can also be opened with
ms-settings:privacy-graphicscapturewithoutborderfrom Win+R, when available.
Windows requires consent and can retain the border when another capture requests it (Microsoft's API documentation). If it persists, include the Windows version, selected source type and an App diagnostic report with your feedback.
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.