Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

feat(app): improve sharing controls, recovery and troubleshooting

AAAe3ada873fd16
diff --git a/docs/adr/0008-window-scoped-audio-capture.md b/docs/adr/0008-window-scoped-audio-capture.md
index 820837d0..bca4a55c 100644
--- a/docs/adr/0008-window-scoped-audio-capture.md
+++ b/docs/adr/0008-window-scoped-audio-capture.md
@@ -2,7 +2,7 @@
- Status: accepted for Browser capture and the Windows App audio paths
- Date: 2026-08-21
-- Last updated: 2026-10-01
+- Last updated: 2026-10-06
## Context
@@ -39,8 +39,11 @@ platform probe and physical gate report it.
[ADR-0010](./0010-cross-platform-client-runtime.md); measurements are in
[Native App media](../research/native-client-media.md).
7. Windows App screen sharing can optionally exclude one selected process tree
- through WASAPI's exclusion mode, on build 20348+ with a successful capability
- probe. This mode spans all render endpoints; it is not restricted to the
+ through WASAPI's exclusion mode after successful activation of that mode.
+ Probe Windows 10 build 19041+ to include backported implementations, following
+ the same capability boundary as application capture. Microsoft's documented
+ minimum remains 20348; a Windows version alone does not establish support.
+ This mode spans all render endpoints; it is not restricted to the
default playback device. Reuse source enumeration and the existing PCM/mixed
output. Generic Browser capture and arbitrary unrelated process sets are not
covered. [Media quality](../standards/media-quality.md#screen-audio) owns
@@ -68,3 +71,4 @@ Negative:
- [Windows application loopback](https://learn.microsoft.com/en-us/samples/microsoft/windows-classic-samples/applicationloopbackaudio-sample/)
- [Windows Graphics Capture](https://learn.microsoft.com/en-us/windows/apps/develop/media-authoring-processing/screen-capture)
- [WASAPI process-loopback activation](https://learn.microsoft.com/en-us/windows/win32/api/audioclientactivationparams/ns-audioclientactivationparams-audioclient_process_loopback_params)
+- [OBS application-audio platform support](https://obsproject.com/kb/application-audio-capture-guide)
diff --git a/docs/guide/README.md b/docs/guide/README.md
index f4a36d39..7fb1cec6 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -19,9 +19,10 @@ Choose a guide for what you want to do.
[Troubleshooting](./troubleshooting.md) starts from the symptom you see. Common checks:
+- [Public invitation failure or 1033](./troubleshooting.md#public-invitation-fails-or-shows-1033), or [room creation returns 403](./troubleshooting.md#room-creation-returns-403).
+- [Sharing will not start](./troubleshooting.md#sharing-does-not-start-after-source-selection), [missing App sources](./troubleshooting.md#app-windows-or-screens-are-missing), or [H264 and graphics checks](./troubleshooting.md#h264-sharing-fails-on-windows).
- [Video will not connect](./troubleshooting.md#when-video-will-not-connect), including WebRTC settings and campus networks.
-- [H264 sharing or graphics problems](./troubleshooting.md#h264-sharing-fails-on-windows).
-- [Missing App sources](./troubleshooting.md#app-windows-or-screens-are-missing) or [room creation returns 403](./troubleshooting.md#room-creation-returns-403).
+- [Blur or stuttering](./troubleshooting.md#picture-blurs-stutters-or-stops), or [HDR overexposure](./troubleshooting.md#hdr-picture-looks-too-bright-or-washed-out).
Still stuck? [Report a problem](https://github.com/TNTcraftHIM/Piik/issues/new/choose)
with your version, system, browser and reproduction steps. The
diff --git a/docs/guide/README.zh-CN.md b/docs/guide/README.zh-CN.md
index 375b2b36..8063179b 100644
--- a/docs/guide/README.zh-CN.md
+++ b/docs/guide/README.zh-CN.md
@@ -19,9 +19,10 @@
[问题排查](./troubleshooting.zh-CN.md)按遇到的现象提供处理步骤,常用入口:
+- [公网邀请失败或 1033](./troubleshooting.zh-CN.md#公网邀请创建失败或出现-1033)、[创建房间返回 403](./troubleshooting.zh-CN.md#创建房间返回-403)。
+- [无法开始分享](./troubleshooting.zh-CN.md#选源后无法开始分享)、[App 找不到来源](./troubleshooting.zh-CN.md#app-找不到窗口或屏幕)、[H264 与显卡排查](./troubleshooting.zh-CN.md#windows-上-h264-分享失败)。
- [画面连接不上](./troubleshooting.zh-CN.md#画面连接不上),包括 WebRTC 设置与校园网问题。
-- [H264 分享失败与显卡排查](./troubleshooting.zh-CN.md#windows-上-h264-分享失败)。
-- [App 找不到来源](./troubleshooting.zh-CN.md#app-找不到窗口或屏幕)或[创建房间返回 403](./troubleshooting.zh-CN.md#创建房间返回-403)。
+- [模糊或卡顿](./troubleshooting.zh-CN.md#画面模糊卡顿或中断)、[HDR 过曝](./troubleshooting.zh-CN.md#hdr-画面过亮或颜色发白)。
仍然没解决?可以[反馈问题](https://github.com/TNTcraftHIM/Piik/issues/new/choose),
附上版本、系统、浏览器和复现步骤。需要收集报告时,参阅
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 0c11a204..889c079f 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -31,7 +31,7 @@ and use its buttons. Safari may show system controls in video fullscreen.
| Control | What it does |
| --- | --- |
| **Theater mode** | Expands the picture inside the browser tab. |
-| **Fullscreen** | Fills your screen. |
+| **Fullscreen** | Uses the full screen while keeping the picture's proportions; black bars can remain when they differ from 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. |
@@ -145,7 +145,7 @@ sharing to allow that fallback. The project's online site uses P2P only.
## Add your voice
While sharing, select **Microphone** below the picture and
-allow microphone access. Select it again to mute. Open **Sharing settings** below the picture
+allow microphone access. Select it again to mute. Open **Settings → Sound** below the picture
to choose a microphone and adjust its input volume.
The default volume is 100%, with up to 200% available.
Source audio and your voice reach viewers together. The Host preview stays muted.
@@ -176,10 +176,15 @@ This excludes one process and its children. Other apps remain audible, including
those playing through other output devices.
It does not mute your Piik microphone or prevent speaker sound reaching a microphone.
-If the excluded app closes or restarts, source audio stops. Use **Switch source**
-and select it again. Turning source audio off retains the exclusion choice;
+While sharing, use **Sharing settings → Sound** to change system sound or the
+excluded app without stopping the share. If the app closes or restarts, source
+audio stops; refresh the application list and select it again.
+Turning source audio off retains the exclusion choice;
select **None** to restore unfiltered system audio. This control requires an updated page and a Windows App
whose capability probe supports process exclusion; it is not a Browser-capture filter.
+Windows 10 support depends on system updates and the actual capability check.
+If the option is absent, share a single application window or route the voice
+app to a different playback device.
## Chat and reactions
diff --git a/docs/guide/getting-started.zh-CN.md b/docs/guide/getting-started.zh-CN.md
index ab383054..07b8d0b1 100644
--- a/docs/guide/getting-started.zh-CN.md
+++ b/docs/guide/getting-started.zh-CN.md
@@ -29,7 +29,7 @@ Piik 支持一位房主分享屏幕,最多 20 位受邀观众通过浏览器
| 按钮 | 作用 |
| --- | --- |
| **剧场模式** | 在浏览器标签页内展开画面。 |
-| **全屏观看** | 让画面铺满屏幕。 |
+| **全屏观看** | 全屏显示并保持原始比例;画面与屏幕比例不同时会留边。 |
| **悬浮小窗** | 浏览器支持时,把视频放进独立小窗。 |
| **音量** | 支持增强时最高 200%,否则最高 100%;声音失真时调低一些。 |
@@ -128,7 +128,7 @@ Linux 原生采集还需要[系统组件](../../native/capture/linux/README.md)
## 加上自己的声音
分享时,点击画面下方的 **麦克风**,并允许访问。
-再次点击即可静音。在画面下方的 **分享设置** 中可以选择麦克风和调节输入音量,默认 100%,最高可调至 200%。
+再次点击即可静音。在画面下方的 **设置 → 声音** 中可以选择麦克风和调节输入音量,默认 100%,最高可调至 200%。
观众会同时听到来源声音和你的解说;房主本机预览保持静音。
摄像头分享不会自动开启麦克风。App 的 **程序 / 窗口** 和 **屏幕** 采集也使用同一组控件,
@@ -152,9 +152,11 @@ Linux 原生采集还需要[系统组件](../../native/capture/linux/README.md)
其他应用的声音仍会被分享,包括输出到其他播放设备的声音。
它不影响 Piik 麦克风,也不能消除扬声器被麦克风收音产生的回声。
-所选应用关闭或重启后,来源声音会停止;请通过 **切换来源** 重新选择。
+开播后,可在 **分享设置 → 声音** 中调整系统声音和排除的应用,无需停止分享。
+所选应用关闭或重启后,来源声音会停止;请刷新应用列表并重新选择。
暂时关闭来源声音会保留排除选择;需要恢复完整的系统声音时,选择 **不排除**。
此控件需要新版页面和通过进程排除能力检测的 Windows App,不适用于浏览器自带的分享选择器。
+Windows 10 是否支持取决于系统更新与实际检测;未显示此选项时,可改为分享单个应用窗口,或将语音软件输出到另一播放设备。
## 聊天与表情
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index a8e6f41f..22d4d9e9 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -9,24 +9,59 @@ collect a diagnostic report if the problem persists.
| 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. |
+| App startup fails, or no page opens automatically | Read the reason on the page and in the terminal. If the App is still running, copy its address into your browser. See [App diagnostics](../../cmd/piik-app/README.md#diagnostics) to collect a report; if Local mode lists several addresses, choose an adapter and IP on the launch page. |
+| Public invitation fails to start, or a link shows 1033 | Check the host's App and current link using [public invitation troubleshooting](#public-invitation-fails-or-shows-1033). |
+| 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. |
+| Room code says the room does not exist | Codes work only on the site where the room was created. Open the host's full invitation link; see [joining a room](./getting-started.md#join-a-friends-room). |
+| Cannot create a room (403) | On a self-hosted site, ask the administrator to check the [allowed site address](#room-creation-returns-403). |
| 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](#app-windows-or-screens-are-missing). **Browser** → **Choose what to share** opens the browser's screen, window or tab chooser. |
+| Sharing fails after selecting a source | Click the error icon below the TV for details and guidance, then follow [sharing startup checks](#sharing-does-not-start-after-source-selection). |
| H264 fails to start, or sharing stops just after source selection | Try **Auto** or **VP8**, then follow [Windows H264 and graphics checks](#h264-sharing-fails-on-windows). |
+| Game capture is black, shows only the desktop, or stops when entering the game | Compare sources and window modes using [game capture checks](#game-capture-is-black-or-sharing-stops). |
+| HDR picture looks too bright or washed out | On Windows, try App capture or temporarily turn off HDR; see [HDR capture](#hdr-picture-looks-too-bright-or-washed-out). |
| Yellow outline around the shared window or screen | This is Windows' capture indicator. See [capture borders](#yellow-capture-border-on-windows) 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. |
-| Cannot create a room (403) | On a self-hosted site, ask the administrator to check the [allowed site address](#room-creation-returns-403). |
+| Picture but no source sound | Unmute the video. The host should choose a source with shareable audio and enable sound in the source picker. Camera video and audio inputs are selected separately; see [audio settings](./getting-started.md#add-your-voice). |
+| Cannot hear the host's voice | The host can enable **Microphone** below the picture, then check the selected input and its volume in **Settings → Sound**. Check the device connection and microphone permission. If the control is unavailable, update the App and refresh the page. |
+| Screen sharing includes a voice app's audio | Windows App screen capture can [exclude application audio](./getting-started.md#exclude-a-voice-app-from-screen-audio). This does not remove echo from speakers picked up by a microphone. |
| Page opens but video will not connect | Use **Reconnect** if available, or refresh the viewing page. See [connection troubleshooting](#when-video-will-not-connect) if it still fails. |
| WebRTC or IP-leak protection is enabled | Check whether it blocks media connections using [browser WebRTC settings](#browser-webrtc-restrictions). |
| Connection fails on a campus or restricted network | Compare with a phone hotspot, then consider a [site with SFU forwarding](#campus-networks-and-strict-nat). |
+| Picture repeatedly blurs, stutters or stops | Identify who is affected, then follow [picture quality and interruption checks](#picture-blurs-stutters-or-stops). |
+| Phone fullscreen has black bars, or the button does not work | Video keeps its proportions; try landscape orientation and the playback bar's **Fullscreen** button. System video fullscreen depends on the browser. See [viewing controls](./getting-started.md#join-a-friends-room). |
| 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](../../cmd/piik-app/README.md#diagnostics)
explains how to collect a local report and what to review before sharing it.
+## Sharing does not start after source selection
+
+The error icon below the TV explains the current failure. Click it for suggested
+checks, a copyable failure summary and browser diagnostics. The summary contains
+the Web version, message and error code, without invitation links or source names.
+
+- **App disconnected or request timed out:** check that the App is running and
+ responding, open this site from the App, then refresh. Allow local network
+ access if the browser asks. A timeout alone does not establish a graphics fault.
+- **App could not start the selected source:** try an ordinary window or screen,
+ then compare with the **Browser** source picker. On Windows, try **Auto** or
+ **VP8** and follow [graphics checks](#h264-sharing-fails-on-windows).
+- **Browser cannot read the source or permission is missing:** keep the source
+ open, allow screen recording and select the source again from the sharing page.
+ For a camera, also check whether another application has exclusive use of it.
+- **Media connection failed:** check [browser WebRTC settings](#browser-webrtc-restrictions)
+ and local network permission. For **room creation HTTP 403**, use the next section.
+
+Stop when sharing works. Otherwise, enable diagnostics before reproducing it once:
+the Web button collects browser reports only. For App capture, also enable
+**Debug launch** on its mode selection page, then press `D` in the terminal to export.
+Send the reports from that attempt with the copied failure summary and the source
+type you selected. You can still report without logs; a generic failure screenshot
+alone usually cannot distinguish capture, encoding and connection causes.
+Logs stay on your device; review private information before sharing them.
+See [diagnostics and export](../../cmd/piik-app/README.md#diagnostics) for details.
+
## Room creation returns 403
Piik rejects room creation from a browser address that the server has not allowed,
@@ -73,7 +108,7 @@ If selecting a window or screen returns you to the start screen, or reports a
sharing failure, it may involve capture, encoding or the Browser-to-App media
connection. The message alone does not identify a graphics-driver problem.
-1. **Compare codecs on the same source.** In **Sharing settings**, change the
+1. **Compare codecs on the same source.** In **Settings → Connection & encoding**, change the
video codec from **H264** to **Auto** or **VP8**, then start sharing again.
If VP8 works, you can keep using it while checking the H264 path.
2. **Update and restart.** Update Piik App and Chrome, and install the appropriate
@@ -94,6 +129,30 @@ comparison and export the App and browser reports for the same attempt. Include
your GPU model, driver version, source type and whether VP8 works. If both codecs
fail, also check [WebRTC restrictions](#browser-webrtc-restrictions).
+## Game capture is black or sharing stops
+
+Check that you selected the game's window or the screen displaying it, then try
+the game's borderless window mode. Compare an ordinary window, and try both App
+capture and the **Browser** source picker. Protected content may be unavailable
+for capture; one game failing does not establish that every source is affected.
+
+If Piik returns to the start screen after you enter a game, read the reason below
+the TV and follow [sharing startup checks](#sharing-does-not-start-after-source-selection).
+Include the game, window mode, source type, codec and matching App/browser reports
+in your feedback. A missing picture alone does not identify an encoder fault.
+
+## HDR picture looks too bright or washed out
+
+Windows App capture through **Apps / Windows** or **Screens** converts HDR to SDR
+for viewers. The **Browser** picker uses browser capture instead; some HDR sources
+can look overexposed. This is a known limitation. Try the App categories above,
+or temporarily turn off HDR in Windows display settings and select the source again.
+Higher resolution or bitrate cannot restore clipped highlights.
+
+If the picture still looks wrong, report the source type, HDR setting, GPU and
+display model, with a comparison of the source and viewer pictures. Technical
+background is in [HDR capture notes](../research/media-fidelity.md#hdr-to-sdr).
+
## Yellow capture border on Windows
Windows draws this outline to identify the window or display being captured.
@@ -138,6 +197,50 @@ See the [mod author's instructions](https://github.com/ramensoftware/windhawk-mo
and [Windhawk's process settings](https://github.com/ramensoftware/windhawk/wiki/Injection-targets-and-critical-system-processes)
for current setup details.
+## Public invitation fails or shows 1033
+
+App **Public invite** uses Cloudflare Tunnel to provide a temporary web address.
+`public invitation service exited before connecting` means the helper exited
+before connecting; `exit status 1` alone does not identify the cause.
+[Cloudflare error 1033](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1033/)
+means that the address currently has no available tunnel connection. This differs
+from a page that opens but reports **No media route available**.
+
+1. **Viewers: confirm the link.** Ask the host to check that the App is running
+ and the computer is awake, then send the current invitation. Use a new link
+ after the App restarts; the old address may no longer work.
+2. **Hosts: read the terminal error.** Check that the complete App package was
+ extracted. Save the full startup error and try again with **Debug launch**
+ enabled. The App retries early tunnel-process exits within its startup deadline.
+3. **Compare networks.** Try a phone hotspot. Check whether DNS, a proxy or a
+ firewall blocks Cloudflare Tunnel; adjust only relevant rules. Ask the
+ administrator about a school or workplace network.
+
+If it keeps failing, you can share through the [online site or an existing site](./getting-started.md#share-from-an-existing-site).
+Include the App version, failure time and [App diagnostic report](../../cmd/piik-app/README.md#diagnostics)
+in feedback. If the unavailable address is a self-hosted site rather than the App's
+temporary address, ask that site's administrator to check its service.
+
+## Picture blurs, stutters or stops
+
+Brief blur can result from automatic adjustments to network or encoding load.
+If it recurs or never recovers, compare the following:
+
+1. **Identify who is affected.** Is it the host's preview, every viewer or just
+ one viewer? Note the time and whether it recovers on its own. A clear host
+ preview does not establish that viewers' connections are healthy.
+2. **Change one thing at a time.** The host can try a lower resolution or frame
+ rate under **Settings → Picture**, and check CPU/GPU load while the game runs.
+ An affected viewer can compare another browser or a phone hotspot. Increasing
+ bitrate does not necessarily help.
+3. **Save reports from the affected period.** Enable diagnostics on the host and
+ affected viewer pages before reproducing; App capture also needs an App report.
+ Try **Reconnect** if the picture does not recover. Export before refreshing.
+
+If sharing stopped altogether, read the reason below the TV and follow
+[sharing startup checks](#sharing-does-not-start-after-source-selection). If the
+host is still sharing but viewers cannot receive video, continue with the checks below.
+
## When video will not connect
**No media route available** means Piik has not found a working path to deliver
diff --git a/docs/guide/troubleshooting.zh-CN.md b/docs/guide/troubleshooting.zh-CN.md
index 0cc83369..e8bd9b2d 100644
--- a/docs/guide/troubleshooting.zh-CN.md
+++ b/docs/guide/troubleshooting.zh-CN.md
@@ -9,24 +9,52 @@
| 你遇到的情况 | 可以先试什么 |
| --- | --- |
-| 有画面,没来源声音 | 先取消视频静音。房主应选择支持分享声音的来源,并在选源器中打开声音。 |
-| 听不到房主说话 | 房主可在画面下方开启 **麦克风**,在 **分享设置 → 声音** 中检查输入设备和音量,并确认设备连接与麦克风权限。如控件不可用,请更新 App 并刷新页面。 |
+| App 启动失败,或没有自动打开网页 | 查看页面和终端中的原因;App 仍在运行时可复制终端中的地址打开。按 [App 运行与诊断说明](../../cmd/piik-app/README.zh-CN.md#诊断)收集报告;本地模式提示多个地址时,在启动页选择网卡和 IP。 |
+| 公网邀请创建失败,或打开链接出现 1033 | 按[公网邀请排查](#公网邀请创建失败或出现-1033)检查房主 App 和当前链接。 |
+| 本地邀请打不开 | 确认两台设备在同一网络且可以互相访问。访客 Wi-Fi 或防火墙规则可能阻止本地连接。 |
+| 输入房间号后提示房间不存在 | 房间号只在创建它的站点有效。优先打开房主发送的完整邀请链接,参阅[加入房间](./getting-started.zh-CN.md#加入朋友的房间)。 |
+| 无法创建房间 (403) | 自建站点请联系管理员检查[允许访问的站点地址](#创建房间返回-403)。 |
| 没有屏幕选择弹窗 | 按系统提示允许浏览器或 App 录制屏幕。浏览器采集需要 HTTPS 或 `localhost`,请在电脑上尝试分享。 |
| App 的窗口或屏幕列表为空 | 先查看选源器中的提示,再按 [App 来源排查](#app-找不到窗口或屏幕) 操作;也可以选 **浏览器** → **选择画面**,在浏览器弹窗中选择屏幕、窗口或标签页。 |
+| 选源后提示分享失败 | 点击电视下方的错误图标查看原因和排查入口,按[分享启动排查](#选源后无法开始分享)逐步对照。 |
| H264 无法开播,或选源后立即退回未分享状态 | 先试 **自动** 或 **VP8**,再按 [Windows H264 与显卡排查](#windows-上-h264-分享失败)操作。 |
+| 游戏黑屏、只显示桌面,或进入游戏后停止分享 | 对照其他来源和窗口模式,按[游戏采集排查](#游戏黑屏或进入游戏后停止分享)操作。 |
+| HDR 画面过亮或颜色发白 | Windows 上可改用 App 选源,或暂时关闭 HDR;查看 [HDR 说明](#hdr-画面过亮或颜色发白)。 |
| 分享的窗口或屏幕周围出现黄框 | 这是 Windows 的采集提示。查看[采集边框说明](#windows-分享时出现黄框),了解 Windows 11 的开关和 Windows 10 的可选处理方法。 |
-| App 启动失败 | 先查看页面和终端中的具体原因。重新打开 App,在主题按钮后的芯片图标开启「诊断启动」再重试。启动失败时会自动导出报告,保存位置见终端。 |
-| 本地邀请打不开 | 确认两台设备在同一网络且可以互相访问。访客 Wi-Fi 或防火墙规则可能阻止本地连接。 |
-| 无法创建房间 (403) | 自建站点请联系管理员检查[允许访问的站点地址](#创建房间返回-403)。 |
+| 有画面,没来源声音 | 先取消视频静音。房主应选择支持分享声音的来源,并在选源器中打开声音。摄像头画面与音频输入分别选择,见[声音设置](./getting-started.zh-CN.md#加上自己的声音)。 |
+| 听不到房主说话 | 房主可在画面下方开启 **麦克风**,在 **设置 → 声音** 中检查输入设备和音量,并确认设备连接与麦克风权限。如控件不可用,请更新 App 并刷新页面。 |
+| 分享时把语音软件的声音也传出去了 | Windows App 屏幕采集可选择[排除应用声音](./getting-started.zh-CN.md#分享屏幕时排除语音软件的声音);该功能不消除扬声器被麦克风收音产生的回声。 |
| 网页能打开,画面连不上 | **重新连接** 按钮可用时先点击,否则刷新观看页。仍然失败时,查看 [画面连接排查](#画面连接不上)。 |
| 开启了 WebRTC 或 IP 泄露保护 | 按[浏览器 WebRTC 设置](#浏览器限制了-webrtc)检查是否阻止了媒体连接。 |
| 校园网或受限网络连不上 | 先用手机热点对照,再考虑[启用 SFU 的自建站点](#校园网或严格-nat)。 |
+| 画面反复模糊、卡顿或中断 | 先分清哪些观众受影响,再按[画质与中断排查](#画面模糊卡顿或中断)操作。 |
+| 手机全屏仍有黑边,或全屏按钮无效 | 画面会保持原始比例,可尝试横屏;使用播放栏的 **全屏观看** 按钮,系统视频全屏由浏览器提供。详见[观看操作](./getting-started.zh-CN.md#加入朋友的房间)。 |
| 休眠或挂起后分享中断 | 唤醒设备,回到分享标签页,必要时重新开始分享。浏览器或系统挂起可能中断采集和播放。 |
反馈问题时,请附上版本、系统与浏览器、预期结果和复现步骤。
[诊断与导出](../../cmd/piik-app/README.zh-CN.md#诊断)
说明如何收集本地报告,以及分享前需要检查哪些内容。
+## 选源后无法开始分享
+
+电视下方的错误图标说明当前失败;点击可打开排查面板,查看建议、复制失败信息,
+或开启网页诊断。复制内容包含网页版本、提示和错误编号,不包含邀请链接或来源名称。
+
+- **App 连接断开或请求超时**:确认 App 仍在运行且可以响应,从 App 打开当前站点后刷新。
+ 浏览器询问本地网络权限时允许访问。超时只说明请求未及时完成,不能据此认定显卡故障。
+- **App 未能启动所选来源**:先换一个普通窗口或屏幕;再对照「浏览器」选源。
+ Windows 上可试「自动」或 VP8,后续按[显卡排查](#windows-上-h264-分享失败)操作。
+- **浏览器无法读取来源或缺少权限**:保持来源打开,允许系统录屏权限,回到分享页重新选源。
+ 摄像头还需检查设备是否正被其他程序独占。
+- **媒体连接失败**:检查[浏览器 WebRTC 设置](#浏览器限制了-webrtc)和本地网络权限。
+ **创建房间返回 403** 则按下节检查站点配置。
+
+恢复后不必继续排查。仍然失败时,先开启诊断,再重现一次:网页按钮只收集浏览器报告;
+使用 App 时也请在模式选择页开启「诊断启动」,随后在终端按 `D` 导出 App 报告。
+将同一次尝试的报告与复制的失败信息一起反馈,并说明所选来源类型。
+没有报告时仍可反馈;单独一张「分享失败」截图通常无法确定采集、编码或连接中的具体原因。
+日志保存在本机,分享前请检查其中的私人信息。操作细节见[诊断与导出](../../cmd/piik-app/README.zh-CN.md#诊断)。
+
## 创建房间返回 403
浏览器访问的网址不在服务端允许的范围内时,页面可能正常打开,但创建房间会被拒绝。
@@ -65,7 +93,7 @@
选中窗口或屏幕后回到未分享状态,或出现「启动分享失败」,可能涉及采集、编码或网页与 App
之间的媒体连接,不能仅凭提示确定是显卡驱动问题。
-1. **用同一来源对比编码。** 在 **分享设置** 中,将视频编码从 **H264** 改为 **自动** 或
+1. **用同一来源对比编码。** 在 **设置 → 连接与编码** 中,将视频编码从 **H264** 改为 **自动** 或
**VP8**,重新开始分享。如果 VP8 正常,可以先用它,再排查 H264 路径。
2. **更新后重启。** 更新 Piik App 和 Chrome,并从电脑或显卡厂商的官方网站安装适合本机的
显卡驱动。双显卡笔记本应检查两块显卡的驱动,安装后重启电脑。
@@ -81,6 +109,26 @@
导出同一次尝试的 App 与网页诊断报告,并附上显卡型号、驱动版本、选源方式和 VP8 是否正常。
两种编码都失败时,也检查下方的 [WebRTC 限制](#浏览器限制了-webrtc)。
+## 游戏黑屏或进入游戏后停止分享
+
+先确认当前分享的是游戏窗口或游戏所在的屏幕,再尝试游戏的无边框窗口模式。
+对照分享一个普通窗口,并在 App 选源与 **浏览器** 选源之间比较。
+受保护的内容可能无法采集;某个游戏失败不代表所有来源都不可用。
+
+如果进入游戏后 Piik 退回未分享状态,查看电视下方的失败原因,按[分享启动排查](#选源后无法开始分享)操作。
+反馈时附上游戏名称、窗口模式、选源方式、编码器和同一次尝试的 App/网页报告。
+不要仅凭「没有画面」确定为编码故障。
+
+## HDR 画面过亮或颜色发白
+
+Windows App 的 **程序 / 窗口** 和 **屏幕** 采集会将 HDR 转成 SDR,再分享给观众。
+**浏览器** 选源由浏览器负责采集,部分 HDR 来源可能过曝;这是当前的已知限制。
+可改用 App 的上述分类,或在 Windows 显示设置中暂时关闭 HDR 后重新选源。
+提高分辨率或码率无法恢复已经丢失的亮部细节。
+
+仍然异常时,请说明使用的是哪种选源方式、是否开启 HDR、显卡和显示器型号,
+并附上源画面与观众画面的对照。技术背景见 [HDR 采集说明(英文)](../research/media-fidelity.md#hdr-to-sdr)。
+
## Windows 分享时出现黄框
Windows 用黄色边框标出正在采集的窗口或屏幕。在支持的 Windows 版本上,
@@ -120,6 +168,40 @@ Windows 需要用户授权;其他采集要求显示边框时,边框仍会保
最新操作说明见[模组作者说明](https://github.com/ramensoftware/windhawk-mods/blob/main/mods/dwm-custom-projection-border.wh.cpp)
和 [Windhawk 进程设置文档](https://github.com/ramensoftware/windhawk/wiki/Injection-targets-and-critical-system-processes)(英文)。
+## 公网邀请创建失败或出现 1033
+
+App 的 **公网邀请** 通过 Cloudflare Tunnel 提供临时网页地址。
+`public invitation service exited before connecting` 表示辅助程序在连接完成前退出;
+`exit status 1` 本身不能说明具体原因。
+[Cloudflare 的 1033 说明](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1033/)(英文)
+表示该地址当前没有可用的隧道连接。这与网页能打开、但显示「没有可用的媒体线路」是不同的问题。
+
+1. **观众先确认链接。** 请房主确认 App 仍在运行、电脑未休眠,并发送当前邀请。
+ App 重新启动后应使用新链接,旧地址可能失效。
+2. **房主查看终端原因。** 确认已完整解压 App 程序包;启动失败时,保留终端的完整错误,
+ 开启 **诊断启动** 后再试。App 会在启动时限内重试提前退出的隧道进程。
+3. **对照网络。** 可用手机热点重试,检查 DNS、代理或防火墙是否阻止 Cloudflare Tunnel。
+ 只调整相关规则;学校或公司的网络应联系管理员。
+
+反复失败时可先通过[在线版或已有站点](./getting-started.zh-CN.md#使用已有站点分享)分享。
+反馈中请附上 App 版本、失败时间和 [App 诊断报告](../../cmd/piik-app/README.zh-CN.md#诊断)。
+如果打不开的是自建站点而非 App 的临时地址,请联系该站点管理员检查服务。
+
+## 画面模糊、卡顿或中断
+
+短时变糊可能来自网络或编码负载的自动调整;反复出现或长期不恢复时,按下面的步骤对照:
+
+1. **确认影响范围。** 是房主预览、所有观众,还是只有某位观众?记录大致时间,
+ 以及能否自行恢复。房主预览清楚并不保证观众的连接也正常。
+2. **一次调整一项。** 房主可在 **设置 → 画面** 中先试较低的分辨率或帧率,
+ 检查游戏运行时 CPU/GPU 是否接近满载;受影响的观众可用另一浏览器或手机热点对照。
+ 将码率调高不一定有帮助。
+3. **保留问题发生时的报告。** 在房主和受影响的观众页面开启诊断后重现,
+ App 采集还需 App 报告。画面持续不恢复时可尝试 **重新连接**;请先导出报告再刷新页面。
+
+如果分享已自动停止,查看电视下方的具体原因,并按[分享启动排查](#选源后无法开始分享)操作;
+如果仍在分享但观众看不到画面,继续查看下方的连接排查。
+
## 画面连接不上
**没有可用的媒体线路** 表示 Piik 还没有找到能把画面送到你设备上的连接。
diff --git a/docs/operations/website.md b/docs/operations/website.md
index 0aa82e41..8f77aa54 100644
--- a/docs/operations/website.md
+++ b/docs/operations/website.md
@@ -87,6 +87,11 @@ ranges for seeking the soundtrack. Keep asset links relative so both a custom
domain and GitHub's `/Piik/` project path work. For a nested deployment, set
`PIIK_DOCS_BASE=/Piik/docs/` when building; ordinary custom-domain builds use `/docs/`.
+The homepage, film and demonstration frames use content-hashed script/style
+bundles. Their HTML references come from the same build, including imported
+dependencies; fixed filenames must not mix a new page with cached old controls
+or styles. Publish the complete output together.
+
## Documentation Build
`site/docs/` configures VitePress; its isolated package and lockfile keep document
diff --git a/docs/research/media-fidelity.md b/docs/research/media-fidelity.md
index 33216f21..2f95f1a9 100644
--- a/docs/research/media-fidelity.md
+++ b/docs/research/media-fidelity.md
@@ -104,9 +104,10 @@ coverage of all hardware encoders, HDR content or missing upstream color declara
## HDR To SDR
-[#420](https://github.com/TNTcraftHIM/Piik/issues/420) reports overexposure with
-both App and Browser capture on one Windows HDR machine. The report does not
-locate the failing stage.
+[#420](https://github.com/TNTcraftHIM/Piik/issues/420) initially reported
+overexposure with both App and Browser capture. On 2026-10-04 the reporter
+confirmed that native App capture was corrected in v1.7, while Browser capture
+remained overexposed. This is one machine's evidence, not all-device acceptance.
The previous native WGC frame pool and thumbnails requested BGRA8, discarding
HDR range before the existing 8-bit H.264/VP8 encoder. Microsoft's
@@ -157,6 +158,13 @@ thumbnails, mixed displays and mode changes under load remain unaccepted.
Browser capture owns its own conversion; inspect the acquired frame before
assigning a downstream bug.
+The reviewed [WebRTC WGC implementation](https://webrtc.googlesource.com/src/+/b5cf1fa607113788cf894d5b6895c72fba1d9254/modules/desktop_capture/win/wgc_capture_session.cc)
+requests an 8-bit BGRA frame pool. The Web capture API exposes no portable
+HDR-tone-mapping control; once highlights are clipped, lowering brightness in
+Piik cannot recover them. Keep this Browser/platform limitation explicit and
+offer native capture or disabling system HDR in troubleshooting. Do not add a
+second Browser pixel pipeline without evidence that it receives intact HDR.
+
Full HDR requires a separate end-to-end decision for bit depth, codec support,
color metadata, decoding and mixed Viewer capabilities. It is not a quality
dropdown addition. Preserve ordinary SDR routing and existing compatibility
diff --git a/docs/research/nat-traversal.md b/docs/research/nat-traversal.md
index 10f945df..f629b0a9 100644
--- a/docs/research/nat-traversal.md
+++ b/docs/research/nat-traversal.md
@@ -361,6 +361,14 @@ connection ID, or new ICE credentials did not prove a fresh library observation.
Recovery checks must retain the resources production retains while changing the
external condition; recreating everything would hide this cache boundary.
+The same lifetime review found gateway mappings were reused until half their
+requested lease elapsed. A router restart can lose that mapping sooner. Each
+actual gathering now refreshes a successful mapping through the existing bounded
+gateway owner; ordinary renegotiation does not. A retained-owner fixture changes
+the allocated external port between gatherings and verifies the new result.
+Failed attempts still obey the existing cancellation and cleanup rules; this
+adds no periodic renewal loop or claim of improved field success rates.
+
A separate Chrome 152 Windows loopback probe on 2026-10-04 changed a STUN
fixture's reported mapping across four gatherings on one PeerConnection and
four replacement PeerConnections. Every gathering sent a new Binding request
diff --git a/docs/research/native-client-media.md b/docs/research/native-client-media.md
index 5a5291b0..8da28b7e 100644
--- a/docs/research/native-client-media.md
+++ b/docs/research/native-client-media.md
@@ -1,6 +1,6 @@
# Native App Media Evidence
-- Reviewed: 2026-10-04
+- Reviewed: 2026-10-06
- Scope: platform capture, shared encoded sources, Pion transport and Browser
decode; current behavior belongs to [media quality](../standards/media-quality.md)
- Status: Windows physical native Host and Viewer gates passed; macOS and Linux adapters
@@ -32,6 +32,14 @@ application's process tree or simultaneous playback across several output device
device acceptance boundaries. [ADR-0008](../adr/0008-window-scoped-audio-capture.md)
owns the platform choice.
+The capability check now attempts exclusion activation on Windows 10 2004+
+instead of rejecting all builds below 20348. Microsoft documents 20348 as the
+minimum, while OBS documents application loopback on Windows 10 2004+; the
+activation result, not an OS label, controls availability. Physical Windows 10
+exclusion remains unverified. A session regression check changes exclusion and
+source-audio off/on while video preparation is deliberately unavailable: the
+capture stream, encoded source, audio output and connected edge remain the same.
+
The [Windows activation contract](https://learn.microsoft.com/en-us/windows/win32/api/audioclientactivationparams/ns-audioclientactivationparams-audioclient_process_loopback_params)
accepts one PID and its process tree, not a list of unrelated processes.
The [win-capture-audio implementation](https://github.com/bozbez/win-capture-audio/releases/tag/v2.2.0-beta)
diff --git a/docs/standards/media-quality.md b/docs/standards/media-quality.md
index 6d3cb7d0..999f1e50 100644
--- a/docs/standards/media-quality.md
+++ b/docs/standards/media-quality.md
@@ -119,6 +119,10 @@ the actual SPS profile/level; one vendor's byte spelling is not the contract.
Native ingress and relay accept only a negotiated profile/packetization compatible
with their unchanged encoded downstream source. A codec name alone is not enough;
same-source renegotiation must preserve that boundary before altering the live peer.
+Received picture summaries are not decoder allocation limits. Before Native
+derivation, validate every H.264 sequence parameter set's supported format,
+coded storage and visible crop; a later small descriptor cannot authorize earlier
+large input.
Framework-driven downscaling under bandwidth or device pressure is valid within
the selected degradation preference. A low decoded resolution alone is not a
@@ -341,7 +345,11 @@ and is never saved across App runs or rebound by executable name. Changing to a
window source or explicitly selecting no exclusion clears it. A requested
exclusion retires previous source audio before replacement preparation; failure
or target exit leaves source audio silent while healthy video and the Host
-microphone continue. Only an explicit source selection resumes it. A missing
+microphone continue. Only an explicit audio/source selection resumes it. Live
+sound controls reuse source replacement and its serialization owner; when the
+video target and capture options are unchanged, update only the audio input.
+Keep the video generation, encoder, media connections and quality evidence.
+A missing
capability must reject the request, never discard the exclusion. Old pages keep
their existing audio behavior.
diff --git a/docs/standards/media-status.md b/docs/standards/media-status.md
index b947e625..de2bffa0 100644
--- a/docs/standards/media-status.md
+++ b/docs/standards/media-status.md
@@ -43,6 +43,16 @@ over a reused comic's default; text and pure-visual tooltips retain that context
The Host television describes its local source, not an arbitrary outbound
child. A confirmed limitation may colour the relevant icon amber while the
page title still says watching.
+ A Host failure may open a troubleshooting dialog from this same icon. Keep
+ the existing hover explanation; the dialog owns actionable help, not a second
+ banner or an interactive tooltip. Preserve the observed operation and failure
+ boundary (timeout, disconnect, rejection); an unspecified App rejection does
+ not establish a driver or network cause. Copy only bounded diagnostic context,
+ never raw exceptions, source names or invitation URLs. Recording remains an
+ explicit opt-in through the shared diagnostic control. Troubleshooting follows
+ the known failure boundary: unknown/session/settings failures must not default
+ to capture advice, and retiring a share must retain a known App control or
+ media-connection failure instead of replacing it with a generic stop notice.
- Host couch: each Viewer has one round lamp. Grey means waiting for the share,
blue means waiting for the media path, green means committed `mediaReady`, and
amber means a recent receive freeze. The Host's own pawn has no duplicate
diff --git a/docs/standards/naming.md b/docs/standards/naming.md
index 1bffc8df..e321048d 100644
--- a/docs/standards/naming.md
+++ b/docs/standards/naming.md
@@ -103,7 +103,9 @@ Download/availability labels, platform requirements, instructions, permission
prompts, status and errors stay plain and specific. Use the exact visible action
names in tutorials; a playful caption never replaces “Download”, “Join a room”
or a platform/connection limitation. Explain what happened, what the user can do
-next, and any real limitation. Jokes belong
+next, and any real limitation. Keep inline errors to the observed problem and
+one useful next action; put longer checks in the existing help dialog or guide.
+Automatic recovery states describe progress, not a request to reload. Jokes belong
in the welcome or illustration caption. Do not soften a failure into a joke,
invent connection progress or promise guaranteed connectivity or absolute privacy.
Screen sharing includes games, creative work and showing a useful discovery.
diff --git a/docs/standards/routing-transport.md b/docs/standards/routing-transport.md
index 52e34139..c84ede8a 100644
--- a/docs/standards/routing-transport.md
+++ b/docs/standards/routing-transport.md
@@ -127,6 +127,9 @@ is unchanged. Pion owns ICE restart; each actual gathering owns fresh supplement
candidates. Native STUN observations share only an in-flight transaction, never
a completed address across gatherings. Discovery uses the existing media socket;
retiring one gathering does not cancel another or close healthy media.
+Each actual gathering also refreshes a previously successful gateway mapping;
+the requested lease does not prove that the gateway retained its state. Ordinary
+SDP renegotiation does not refresh mappings, and this adds no background poller.
A Native connection owns its UDP socket and optional gateway mapping. A new
connection receives an independent socket; ICE restart retains the current one.
Discovery and media must use that same connection-owned socket. Sharing a socket
diff --git a/docs/status.md b/docs/status.md
index 3fce5f04..32e59ebd 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -1,6 +1,6 @@
# Current Status
-Last updated: 2026-10-04
+Last updated: 2026-10-06
This is the compact execution/deployment index. Product modules own behavior,
[verification status](./verification-status.md) owns unresolved physical limits,
@@ -52,15 +52,17 @@ These features are published; physical device limits remain open.
Release artifacts and operator deployment records own delivery completion;
[TODO](./todo.md#now) owns remaining work.
-## Current Candidate
+## Current Work
-The owner authorized v1.8.0 publication on 2026-10-04. This phase retains the
-published protocols and 1440p ceiling; immutable release artifacts own delivery
-completion. Follow-up work reviews extension boundaries, implements 4K and more
-resolutions with capability negotiation, then develops Native Magicsock NAT
-traversal. The isolated transport experiment is not part of v1.8.0; its product
-integration and connectivity benefit still require verification.
-[TODO](./todo.md#now) owns remaining work and later release authorization.
+The public baseline retains Browser/server v23, Native control v9, capture v7
+and the 1440p ceiling. The compatible maintenance phase combines sharing-failure
+guidance and bilingual troubleshooting with source-list, codec admission,
+minimized-capture and gateway-mapping repairs. Live audio-exclusion controls
+reuse the source/mixer owner; website controls retain shared motion and cache
+identity. 4K and resolution/capability expansion are not planned for this phase.
+Native Magicsock remains a separate experiment, outside product integration.
+Immutable release artifacts own delivery completion; [TODO](./todo.md#now) owns
+remaining work.
## Deployment
@@ -89,7 +91,7 @@ public release on 2026-09-12. Source is public, main protection is active, and
remains a separate deployment. Release descriptors and GitHub deployment records
identify published artifacts and website revisions.
-The matching Server and three App packages are published on GitHub and Gitee;
+Matching Server and registered App packages are published on GitHub and Gitee;
anonymous mirror downloads match the original checksums. Public-repository CI
and native packaging passed. App entry, update links
and bounded two-build interoperability have acceptance evidence. Accepted
diff --git a/docs/todo.md b/docs/todo.md
index 44a7201a..3911685f 100644
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -1,49 +1,28 @@
# Current TODO Ledger
-Last reviewed: 2026-10-04
+Last reviewed: 2026-10-06
Only **Now** is executable. Product modules own behavior; Git/PRs own completed
history. A parked idea is not implementation authority.
## Now
-- [ ] **Publish the accepted v1.8.0 candidate first.** Authorized by the owner
- on 2026-10-04. Complete final checks and publish through the existing squash
- PR, packaging, mirror and deployment workflow. Preserve
- [#449](https://github.com/TNTcraftHIM/Piik/pull/449)'s contributor credit and
- `Co-authored-by` identity. Reply to resolved issues at publication; retain
- unmatched field reports below. This release keeps the published protocols
- and 1440p ceiling; the subsequent media/transport work is separate.
-- [ ] **Resolve the extensibility audit boundaries before freezing 2.0.** Review
- the media findings in the assessment below together with optional interaction
- evolution: the current reaction catalog is a strict wire enum, and an unknown
- reaction or extra event field terminates the Browser signaling session.
- Current producers do not send those values. Choose bounded capability-gated
- delivery or a safe presentation fallback before expanding the catalog; preserve
- strict command and authority validation. No replacement protocol is accepted yet.
-- [ ] **Align native source-list aggregate bounds.** The helper admits up to
- 1024 sources, but `nativecapture.ListSources` reuses the 64 KiB probe-output
- bound. A synthetic helper with 64 individually valid 512-character window
- titles returns no list; the 32-source control succeeds. Align enumeration,
- encoded JSON and loopback response budgets with bounded overflow behavior.
- This is a confirmed uncommon enumeration failure, not a diagnosis of earlier
- reporter logs; it does not justify removing byte limits or adding pagination.
-- [ ] **Implement extensible resolution and transport support after v1.8.0.**
- The owner requested continued repository review, then 4K (#410) and additional
- resolutions with adaptation and capability negotiation, followed by Magicsock
- NAT traversal on 2026-10-04. Compare the isolated Go transport
+- [ ] **Assess Native Magicsock transport.** Compare the isolated Go transport
with the repaired Pion baseline under the [NAT evidence boundary](#next-p2p-connection-and-feedback-evidence).
- Evaluate orientation-independent resolution limits, source aspect preservation
- and negotiated codec capabilities under the
- [media extension assessment](./research/native-client-media.md#media-capability-extension-assessment).
- Establish the supported paths, late-join behavior, resource bounds and public
- compatibility boundary before freezing the production design. Additional
- codecs still require a concrete format decision. Experiments do not establish
- a connectivity gain; implementation authority does not authorize publishing
- the later release.
+ Establish a measured benefit, supported paths, resource/authority bounds and
+ compatibility cost before accepting product integration. Experiments do not
+ establish a connectivity gain or authorize publication.
## Held By Owner
+- [ ] **4K and resolution/capability expansion.** Not planned for this phase,
+ reaffirmed by the owner on 2026-10-06 because of cost relative to benefit. Keep the
+ public v23/v9/v7 contract and 1440p ceiling. Resume the extensibility audit and
+ [media extension assessment](./research/native-client-media.md#media-capability-extension-assessment)
+ only with a renewed benefit/cost decision. This includes unfinished
+ cross-platform capture and capability negotiation; local tests alone do not
+ authorize a protocol break or a 2.0 release. Retain recoverable Git evidence
+ for the experiment without requiring an active worktree.
- [ ] **Browser-internal encoder work.** Paused by the owner on 2026-10-01.
[Comparisons and Chromium traces](./research/browser-local-encoding-pool.md#sustained-h264-recovery)
own the evidence for synchronous H264 initialization, native adaptation and
@@ -53,7 +32,7 @@ history. A parked idea is not implementation authority.
- [ ] **32-bit Windows/Linux Apps.** Deferred by the owner on 2026-10-02;
no package or website option is planned. Browser use remains available where
the OS/browser supports the required media APIs. Retain the isolated
- `spike/windows-x86-capture` experiment; revisit its native dependencies,
+ Git evidence for the Windows x86 capture experiment; revisit its native dependencies,
atomic alignment and real 32-bit device coverage only if this work is reopened.
- [ ] **Windows ARM64 App.** Deferred by the owner on 2026-10-03. Keep Windows
App packages and website downloads x64-only until this work is reopened.
@@ -62,6 +41,10 @@ history. A parked idea is not implementation authority.
These proposals remain deferred beyond the accepted interaction phase.
+- [ ] **Managed Demo hosting.** Evaluate cost and public UDP support before any
+ migration. The assessment remains outside the current product release; keep
+ the existing P2P-only Demo deployment until a provider and operating boundary
+ are accepted.
- [ ] **Phone as a Host microphone: assess after the current work.** Explore an
opt-in link that pairs a phone's microphone with the Host's existing audio
mixer. Evaluate pairing/revocation, latency/echo, browser background limits
@@ -88,9 +71,9 @@ of a reporter's cause; research owns the completed experiments and their limits.
- [ ] **HDR, audio-exclusion and mobile interaction device coverage.** Complete
the [physical matrix](./verification-status.md#device-evidence-boundary):
HDR/mixed displays, voice-app process trees across playback devices and phone
- keyboard/theater/participant-menu interaction. Browser HDR
- [#420](https://github.com/TNTcraftHIM/Piik/issues/420) needs its own capture
- evidence, separate from Native conversion.
+ keyboard/theater/participant-menu interaction. Browser HDR overexposure is an
+ accepted limitation with [documented alternatives](./guide/troubleshooting.md#hdr-picture-looks-too-bright-or-washed-out);
+ reopen conversion work only with new evidence and an accepted implementation.
- [ ] **Native H.264 motion quality (#432).** Obtain matched source/decoded
pictures and bitstream for the original 720p30 game comparison. Retain current
codec parameters. The [evidence review](./research/native-client-media.md#native-h264-motion-quality)
diff --git a/docs/verification-status.md b/docs/verification-status.md
index f7f5ffca..379155b8 100644
--- a/docs/verification-status.md
+++ b/docs/verification-status.md
@@ -56,7 +56,8 @@ These checks do not establish Browser-capture HDR behavior or end-to-end HDR.
Windows source-audio exclusion has bounded parent/child tone-isolation and
target-exit evidence. It does not establish coverage of arbitrary process trees
-or real voice applications across playback devices. The
+or real voice applications across playback devices. Windows 10 exclusion
+activation and tone isolation still need a physical device check. The
[audio assessment](./research/native-client-media.md#windows-audio-exclusion)
owns that distinction.
diff --git a/go.mod b/go.mod
index 9c000ff0..a933186b 100644
--- a/go.mod
+++ b/go.mod
@@ -1,6 +1,6 @@
module github.com/TNTcraftHIM/Piik
-go 1.26
+go 1.26.0
// Scoped NAT-PMP fixes; provenance and removal criteria: internal/thirdparty/README.md.
replace github.com/netbirdio/go-nat => ./internal/thirdparty/go-nat
@@ -10,6 +10,7 @@ replace github.com/jackpal/go-nat-pmp => ./internal/thirdparty/go-nat-pmp
require (
charm.land/bubbletea/v2 v2.0.9
charm.land/lipgloss/v2 v2.0.6
+ github.com/bluenviron/mediacommon/v2 v2.9.5
github.com/charmbracelet/colorprofile v0.4.3
github.com/charmbracelet/x/ansi v0.11.8
github.com/charmbracelet/x/term v0.2.2
diff --git a/go.sum b/go.sum
index a2e2df51..0a1c4bcd 100644
--- a/go.sum
+++ b/go.sum
@@ -20,6 +20,8 @@ github.com/benbjohnson/clock v1.3.5 h1:VvXlSJBzZpA/zum6Sj74hxwYI2DIxRWuNIoXAzHZz
github.com/benbjohnson/clock v1.3.5/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA=
github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/bluenviron/mediacommon/v2 v2.9.5 h1:6r1vq9qFH5AUUjPOPxRd00BhBNAg1EcmYNvwmpzAibo=
+github.com/bluenviron/mediacommon/v2 v2.9.5/go.mod h1:1J4QckclKIksdI9+7C+PJXVBkpO/JYWn7/h+wOYq+7E=
github.com/brianvoe/gofakeit/v6 v6.28.0 h1:Xib46XXuQfmlLS2EXRuJpqcw8St6qSZz75OUo0tgAW4=
github.com/brianvoe/gofakeit/v6 v6.28.0/go.mod h1:Xj58BMSnFqcn/fAQeSK+/PLtC5kSb7FJIq4JyGa8vEs=
github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
diff --git a/internal/app/mediaedge/relay_input.go b/internal/app/mediaedge/relay_input.go
index da785ea8..c0e78b4f 100644
--- a/internal/app/mediaedge/relay_input.go
+++ b/internal/app/mediaedge/relay_input.go
@@ -2,10 +2,13 @@ package mediaedge
import (
"bytes"
+ "encoding/hex"
"errors"
+ "fmt"
"io"
"github.com/TNTcraftHIM/Piik/internal/app/nativecapture"
+ "github.com/bluenviron/mediacommon/v2/pkg/codecs/h264"
mediacodec "github.com/livekit/mediatransportutil/pkg/codec"
"github.com/livekit/server-sdk-go/v2/pkg/samplebuilder"
"github.com/pion/rtp"
@@ -99,11 +102,12 @@ func (input *relayVideoInput) frame(data []byte) (nativecapture.Frame, error) {
}
switch nal.UnitType {
case h264reader.NalUnitTypeSPS:
- input.sps = append(input.sps[:0], nal.Data...)
- size := mediacodec.ExtractH264VideoSize(nal.Data)
- if size.Width > 0 && size.Height > 0 {
- input.width, input.height = size.Width, size.Height
+ width, height, err := relayH264Size(nal.Data)
+ if err != nil {
+ return frame, err
}
+ input.sps = append(input.sps[:0], nal.Data...)
+ input.width, input.height = width, height
case h264reader.NalUnitTypePPS:
input.pps = append(input.pps[:0], nal.Data...)
case h264reader.NalUnitTypeCodedSliceIdr:
@@ -126,3 +130,41 @@ func (input *relayVideoInput) frame(data []byte) (nativecapture.Frame, error) {
frame.Width, frame.Height = input.width, input.height
return frame, nil
}
+
+// A size summary is not a decoder allocation bound: one access unit may carry
+// several SPS IDs, and a slice need not reference the last one. Admit every SPS
+// before forwarding it to any platform decoder, including its uncropped storage.
+func relayH264Size(nal []byte) (uint32, uint32, error) {
+ if len(nal) < 4 || !forwardableH264("profile-level-id="+hex.EncodeToString(nal[1:4])+";packetization-mode=1") {
+ return 0, 0, errors.New("native H264 input profile is unsupported")
+ }
+ var sps h264.SPS
+ if err := sps.Unmarshal(nal); err != nil {
+ return 0, 0, fmt.Errorf("invalid native H264 input SPS: %w", err)
+ }
+ width := (uint64(sps.PicWidthInMbsMinus1) + 1) * 16
+ height := (uint64(sps.PicHeightInMapUnitsMinus1) + 1) * 16
+ cropUnitY := uint64(2)
+ if !sps.FrameMbsOnlyFlag {
+ height *= 2
+ cropUnitY *= 2
+ }
+ // Constrained Baseline uses 8-bit 4:2:0. Bound uncropped storage before
+ // allowing padding to be removed from the visible picture.
+ if sps.ChromaFormatIdc != 1 || sps.MaxNumRefFrames > 16 ||
+ width > nativecapture.MaxVideoWidth || height > nativecapture.MaxVideoHeight {
+ return 0, 0, errors.New("native H264 input storage exceeds its bound")
+ }
+ if crop := sps.FrameCropping; crop != nil {
+ x := (uint64(crop.LeftOffset) + uint64(crop.RightOffset)) * 2
+ y := (uint64(crop.TopOffset) + uint64(crop.BottomOffset)) * cropUnitY
+ if x >= width || y >= height {
+ return 0, 0, errors.New("native H264 input crop is outside its picture")
+ }
+ width, height = width-x, height-y
+ }
+ if !nativecapture.ValidVideoSize(uint32(width), uint32(height)) {
+ return 0, 0, errors.New("native H264 input picture exceeds its bound")
+ }
+ return uint32(width), uint32(height), nil
+}
diff --git a/internal/app/mediaedge/relay_input_test.go b/internal/app/mediaedge/relay_input_test.go
index c5886a25..3ba2e0de 100644
--- a/internal/app/mediaedge/relay_input_test.go
+++ b/internal/app/mediaedge/relay_input_test.go
@@ -7,6 +7,7 @@ import (
"testing"
"time"
+ "github.com/TNTcraftHIM/Piik/internal/app/nativecapture"
"github.com/TNTcraftHIM/Piik/internal/media/encoded"
"github.com/livekit/livekit-server/pkg/sfu"
"github.com/pion/rtp"
@@ -39,7 +40,11 @@ func TestRelayInputKeepsRecoveryAndEmitsACompleteQuietFrame(t *testing.T) {
}
input = relayVideoInput{codec: "h264"}
- configuration, _ := hex.DecodeString("000000016742c01eda0280b7fe5c050505020000000168ce06e2")
+ var configuration []byte
+ for _, nal := range sfu.H264KeyFrame2x2[:2] {
+ configuration = append(configuration, 0, 0, 0, 1)
+ configuration = append(configuration, nal...)
+ }
if _, err = input.frame(configuration); err != nil {
t.Fatal(err)
}
@@ -50,6 +55,94 @@ func TestRelayInputKeepsRecoveryAndEmitsACompleteQuietFrame(t *testing.T) {
}
}
+func TestRelayInputRejectsUnsafeH264Configuration(t *testing.T) {
+ // Locally generated Constrained Baseline SPS: ID 0 is 4096x2160; ID 1 is
+ // 160x90. A decoder may use either, regardless of which arrived last.
+ const oversized = "6742c033dc0100010fb016a02020280000030008000003001478c19c"
+ const small = "6742c015570a37e4c05a8303035280000003008000000301478b17c0"
+ for _, test := range []struct {
+ name string
+ nals []string
+ }{
+ {"oversize-hidden-by-small-SPS", []string{oversized, small}},
+ {"oversize-after-small-SPS", []string{small, oversized}},
+ {"truncated-SPS", []string{small, "6742c015"}},
+ {"truncated-VUI", []string{"6742c01eda0280b7fe5c0505050200"}},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ var data []byte
+ for _, value := range test.nals {
+ nal, err := hex.DecodeString(value)
+ if err != nil {
+ t.Fatal(err)
+ }
+ data = append(data, 0, 0, 0, 1)
+ data = append(data, nal...)
+ }
+ input := relayVideoInput{codec: "h264"}
+ if _, err := input.frame(data); err == nil {
+ t.Fatal("unsafe configuration reached the native decoder boundary")
+ }
+ })
+ }
+ input := relayVideoInput{codec: "h264"}
+ data, err := hex.DecodeString("00000001" + small)
+ if err != nil {
+ t.Fatal(err)
+ }
+ frame, err := input.frame(data)
+ if err != nil || frame.Width != 160 || frame.Height != 90 {
+ t.Fatalf("valid cropped SPS was rejected: %dx%d, %v", frame.Width, frame.Height, err)
+ }
+}
+
+func TestRelayH264AllocationBounds(t *testing.T) {
+ // Minimal Constrained Baseline parameter sets, including valid codec padding
+ // and coded dimensions hidden behind a small crop. No decoder is allocated.
+ for _, test := range []struct {
+ name, sps string
+ width, height uint32
+ }{
+ {"1440p", "6742c033da00a002d640", 2560, 1440},
+ {"padded-1080p", "6742c033da01e0089f95", 1920, 1080},
+ {"portrait-within-bound", "6742c033da01100b5e5d", 1080, 1440},
+ {"4k", "6742c033da00f0010f90", 0, 0},
+ {"portrait-overflow", "6742c033da008701e190", 0, 0},
+ {"padded-4k", "6742c033da00f00111f894", 0, 0},
+ {"large-cropped-storage", "6742c033da00f001e1f8034940", 0, 0},
+ {"crop-overflow", "6742c033da0a37e000000300100000030004", 0, 0},
+ {"coded-size-overflow", "6742c033da000003000040000003000d90", 0, 0},
+ {"excessive-references", "6742c033d84828d9", 0, 0},
+ } {
+ t.Run(test.name, func(t *testing.T) {
+ data, err := hex.DecodeString(test.sps)
+ if err != nil {
+ t.Fatal(err)
+ }
+ width, height, err := relayH264Size(data)
+ if (err == nil) != (test.width != 0) || width != test.width || height != test.height {
+ t.Fatalf("picture = %dx%d, %v; want %dx%d", width, height, err, test.width, test.height)
+ }
+ })
+ }
+}
+
+func FuzzRelayH264Size(f *testing.F) {
+ for _, value := range []string{"6742c033da00f0010f90", "6742c033da008701e190", "6742c033da00f00111f894", "6742c015"} {
+ data, err := hex.DecodeString(value)
+ if err != nil {
+ f.Fatal(err)
+ }
+ f.Add(data)
+ }
+ f.Fuzz(func(t *testing.T, data []byte) {
+ width, height, err := relayH264Size(data)
+ if err == nil && !nativecapture.ValidVideoSize(width, height) {
+ t.Fatalf("unbounded picture accepted: %dx%d", width, height)
+ }
+ })
+}
+
func TestLargeRecoveryUsesTheDefaultPacketWindow(t *testing.T) {
check := func(err error) {
t.Helper()
@@ -134,9 +227,8 @@ func TestLargeRecoveryUsesTheDefaultPacketWindow(t *testing.T) {
func TestRelayAssemblyRecoversAtNewIndependentFrame(t *testing.T) {
key, _ := hex.DecodeString("1000009d012aa0005a00")
- sps, _ := hex.DecodeString("6742c01eda0280b7fe5c0505050200")
- pps := []byte{0x68, 0xce, 0x06, 0xe2}
- idr := []byte{0x65, 0x88, 0x84}
+ sps, pps := sfu.H264KeyFrame2x2[0], sfu.H264KeyFrame2x2[1]
+ idr := sfu.H264KeyFrame2x2IDR
stap := []byte{0x78}
for _, nal := range [][]byte{sps, pps, idr} {
stap = append(stap, byte(len(nal)>>8), byte(len(nal)))
diff --git a/internal/app/nativecapture/protocol.go b/internal/app/nativecapture/protocol.go
index 93de7f1a..5ba4f96a 100644
--- a/internal/app/nativecapture/protocol.go
+++ b/internal/app/nativecapture/protocol.go
@@ -15,8 +15,16 @@ const (
maxMediaBytes = encoded.MaxAccessUnitBytes
maxStatusBytes = 4 * 1024
maxControlBytes = 64
+ MaxVideoWidth = 2560
+ MaxVideoHeight = 1440
)
+// ValidVideoSize bounds the decoded picture in the current capture contract.
+func ValidVideoSize(width, height uint32) bool {
+ return width >= 2 && width <= MaxVideoWidth && width%2 == 0 &&
+ height >= 2 && height <= MaxVideoHeight && height%2 == 0
+}
+
type FrameKind uint8
const (
@@ -84,8 +92,7 @@ func parseFrameHeader(header []byte) (Frame, uint32, error) {
const maxTime100ns = uint64(1<<63-1) / 100
if timestamp100ns > maxTime100ns || duration100ns > maxTime100ns ||
(isTimed && duration100ns == 0) || (!isTimed && (timestamp100ns != 0 || duration100ns != 0)) ||
- (isVideo && (header[6] > 1 || layer >= maxOutputs || width < 2 || width > 2560 ||
- height < 2 || height > 1440 || width%2 != 0 || height%2 != 0)) ||
+ (isVideo && (header[6] > 1 || layer >= maxOutputs || !ValidVideoSize(width, height))) ||
(!isVideo && (header[6] != 0 || width != 0 || height != 0)) ||
(kind == FrameLayerUnavailable && layer >= maxOutputs) ||
(!isVideo && kind != FrameLayerUnavailable && layer != 0) {
diff --git a/internal/app/nativecapture/stream.go b/internal/app/nativecapture/stream.go
index 2b31d660..0df559bb 100644
--- a/internal/app/nativecapture/stream.go
+++ b/internal/app/nativecapture/stream.go
@@ -2,6 +2,7 @@ package nativecapture
import (
"context"
+ "encoding/json"
"errors"
"fmt"
"io"
@@ -19,11 +20,18 @@ import (
)
const (
- captureStopTimeout = time.Second
- maxPreviewBytes = 192 * 1024
- maxOutputs = 6
- minOutputBitrate = 1_000 // Codec rate APIs use whole kbps.
- maxOutputBitrate = 12_000_000
+ captureStopTimeout = time.Second
+ maxPreviewBytes = 192 * 1024
+ maxOutputs = 6
+ minOutputBitrate = 1_000 // Codec rate APIs use whole kbps.
+ maxOutputBitrate = 12_000_000
+ maxSources = 1024
+ maxSourceTitleBytes = 4096
+ // Leave room for the control envelope within loopback's 256 KiB message.
+ maxSourceListBytes = 192 * 1024
+ // A complete helper list may be larger than the returned prefix. Decode it
+ // incrementally; JSON escaping can use six bytes for each title byte.
+ maxSourceOutputBytes = maxSources*(maxSourceTitleBytes*6+256) + 2
)
var (
@@ -80,8 +88,7 @@ type OutputProfile struct {
}
func (profile OutputProfile) Valid() bool {
- return profile.Width >= 2 && profile.Width <= 2560 && profile.Width%2 == 0 &&
- profile.Height >= 2 && profile.Height <= 1440 && profile.Height%2 == 0 &&
+ return ValidVideoSize(profile.Width, profile.Height) &&
profile.Framerate >= 1 && profile.Framerate <= 60 &&
profile.Bitrate >= minOutputBitrate && profile.Bitrate <= maxOutputBitrate
}
@@ -137,25 +144,71 @@ type Stream struct {
func ListSources(parent context.Context, executable string) ([]CaptureTarget, error) {
ctx, cancel := context.WithTimeout(parent, probeTimeout)
defer cancel()
- stdout := &boundedBuffer{limit: maxProbeOutputBytes}
command := exec.CommandContext(ctx, executable, "--list")
- command.Stdout = stdout
stderr := diagnostics.Writer("native-source-list")
defer stderr.Close()
command.Stderr = stderr
hideWindow(command)
- if err := command.Run(); err != nil {
+ stdout, err := command.StdoutPipe()
+ if err != nil {
+ return nil, errors.New("native capture source list is unavailable")
+ }
+ if err := command.Start(); err != nil {
slog.DebugContext(ctx, "piik-client", "event", "capture-source-list-failed", diagnostics.Error(err), "canceled", ctx.Err() != nil)
return nil, errors.New("native capture source list is unavailable")
}
- var targets []CaptureTarget
- if err := decodeStrictJSON(stdout.Bytes(), &targets); err != nil || len(targets) > 1024 {
+ targets, readErr := readSources(stdout)
+ if readErr != nil {
+ cancel()
+ }
+ waitErr := command.Wait()
+ if waitErr != nil {
+ slog.DebugContext(ctx, "piik-client", "event", "capture-source-list-failed", diagnostics.Error(waitErr), "canceled", ctx.Err() != nil)
+ }
+ if readErr != nil {
return nil, errors.New("native capture source list is invalid")
}
- for _, target := range targets {
- if !target.Valid() {
- return nil, errors.New("native capture target is invalid")
+ if waitErr != nil {
+ return nil, errors.New("native capture source list is unavailable")
+ }
+ return targets, nil
+}
+
+func readSources(reader io.Reader) ([]CaptureTarget, error) {
+ input := &io.LimitedReader{R: reader, N: maxSourceOutputBytes + 1}
+ decoder := json.NewDecoder(input)
+ decoder.DisallowUnknownFields()
+ invalid := errors.New("native capture source list is invalid")
+ if token, err := decoder.Token(); err != nil || token != json.Delim('[') {
+ return nil, invalid
+ }
+ targets := make([]CaptureTarget, 0)
+ size := 2 // JSON array delimiters; subsequent entries also need a comma.
+ full := false
+ for count := 0; decoder.More(); count++ {
+ var target CaptureTarget
+ if count >= maxSources || decoder.Decode(&target) != nil || !target.Valid() {
+ return nil, invalid
+ }
+ if full {
+ continue
}
+ encoded, err := json.Marshal(target)
+ if err != nil {
+ return nil, invalid
+ }
+ if size+len(encoded)+1 > maxSourceListBytes {
+ full = true
+ continue
+ }
+ targets = append(targets, target)
+ size += len(encoded) + 1
+ }
+ if token, err := decoder.Token(); err != nil || token != json.Delim(']') {
+ return nil, invalid
+ }
+ if decoder.Decode(&struct{}{}) != io.EOF || input.N == 0 {
+ return nil, invalid
}
return targets, nil
}
@@ -355,7 +408,7 @@ func startAudioStreamWithTimeout(parent context.Context, executable string, argu
func (target CaptureTarget) Valid() bool {
if !positiveDecimal(target.SourceID) || len(target.Title) == 0 ||
- len(target.Title) > 4096 {
+ len(target.Title) > maxSourceTitleBytes {
return false
}
switch target.Kind {
diff --git a/internal/app/nativecapture/stream_test.go b/internal/app/nativecapture/stream_test.go
index e59f58f6..3aa8f23a 100644
--- a/internal/app/nativecapture/stream_test.go
+++ b/internal/app/nativecapture/stream_test.go
@@ -9,12 +9,75 @@ import (
"log/slog"
"os"
"path/filepath"
+ "strconv"
"strings"
"sync"
"testing"
"time"
)
+func TestSourceListBoundsFollowSerializedOutput(t *testing.T) {
+ for _, check := range []struct {
+ name, title string
+ count int
+ truncated bool
+ }{
+ {"empty", "Window", 0, false},
+ {"long-localized-titles", strings.Repeat("界", 512), 64, false},
+ {"many-windows", "Window", maxSources, false},
+ {"escaped-titles", strings.Repeat("<", 512), 100, true},
+ {"full-list", strings.Repeat("a", maxSourceTitleBytes), maxSources, true},
+ } {
+ t.Run(check.name, func(t *testing.T) {
+ targets := make([]CaptureTarget, check.count)
+ for index := range targets {
+ targets[index] = CaptureTarget{Kind: "window", SourceID: strconv.Itoa(index + 1),
+ PID: 1, CreationTime: "1", Title: check.title}
+ }
+ var input bytes.Buffer
+ encoder := json.NewEncoder(&input)
+ // The platform helpers need not use Go's HTML escaping.
+ encoder.SetEscapeHTML(false)
+ if err := encoder.Encode(targets); err != nil {
+ t.Fatal(err)
+ }
+ got, err := readSources(&input)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if (!check.truncated && len(got) != len(targets)) ||
+ (check.truncated && (len(got) == 0 || len(got) >= len(targets))) {
+ t.Fatalf("source count = %d of %d", len(got), len(targets))
+ }
+ for index, target := range got {
+ if target != targets[index] {
+ t.Fatal("bounded list changed a source's identity or title")
+ }
+ }
+ output, _ := json.Marshal(got)
+ if len(output) > maxSourceListBytes || string(output) == "null" {
+ t.Fatalf("source-list response exceeds its contract: %d bytes", len(output))
+ }
+ })
+ }
+}
+
+func TestSourceListRejectsMalformedOutputEvenAfterTheReturnedPrefix(t *testing.T) {
+ valid := `{"kind":"display","sourceId":"1","title":"Display"}`
+ full := `{"kind":"display","sourceId":"1","title":"` + strings.Repeat("a", maxSourceTitleBytes) + `"}`
+ for _, payload := range []string{
+ `null`, `{}`, `[`, `[` + valid, `[` + valid + `] []`,
+ `[{"kind":"display","sourceId":"1","title":"Display","extra":true}]`,
+ `[` + strings.Repeat(valid+",", maxSources) + valid + `]`,
+ `[` + strings.Repeat(full+",", 100) + `{"kind":"wrong","sourceId":"1","title":"Window"}]`,
+ `[]` + strings.Repeat(" ", maxSourceOutputBytes),
+ } {
+ if _, err := readSources(strings.NewReader(payload)); err == nil {
+ t.Fatal("invalid helper output was accepted")
+ }
+ }
+}
+
func TestCaptureStopHelper(t *testing.T) {
mode := os.Getenv("PIIK_CAPTURE_STOP_FIXTURE")
if mode == "" {
diff --git a/internal/app/nativecontrol/session_test.go b/internal/app/nativecontrol/session_test.go
index cad4b95f..d626d45c 100644
--- a/internal/app/nativecontrol/session_test.go
+++ b/internal/app/nativecontrol/session_test.go
@@ -89,6 +89,14 @@ func TestReceiveOfferReusePreservesLegacyResponseShape(t *testing.T) {
}
func TestMain(tests *testing.M) {
+ if path := os.Getenv("PIIK_SOURCE_LIST_FIXTURE"); path != "" {
+ payload, err := os.ReadFile(path)
+ if err != nil {
+ os.Exit(1)
+ }
+ _, _ = os.Stdout.Write(payload)
+ os.Exit(0)
+ }
if marker := os.Getenv("PIIK_SOURCE_PROBE_FIXTURE"); marker != "" {
if err := os.WriteFile(marker, nil, 0600); err != nil {
os.Exit(1)
@@ -103,6 +111,55 @@ func TestMain(tests *testing.M) {
os.Exit(tests.Run())
}
+func TestSourceListFitsTheControlEnvelope(t *testing.T) {
+ executable, err := os.Executable()
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, check := range []struct {
+ title string
+ count int
+ }{
+ {strings.Repeat("界", 512), 64},
+ {strings.Repeat("<", 512), 100},
+ } {
+ targets := make([]nativecapture.CaptureTarget, check.count)
+ for index := range targets {
+ targets[index] = nativecapture.CaptureTarget{Kind: "window", SourceID: strconv.Itoa(index + 1),
+ PID: 1, CreationTime: "1", Title: check.title}
+ }
+ var payload bytes.Buffer
+ encoder := json.NewEncoder(&payload)
+ encoder.SetEscapeHTML(false)
+ if err := encoder.Encode(targets); err != nil {
+ t.Fatal(err)
+ }
+ path := filepath.Join(t.TempDir(), "sources.json")
+ if err := os.WriteFile(path, payload.Bytes(), 0600); err != nil {
+ t.Fatal(err)
+ }
+ t.Setenv("PIIK_SOURCE_LIST_FIXTURE", path)
+ session := New(executable, nativecapture.Capabilities{}, false)
+ defer session.Close()
+ value, err := awaitControlResponse(t, session,
+ []byte(`{"version":9,"id":"request_sources","type":"list-sources"}`))
+ if err != nil {
+ t.Fatal(err)
+ }
+ response, ok := value.(sourceListResponse)
+ if !ok || len(response.Sources) == 0 {
+ t.Fatalf("usable sources were lost: %#v", value)
+ }
+ if check.count == 64 && len(response.Sources) != 64 {
+ t.Fatalf("localized windows were truncated: %d", len(response.Sources))
+ }
+ encoded, err := json.Marshal(response)
+ if err != nil || len(encoded) > loopback.MaxControlMessageBytes {
+ t.Fatalf("valid enumeration would close control: %d bytes, %v", len(encoded), err)
+ }
+ }
+}
+
func runQuietCaptureFixture(directory string) {
arguments, _ := json.Marshal(os.Args[1:])
if err := os.WriteFile(filepath.Join(directory, "arguments.json"), arguments, 0600); err != nil {
diff --git a/internal/app/nativehost/audio_mix_test.go b/internal/app/nativehost/audio_mix_test.go
index bbfb7e34..1e72e84c 100644
--- a/internal/app/nativehost/audio_mix_test.go
+++ b/internal/app/nativehost/audio_mix_test.go
@@ -105,7 +105,11 @@ func TestAudioExclusionFailureMutesOnlySourceAndNeverFallsBack(t *testing.T) {
}
video := session.stream
t.Setenv(fault, "1")
- if err := session.ReplaceSource(options, true, excluded); err == nil {
+ attempt := options
+ if fault == "PIIK_VIDEO_FAIL" {
+ attempt.Target.SourceID = "2"
+ }
+ if err := session.ReplaceSource(attempt, true, excluded); err == nil {
t.Fatal("failed exclusion was accepted", fault)
}
if session.SourceAudio() == nil || *session.SourceAudio() || session.audioStream != nil || session.stream != video {
@@ -165,6 +169,36 @@ func TestAudioExclusionFailureMutesOnlySourceAndNeverFallsBack(t *testing.T) {
}
}
+func TestSameVideoSourceAudioChangesPreserveCaptureAndConnections(t *testing.T) {
+ session, options, _ := startMixedFixture(t)
+ if _, err := session.PrepareLocalEdge("audio_change"); err != nil {
+ t.Fatal(err)
+ }
+ video, source, output, edge := session.stream, session.source, session.audioSource, session.edge("audio_change")
+ // New capture is deliberately unavailable; changing sound must still work.
+ t.Setenv("PIIK_VIDEO_FAIL", "1")
+ options.Target.Title = "Renamed display"
+ excluded := &nativecapture.CaptureTarget{Kind: "window", SourceID: "123", PID: 456, CreationTime: "789", Title: "Voice fixture"}
+ for _, selection := range []struct {
+ enabled bool
+ exclude *nativecapture.CaptureTarget
+ }{{true, excluded}, {false, nil}, {true, nil}} {
+ if err := session.ReplaceSource(options, selection.enabled, selection.exclude); err != nil {
+ t.Fatal(err)
+ }
+ if session.stream != video || session.source != source || session.audioSource != output || session.edge("audio_change") != edge {
+ t.Fatal("audio-only selection replaced capture or media owners")
+ }
+ if session.SourceAudio() == nil || *session.SourceAudio() != selection.enabled {
+ t.Fatal("source audio did not follow the selection")
+ }
+ }
+ options.ShowCaptureBorder = true
+ if err := session.ReplaceSource(options, true, nil); err == nil {
+ t.Fatal("a changed video option was mistaken for an audio-only update")
+ }
+}
+
func TestNativeMicrophonePreservesMediaOwnersAcrossInputChanges(t *testing.T) {
session, options, events := startMixedFixture(t)
check := func(err error) {
diff --git a/internal/app/nativehost/session.go b/internal/app/nativehost/session.go
index 4478a1b9..2fa37f30 100644
--- a/internal/app/nativehost/session.go
+++ b/internal/app/nativehost/session.go
@@ -419,6 +419,11 @@ func (session *Session) ReplaceSource(
options.EncoderIndex = session.videoOptions.EncoderIndex
options.OutputGroups = session.edgeCapacity
hasAudio := session.audioSource != nil && session.audioStream != nil
+ currentTarget := session.videoOptions.Target
+ audioOnly := options.Target.Kind != "picker" &&
+ options.Target.Kind == currentTarget.Kind && options.Target.SourceID == currentTarget.SourceID &&
+ options.Target.PID == currentTarget.PID && options.Target.CreationTime == currentTarget.CreationTime &&
+ options.ShowCaptureBorder == session.videoOptions.ShowCaptureBorder
session.mu.Unlock()
if session.mixer == nil && audioEnabled != hasAudio {
return errors.New("native source audio availability cannot change while sharing")
@@ -440,9 +445,14 @@ func (session *Session) ReplaceSource(
}
options.Profile = profile.Video
options.RestoreToken = ""
- replacement, state, err := session.prepareVideo(session.ctx, options, options.Target.Kind == "picker", false)
- if err != nil {
- return err
+ var replacement *nativecapture.Stream
+ var state CaptureState
+ var err error
+ if !audioOnly {
+ replacement, state, err = session.prepareVideo(session.ctx, options, options.Target.Kind == "picker", false)
+ if err != nil {
+ return err
+ }
}
var replacementAudio *nativecapture.Stream
if audioEnabled {
@@ -453,7 +463,9 @@ func (session *Session) ReplaceSource(
excludeAudio,
)
if err != nil {
- _ = replacement.Close()
+ if replacement != nil {
+ _ = replacement.Close()
+ }
return errors.New("native source audio could not start")
}
}
@@ -524,7 +536,9 @@ func (session *Session) commitCapture(
session.mu.Lock()
if session.closed || session.ctx.Err() != nil {
session.mu.Unlock()
- _ = replacement.Close()
+ if replacement != nil {
+ _ = replacement.Close()
+ }
if replacementAudio != nil {
_ = replacementAudio.Close()
}
@@ -532,14 +546,20 @@ func (session *Session) commitCapture(
}
previous := session.stream
previousAudio := session.audioStream
- if state.RestoreToken != "" {
- options.RestoreToken = state.RestoreToken
- }
- state.applyBackend(&options)
- session.stream = replacement
- applied := make(chan struct{})
- session.captureApplied = applied
- session.captureUnavailable = state.unavailableLayers
+ var applied chan struct{}
+ // A source-audio change retains the current capture generation and encoder.
+ if replacement != nil {
+ if state.RestoreToken != "" {
+ options.RestoreToken = state.RestoreToken
+ }
+ state.applyBackend(&options)
+ session.stream = replacement
+ applied = make(chan struct{})
+ session.captureApplied = applied
+ session.captureUnavailable = state.unavailableLayers
+ session.videoOptions = options
+ session.profile = profile
+ }
if replaceAudio {
session.audioStream = replacementAudio
select {
@@ -547,18 +567,19 @@ func (session *Session) commitCapture(
default:
}
}
- session.videoOptions = options
- session.profile = profile
session.mu.Unlock()
if replaceAudio && session.mixer != nil {
session.mixer.setSource(replacementAudio)
}
- _ = replacement.RequestKeyFrame(-1)
- _ = previous.Close()
if replaceAudio && previousAudio != nil {
_ = previousAudio.Close()
}
+ if replacement == nil {
+ return nil
+ }
+ _ = replacement.RequestKeyFrame(-1)
+ _ = previous.Close()
select {
case <-applied:
case <-session.ctx.Done():
diff --git a/internal/app/portmapping/mapping.go b/internal/app/portmapping/mapping.go
index 09978481..d0a7c9fd 100644
--- a/internal/app/portmapping/mapping.go
+++ b/internal/app/portmapping/mapping.go
@@ -15,8 +15,8 @@ const (
// five-second direct-connection head start.
attemptTimeout = 3 * time.Second
deleteTimeout = 2 * time.Second
- // RFC 6886 recommends a two-hour NAT-PMP lease; later gatherings renew it at
- // half-life without adding a background poller.
+ // RFC 6886 recommends requesting a two-hour NAT-PMP lease. A new gathering
+ // revalidates it: gateway state can disappear before the requested expiry.
leaseDuration = 2 * time.Hour
)
@@ -43,7 +43,6 @@ type Mapping struct {
mapped bool
externalPort int
attemptDone chan struct{}
- renewAfter time.Time
closed bool
}
@@ -59,6 +58,8 @@ func Start(localPort int) *Mapping {
return mapping
}
+// Prepare confirms the mapping for one ICE gathering. The gathering calls it
+// once; ordinary renegotiation does not create a gathering or refresh mappings.
func (mapping *Mapping) Prepare() int {
<-mapping.ready
mapping.mu.Lock()
@@ -67,9 +68,6 @@ func (mapping *Mapping) Prepare() int {
(mapping.attempted && !mapping.mapped) {
return 0
}
- if mapping.mapped && time.Now().Before(mapping.renewAfter) {
- return mapping.externalPort
- }
ctx, cancel := context.WithTimeout(mapping.ctx, attemptTimeout)
defer cancel()
mapping.mapPortLocked(ctx)
@@ -174,5 +172,4 @@ func (mapping *Mapping) mapPortLocked(ctx context.Context) {
}
mapping.mapped = true
mapping.externalPort = externalPort
- mapping.renewAfter = time.Now().Add(leaseDuration / 2)
}
diff --git a/internal/app/portmapping/mapping_test.go b/internal/app/portmapping/mapping_test.go
index c916345d..0311a813 100644
--- a/internal/app/portmapping/mapping_test.go
+++ b/internal/app/portmapping/mapping_test.go
@@ -9,11 +9,12 @@ import (
)
type fakeGateway struct {
- mu sync.Mutex
- added []int
- deleted []int
- addErr error
- block chan struct{}
+ mu sync.Mutex
+ added []int
+ deleted []int
+ addErr error
+ block chan struct{}
+ externalPort int
}
func (gateway *fakeGateway) AddPortMapping(
@@ -27,6 +28,7 @@ func (gateway *fakeGateway) AddPortMapping(
gateway.added = append(gateway.added, port)
block := gateway.block
addErr := gateway.addErr
+ externalPort := gateway.externalPort
gateway.mu.Unlock()
if block != nil {
// Exercise the caller's bound even if a gateway fails to observe context.
@@ -35,6 +37,9 @@ func (gateway *fakeGateway) AddPortMapping(
if addErr != nil {
return 0, addErr
}
+ if externalPort != 0 {
+ return externalPort, nil
+ }
return port + 1, nil
}
func (gateway *fakeGateway) DeletePortMapping(
@@ -48,7 +53,7 @@ func (gateway *fakeGateway) DeletePortMapping(
return nil
}
-func TestMappingCreatesOnceAndReleases(t *testing.T) {
+func TestMappingRefreshesForEachGatheringAndReleasesOnce(t *testing.T) {
original := discoverGateway
t.Cleanup(func() { discoverGateway = original })
fake := &fakeGateway{}
@@ -61,15 +66,15 @@ func TestMappingCreatesOnceAndReleases(t *testing.T) {
t.Fatalf("mapped port = %d, want 43211", port)
}
if port := mapping.Prepare(); port != 43211 {
- t.Fatalf("cached mapped port = %d, want 43211", port)
+ t.Fatalf("refreshed mapped port = %d, want 43211", port)
}
mapping.Close()
mapping.Close()
fake.mu.Lock()
defer fake.mu.Unlock()
- if len(fake.added) != 1 || fake.added[0] != 43210 {
- t.Fatalf("added ports = %v, want [43210]", fake.added)
+ if len(fake.added) != 2 || fake.added[0] != 43210 || fake.added[1] != 43210 {
+ t.Fatalf("added ports = %v, want [43210 43210]", fake.added)
}
if len(fake.deleted) != 1 || fake.deleted[0] != 43210 {
t.Fatalf("deleted ports = %v, want [43210]", fake.deleted)
@@ -88,6 +93,26 @@ func TestMappingAbsenceLeavesICEAvailable(t *testing.T) {
mapping.Close()
}
+func TestMappingGatheringAfterGatewayStateLossUsesNewAllocation(t *testing.T) {
+ original := discoverGateway
+ t.Cleanup(func() { discoverGateway = original })
+ fake := &fakeGateway{externalPort: 43211}
+ discoverGateway = func(context.Context) (gateway, error) { return fake, nil }
+ mapping := Start(43210)
+ t.Cleanup(mapping.Close)
+ if port := mapping.Prepare(); port != 43211 {
+ t.Fatalf("initial mapped port = %d", port)
+ }
+ // A gateway reset can discard a mapping before its requested lease expires.
+ // An ICE restart retains this connection/socket and starts a fresh gathering.
+ fake.mu.Lock()
+ fake.externalPort = 43212
+ fake.mu.Unlock()
+ if port := mapping.Prepare(); port != 43212 {
+ t.Fatalf("new gathering advertised stale mapped port %d, want 43212", port)
+ }
+}
+
func TestMappingFailureIsNotRetriedWithinTheConnection(t *testing.T) {
original := discoverGateway
t.Cleanup(func() { discoverGateway = original })
@@ -140,9 +165,6 @@ func TestCloseSkipsDeleteWhileAnAttemptIsStillAbandoned(t *testing.T) {
if port := mapping.Prepare(); port != 43211 {
t.Fatalf("mapped port = %d, want 43211", port)
}
- mapping.mu.Lock()
- mapping.renewAfter = time.Now().Add(-time.Second)
- mapping.mu.Unlock()
fake.mu.Lock()
fake.block = make(chan struct{})
fake.mu.Unlock()
@@ -175,13 +197,12 @@ func TestRenewalFailureKeepsTheOriginalMappingOwnedUntilClose(t *testing.T) {
mapping := Start(43210)
mapping.Prepare()
- mapping.mu.Lock()
- mapping.renewAfter = time.Now().Add(-time.Second)
- mapping.mu.Unlock()
fake.mu.Lock()
fake.addErr = errors.New("renewal rejected")
fake.mu.Unlock()
- mapping.Prepare()
+ if port := mapping.Prepare(); port != 0 {
+ t.Fatalf("failed renewal advertised stale port %d", port)
+ }
mapping.Close()
fake.mu.Lock()
diff --git a/native/capture/windows/README.md b/native/capture/windows/README.md
index 83fea642..51f7dd64 100644
--- a/native/capture/windows/README.md
+++ b/native/capture/windows/README.md
@@ -33,7 +33,9 @@ unavailable instead of failing the whole source. Process loopback is probed by
activation rather than inferred from a Windows build number; display sources
normally use the standard render-device loopback available on Windows 10 and
later. The optional `--capture-audio exclude <pid> <creation-time>` mode requires
-build 20348+ and a successful exclusion probe. It captures all output devices
+build 19041+ and a successful exclusion-mode probe. Windows 10 isolation still
+needs physical verification; see the [audio evidence](../../../docs/research/native-client-media.md#windows-audio-exclusion).
+It captures all output devices
except the selected process tree, and retires when that process exits. The
[screen-audio contract](../../../docs/standards/media-quality.md#screen-audio)
owns selection and failure behavior.
diff --git a/native/capture/windows/adaptive_encoder.cpp b/native/capture/windows/adaptive_encoder.cpp
index f3ae4c5f..8c5a4edc 100644
--- a/native/capture/windows/adaptive_encoder.cpp
+++ b/native/capture/windows/adaptive_encoder.cpp
@@ -207,6 +207,11 @@ class HardwareEncoder final : public webrtc::VideoEncoder {
applied_bitrate_ = profile_.bit_rate;
return WEBRTC_VIDEO_CODEC_OK;
} catch (...) {
+ if (config) {
+ std::osyncstream(std::cerr) << "event=encoder-initialization-failed codec=h264 width="
+ << config->width << " height=" << config->height
+ << " fps=" << config->maxFramerate << " bitrate=" << config->startBitrate * 1000 << '\n';
+ }
failure_.Capture();
Release();
return WEBRTC_VIDEO_CODEC_ENCODER_FAILURE;
diff --git a/native/capture/windows/capture_target.cpp b/native/capture/windows/capture_target.cpp
index 4675cb3e..f9a789cc 100644
--- a/native/capture/windows/capture_target.cpp
+++ b/native/capture/windows/capture_target.cpp
@@ -169,10 +169,13 @@ BOOL CALLBACK CollectWindow(HWND window, LPARAM parameter) {
auto* targets = reinterpret_cast<std::vector<SourceTarget>*>(parameter);
// FALSE makes EnumWindows report failure; a full list is still usable.
if (targets->size() >= kMaxSources) return TRUE;
- if (!IsWindowVisible(window) || GetWindow(window, GW_OWNER) != nullptr) {
+ if (!IsWindowVisible(window)) return TRUE;
+ const LONG_PTR extended_style = GetWindowLongPtrW(window, GWL_EXSTYLE);
+ // An owned window can still be an independent taskbar application window.
+ if (GetWindow(window, GW_OWNER) != nullptr &&
+ (extended_style & WS_EX_APPWINDOW) == 0) {
return TRUE;
}
- const LONG_PTR extended_style = GetWindowLongPtrW(window, GWL_EXSTYLE);
if ((extended_style & WS_EX_TOOLWINDOW) != 0 ||
(extended_style & WS_EX_NOACTIVATE) != 0) {
return TRUE;
diff --git a/native/capture/windows/capture_target.test.cpp b/native/capture/windows/capture_target.test.cpp
index 4f026287..b3d9895c 100644
--- a/native/capture/windows/capture_target.test.cpp
+++ b/native/capture/windows/capture_target.test.cpp
@@ -2,8 +2,62 @@
#include <cassert>
#include <iostream>
+#include <sstream>
+#include <string>
-int main() {
+namespace {
+
+void CheckOwnedApplicationWindow() {
+ HWND owner = CreateWindowExW(0, L"STATIC", L"Piik enumeration owner",
+ WS_OVERLAPPEDWINDOW, 0, 0, 320, 180, nullptr, nullptr, nullptr, nullptr);
+ assert(owner != nullptr);
+ HWND application = CreateWindowExW(WS_EX_APPWINDOW, L"STATIC", L"Piik owned application",
+ WS_OVERLAPPEDWINDOW, 0, 0, 320, 180, owner, nullptr, nullptr, nullptr);
+ HWND dialog = CreateWindowExW(0, L"STATIC", L"Piik owned dialog",
+ WS_OVERLAPPEDWINDOW, 0, 0, 320, 180, owner, nullptr, nullptr, nullptr);
+ assert(application != nullptr && dialog != nullptr);
+ ShowWindow(application, SW_SHOWNOACTIVATE);
+ ShowWindow(dialog, SW_SHOWNOACTIVATE);
+
+ // Enumerate from a child: the real picker excludes its own process.
+ wchar_t executable[MAX_PATH]{};
+ assert(GetModuleFileNameW(nullptr, executable, MAX_PATH) > 0);
+ std::wstring command = L"\"" + std::wstring(executable) + L"\" --check-enumeration " +
+ std::to_wstring(reinterpret_cast<UINT_PTR>(application)) + L" " +
+ std::to_wstring(reinterpret_cast<UINT_PTR>(dialog));
+ STARTUPINFOW startup{};
+ startup.cb = sizeof(startup);
+ PROCESS_INFORMATION process{};
+ assert(CreateProcessW(executable, command.data(), nullptr, nullptr, FALSE,
+ CREATE_NO_WINDOW, nullptr, nullptr, &startup, &process));
+ const DWORD wait = WaitForSingleObject(process.hProcess, 5000);
+ if (wait != WAIT_OBJECT_0) {
+ TerminateProcess(process.hProcess, 1);
+ WaitForSingleObject(process.hProcess, 1000);
+ }
+ DWORD exit_code = 1;
+ assert(GetExitCodeProcess(process.hProcess, &exit_code));
+ CloseHandle(process.hThread);
+ CloseHandle(process.hProcess);
+ DestroyWindow(owner);
+ assert(wait == WAIT_OBJECT_0 && exit_code == 0);
+}
+
+} // namespace
+
+int wmain(int count, wchar_t** arguments) {
+ if (count == 4 && std::wstring(arguments[1]) == L"--check-enumeration") {
+ std::ostringstream sources;
+ auto* output = std::cout.rdbuf(sources.rdbuf());
+ const int result = piik::capture::WriteSourceList();
+ std::cout.rdbuf(output);
+ const auto listed = [&](const wchar_t* id) {
+ return sources.str().find("\"sourceId\":\"" +
+ std::to_string(std::stoull(id)) + "\"") != std::string::npos;
+ };
+ return result == 0 && listed(arguments[2]) && !listed(arguments[3]) ? 0 : 1;
+ }
+ CheckOwnedApplicationWindow();
// Enumeration and preview are separate operations. A once-listed window may
// become hidden before WGC creates its item. Unsupported capture may return
// an advisory error or a fallback preview, but cleanup must never crash.
@@ -28,5 +82,5 @@ int main() {
SetStdHandle(STD_OUTPUT_HANDLE, previous_output);
CloseHandle(sink);
DestroyWindow(window);
- std::cout << "Capture preview failure cleanup passed.\n";
+ std::cout << "Capture enumeration and preview failure cleanup passed.\n";
}
diff --git a/native/capture/windows/main.cpp b/native/capture/windows/main.cpp
index 700d1089..839e6b3d 100644
--- a/native/capture/windows/main.cpp
+++ b/native/capture/windows/main.cpp
@@ -1171,7 +1171,6 @@ UINT32 WindowsBuild() {
void WriteCapabilityProbe() {
constexpr UINT32 kCreateForWindowMinimumBuild = 18'362;
constexpr UINT32 kProcessLoopbackMinimumBuild = 19'041;
- constexpr UINT32 kProcessExclusionMinimumBuild = 20'348;
const UINT32 build = WindowsBuild();
bool window_capture = false;
if (build >= kCreateForWindowMinimumBuild) {
@@ -1186,7 +1185,9 @@ void WriteCapabilityProbe() {
build >= kProcessLoopbackMinimumBuild &&
piik::capture::ProcessAudioAvailable();
const bool system_audio = piik::capture::SystemAudioAvailable();
- const bool process_audio_exclusion = build >= kProcessExclusionMinimumBuild &&
+ // Process loopback was backported to Windows 10 2004. Probe each mode;
+ // the documented 20348 minimum must not hide a working exclusion interface.
+ const bool process_audio_exclusion = build >= kProcessLoopbackMinimumBuild &&
piik::capture::ProcessAudioAvailable(true);
std::vector<Adapter> adapters = EnumerateAdapters();
@@ -1943,7 +1944,10 @@ void RunVideoCapture(ProductArguments arguments) {
const HANDLE window_waits[] = {
process.get(), shutdown.get(), frame_ready.get()};
const HANDLE display_waits[] = {shutdown.get(), frame_ready.get()};
+ bool source_was_minimized = false;
for (;;) {
+ if (window_target && IsIconic(reinterpret_cast<HWND>(
+ static_cast<UINT_PTR>(arguments.source_id)))) source_was_minimized = true;
for (const auto& control : controls.Read()) {
if (control.kind == 'Q') {
cleanup();
@@ -1997,6 +2001,21 @@ void RunVideoCapture(ProductArguments arguments) {
latest = std::move(next);
}
if (!latest) continue;
+ // Minimized content is a placeholder, including queued frames after
+ // restoration. Retire that pool generation before admitting pictures.
+ if (window_target && IsIconic(reinterpret_cast<HWND>(
+ static_cast<UINT_PTR>(arguments.source_id)))) {
+ source_was_minimized = true;
+ latest.Close();
+ continue;
+ }
+ if (source_was_minimized) {
+ latest.Close();
+ latest = nullptr;
+ pool.Recreate(capture_device, static_cast<DirectXPixelFormat>(pool_format), 2, pool_size);
+ source_was_minimized = false;
+ continue;
+ }
INT64 signed_timestamp = latest.SystemRelativeTime().count();
if (signed_timestamp <= 0) {
Fail("capture-timestamp", "captured frame has no QPC timestamp");
diff --git a/scripts/build-website.mjs b/scripts/build-website.mjs
index dbe03d19..3f875f9d 100644
--- a/scripts/build-website.mjs
+++ b/scripts/build-website.mjs
@@ -1,5 +1,6 @@
import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
+import { extname, relative, resolve } from "node:path";
import { build } from "esbuild";
import { writeWebLicenseNotices } from "./package-licenses.mjs";
import { createElement } from "react";
@@ -15,6 +16,8 @@ await cp(source, output, {
recursive: true,
filter: (path) =>
path !== fileURLToPath(new URL("docs", source)) &&
+ !path.endsWith(".js") &&
+ !path.endsWith(".css") &&
!path.endsWith(".ts") &&
!path.endsWith(".tsx") &&
!path.endsWith("tsconfig.json") &&
@@ -36,14 +39,6 @@ const homepage = (await readFile(new URL("index.html", source), "utf8"))
await writeFile(new URL("index.html", output), homepage.replace(
'</body>', `<template id="welcome-lines">${welcomePools.flat().join('')}</template></body>`,
));
-// The page shares only the small, DOM-based rotation owner with the product UI.
-await build({
- entryPoints: [fileURLToPath(new URL("main.js", source))],
- outfile: fileURLToPath(new URL("main.js", output)),
- bundle: true,
- format: "esm",
- minify: true,
-});
// The opening shot uses the current homepage, with only its film clock adapter
// substituted for the ordinary page script. Keep its layout and copy in one place.
await writeFile(new URL("film/ui/website.html", output),
@@ -59,28 +54,40 @@ await writeFile(filmPage, (await readFile(filmPage, "utf8")).replace(
/<span data-glyph="([a-zA-Z]+)"><\/span>/g,
(_, name) => renderToStaticMarkup(createElement(Glyph, { name, size: 21 })),
));
-await cp(
- new URL("../src/client/components/living/playback-controls.css", import.meta.url),
- new URL("film/playback-controls.css", output),
-);
-await cp(
- new URL("../src/client/components/living/brand-mark.css", import.meta.url),
- new URL("film/brand-mark.css", output),
-);
writeWebLicenseNotices(
fileURLToPath(new URL("../", import.meta.url)),
fileURLToPath(new URL("film/ui/third-party-licenses.txt", output)),
);
-await build({
- entryPoints: {
- ui: fileURLToPath(new URL("../site/film/ui/main.tsx", import.meta.url)),
- website: fileURLToPath(new URL("../site/film/ui/website.ts", import.meta.url)),
- },
- outdir: fileURLToPath(new URL("film/ui/", output)),
+const sharedBuild = {
+ outdir: fileURLToPath(output),
+ entryNames: "[dir]/[name]-[hash]",
bundle: true,
+ minify: true,
+ metafile: true,
+};
+const pageEntries = {
+ main: fileURLToPath(new URL("main.js", source)),
+ styles: fileURLToPath(new URL("styles.css", source)),
+ "assets/brand": fileURLToPath(new URL("assets/brand.css", source)),
+ "film/player": fileURLToPath(new URL("film/player.js", source)),
+ "film/film": fileURLToPath(new URL("film/film.css", source)),
+ "film/playback-controls": fileURLToPath(new URL("../src/client/components/living/playback-controls.css", import.meta.url)),
+ "film/brand-mark": fileURLToPath(new URL("../src/client/components/living/brand-mark.css", import.meta.url)),
+};
+const demoEntries = {
+ "film/ui/ui": fileURLToPath(new URL("film/ui/main.tsx", source)),
+ "film/ui/website": fileURLToPath(new URL("film/ui/website.ts", source)),
+};
+const pageAssets = await build({
+ ...sharedBuild,
+ entryPoints: pageEntries,
+ format: "esm",
+});
+const demoAssets = await build({
+ ...sharedBuild,
+ entryPoints: demoEntries,
format: "iife",
jsx: "automatic",
- minify: true,
legalComments: "linked",
define: {
"import.meta": "piikFilmBuild",
@@ -90,6 +97,34 @@ await build({
js: "const piikFilmBuild = { url: document.currentScript.src, env: { DEV: false } };",
},
});
+// HTML and its scripts/styles must share a content identity across CDN caches.
+// Bundle imports too, so a fresh entry cannot load a stale fixed-name dependency.
+const assets = new Map();
+const entries = new Map(Object.entries({ ...pageEntries, ...demoEntries }).map(([name, path]) => [path, name]));
+const outputPath = path => relative(fileURLToPath(output), resolve(path)).replaceAll("\\", "/");
+for (const [path, metadata] of Object.entries({ ...pageAssets.metafile.outputs, ...demoAssets.metafile.outputs })) {
+ if (!metadata.entryPoint) continue;
+ const name = entries.get(resolve(metadata.entryPoint));
+ if (!name) throw new Error(`Unknown website entry: ${metadata.entryPoint}`);
+ assets.set(name + extname(path), outputPath(path));
+ if (metadata.cssBundle) assets.set(name + ".css", outputPath(metadata.cssBundle));
+}
+for (const [page, base] of [
+ ["index.html", ""], ["film/index.html", "film/"],
+ ["film/ui/index.html", "film/ui/"], ["film/ui/website.html", ""],
+]) {
+ const location = new URL(page, output);
+ const html = (await readFile(location, "utf8")).replace(
+ /\b(src|href)="([^"?#]+\.(?:js|css))"/g,
+ (_, attribute, href) => {
+ const key = new URL(href, `https://piik.invalid/${base}`).pathname.slice(1);
+ const asset = assets.get(key);
+ if (!asset) throw new Error(`Unbundled website asset: ${page}: ${href}`);
+ return `${attribute}="./${relative(base || ".", asset).replaceAll("\\", "/")}"`;
+ },
+ );
+ await writeFile(location, html);
+}
await buildDocumentation();
console.log(
"Website built in build/site (static files, including the shared product UI).",
diff --git a/site/styles.css b/site/styles.css
index 8d311a23..25663a12 100644
--- a/site/styles.css
+++ b/site/styles.css
@@ -19,6 +19,7 @@
--couch: #e9ad63;
--couch-dark: #cd8845;
--comic-beat: 3.2s;
+ --spring: cubic-bezier(.3, 1.45, .45, 1);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) { color-scheme: dark; --wall: #14232b; --paper: #1b2d34; --ink: #eef4eb; --muted: #b3c4bd; --line: #3b5155; --green: #9bdbb2; --orange: #f28d66; --soft-orange: #3d342c; --button-ink: #14232b; }
@@ -128,13 +129,16 @@ h3 { font-size: 21px; font-weight: 700; letter-spacing: -.03em; line-height: 1.3
.platform-mark svg { width: 30px; height: 30px; }
.download-card h3 { font-size: 25px; }
.download-card > p { margin-top: 8px; color: var(--muted); font-size: 12px; line-height: 1.8; }
-.download-architecture { display: flex; flex-wrap: wrap; gap: 4px; min-width: 0; max-width: 100%; margin: 16px 0 20px; padding: 4px; border: 1px solid var(--line); border-radius: 24px; background: var(--wall); }
-.download-architecture label { position: relative; }
+.download-architecture { position: relative; display: inline-grid; grid-auto-flow: column; grid-auto-columns: 1fr; min-width: 0; max-width: 100%; margin: 16px 0 20px; padding: 4px; border: 1px solid var(--line); border-radius: 24px; background: var(--wall); }
+.download-architecture:not(:disabled)::before { content: ""; position: absolute; inset: 4px auto 4px 4px; box-sizing: border-box; width: calc((100% - 8px) / 2); border: 1px solid var(--line); border-radius: 18px; background: var(--paper); box-shadow: 0 2px 0 color-mix(in srgb, var(--line) 40%, transparent); transition: transform 260ms var(--spring); pointer-events: none; }
+.download-architecture:has(> label:nth-of-type(2) input:checked)::before { transform: translateX(100%); }
+.download-architecture label { position: relative; min-width: 0; }
.download-architecture input { position: absolute; inset: 0; width: 100%; height: 100%; margin: 0; opacity: 0; cursor: pointer; }
.download-architecture input:disabled { cursor: default; }
-.download-architecture label > span { display: flex; align-items: center; justify-content: center; min-height: 36px; padding: 6px 12px; border: 1px solid transparent; border-radius: 18px; font-size: 12px; font-weight: 600; transition: background .18s ease, color .18s ease, box-shadow .18s ease; }
-.download-architecture input:checked + span { background: var(--paper); color: var(--green); border-color: var(--line); box-shadow: 0 2px 0 color-mix(in srgb, var(--line) 40%, transparent); }
-.download-architecture input:enabled:hover + span { color: var(--green); background: var(--paper); }
+.download-architecture label > span { position: relative; display: flex; align-items: center; justify-content: center; height: 100%; min-height: 36px; padding: 6px 12px; border: 1px solid transparent; border-radius: 18px; font-size: 12px; font-weight: 600; pointer-events: none; transition: color 140ms ease, transform 180ms var(--spring); }
+.download-architecture input:checked + span { color: var(--green); }
+.download-architecture input:enabled:is(:hover, :focus-visible) + span { color: var(--green); transform: translateY(-1px); }
+.download-architecture input:enabled:active + span { transform: scale(.9); }
.download-architecture input:focus-visible + span { outline: 3px solid var(--orange); outline-offset: 3px; }
.download-architecture:disabled { border-color: transparent; background: transparent; padding-inline: 0; }
.download-architecture:disabled label > span { padding-inline: 0; border-color: transparent; background: transparent; color: var(--muted); box-shadow: none; }
@@ -338,8 +342,8 @@ html[lang="zh-CN"] .eyebrow { letter-spacing: .13em; }
@media (prefers-reduced-motion: reduce) {
html { scroll-behavior: auto; }
*, *::before, *::after { transition: none !important; }
- .button:not(:disabled):is(:hover, :focus-visible, :active), .button:not(:disabled):is(:hover, :focus-visible) svg { transform: none; }
+ .button:not(:disabled):is(:hover, :focus-visible, :active), .button:not(:disabled):is(:hover, :focus-visible) svg, .download-architecture input:enabled:is(:hover, :focus-visible, :active) + span { transform: none; }
}
html[data-reduced-motion] { scroll-behavior: auto; }
html[data-reduced-motion] *, html[data-reduced-motion] *::before, html[data-reduced-motion] *::after { animation: none !important; transition: none !important; }
-html[data-reduced-motion] :is(.button, .button svg, .film-play, .project-tv) { transform: none !important; }
+html[data-reduced-motion] :is(.button, .button svg, .film-play, .project-tv, .download-architecture label > span) { transform: none !important; }
diff --git a/src/client/components/living/AudioExclusionSelect.tsx b/src/client/components/living/AudioExclusionSelect.tsx
new file mode 100644
index 00000000..3192b2a2
--- /dev/null
+++ b/src/client/components/living/AudioExclusionSelect.tsx
@@ -0,0 +1,64 @@
+import { useEffect, useId, useState } from "react";
+import type { NativeCaptureTarget } from "../../native/wire";
+import { audioApplicationKey, audioApplications } from "../../native/capture-selection";
+import { useCopy } from "../../ui/copy";
+import { Glyph } from "../../ui/icons";
+import { Tooltip } from "./Tooltip";
+
+export function AudioExclusionSelect({ sources, value, onChange, disabled, busy, failed, onRefresh, showLabel = true }: {
+ sources: NativeCaptureTarget[]; value?: NativeCaptureTarget;
+ onChange: (target: NativeCaptureTarget | undefined) => void;
+ disabled?: boolean; busy?: boolean; failed?: boolean; onRefresh?: () => void; showLabel?: boolean;
+}) {
+ const { t, vis } = useCopy();
+ const id = useId();
+ const applications = audioApplications(sources);
+ const key = value ? audioApplicationKey(value) : "";
+ const missing = !!value && !applications.some(target => audioApplicationKey(target) === key);
+ return <div className="lr-capture-device lr-audio-exclusion-select">
+ {showLabel && <Tooltip kind="hint-exclude-audio" text={vis ? undefined : t("host.sourcePicker.excludeAudioHint")}>
+ <label htmlFor={id}>
+ <Glyph name="speakerOff" size={16} />
+ {vis ? null : t("host.sourcePicker.excludeAudio")}
+ </label>
+ </Tooltip>}
+ <div className="lr-capture-device-controls">
+ <select id={id} value={key} disabled={disabled || busy}
+ aria-label={t("host.sourcePicker.excludeAudio")} aria-describedby={`${id}-hint`}
+ onChange={event => onChange(applications.find(target => audioApplicationKey(target) === event.target.value))}>
+ <option value="">{t("host.sourcePicker.excludeNone")}</option>
+ {missing && <option value={key} disabled>{value.title} · {t("host.sourcePicker.excludeMissing")}</option>}
+ {applications.map(target => <option key={audioApplicationKey(target)} value={audioApplicationKey(target)}>{target.title}</option>)}
+ </select>
+ {onRefresh && <button type="button" className="lr-btn lr-device-refresh" disabled={disabled || busy}
+ aria-label={t("host.sourcePicker.refreshApplications")} onClick={onRefresh}>
+ <Glyph name="refresh" size={16} className={busy ? "lr-spin" : undefined} />
+ </button>}
+ </div>
+ <small id={`${id}-hint`} role={failed ? "status" : undefined} className={vis ? "visually-hidden" : undefined}>
+ {t(failed ? "host.sourcePicker.excludeListFailed" : value ? "host.sourcePicker.excludeAudioLifetime" : "host.sourcePicker.excludeAudioChoose")}
+ </small>
+ </div>;
+}
+
+// Reuse native source enumeration. The Host owns applying the selected audio input.
+export function LiveAudioExclusion({ load, ...selection }: {
+ load: () => Promise<NativeCaptureTarget[]>;
+ value?: NativeCaptureTarget; onChange: (target: NativeCaptureTarget | undefined) => void; disabled?: boolean;
+}) {
+ const [sources, setSources] = useState<NativeCaptureTarget[]>([]);
+ const [busy, setBusy] = useState(true);
+ const [failed, setFailed] = useState(false);
+ const [revision, setRevision] = useState(0);
+ useEffect(() => {
+ let current = true;
+ setBusy(true);
+ void load().then(sources => {
+ if (current) { setSources(sources); setFailed(false); }
+ }, () => { if (current) setFailed(true); })
+ .finally(() => { if (current) setBusy(false); });
+ return () => { current = false; };
+ }, [load, revision]);
+ return <AudioExclusionSelect {...selection} sources={sources} busy={busy} failed={failed}
+ onRefresh={() => setRevision(value => value + 1)} />;
+}
diff --git a/src/client/components/living/CaptureSourcePicker.tsx b/src/client/components/living/CaptureSourcePicker.tsx
index 11810e9a..ff29a7a7 100644
--- a/src/client/components/living/CaptureSourcePicker.tsx
+++ b/src/client/components/living/CaptureSourcePicker.tsx
@@ -1,7 +1,7 @@
import { useCallback, useEffect, useId, useRef, useState } from "react";
import type { NativeCaptureTarget } from "../../native/wire";
-import { nativeCaptureTargetKey } from "../../native/capture-selection";
+import { audioApplicationKey, audioApplications, nativeCaptureTargetKey } from "../../native/capture-selection";
import { useCopy } from "../../ui/copy";
import { Glyph, type GlyphName } from "../../ui/icons";
import { Tooltip } from "./Tooltip";
@@ -9,6 +9,7 @@ import { HintComic } from "./hints";
import { Pill } from "./primitives";
import { CameraSources, useCameraSources } from "./CameraSources";
import { CaptureSourceCard } from "./CaptureSourceCard";
+import { AudioExclusionSelect } from "./AudioExclusionSelect";
import type { loadCameraPreviews } from "../../media/camera-previews";
const SOURCE_TABS = ["browser", "camera", "window", "display"] as const;
@@ -127,12 +128,10 @@ export function CaptureSourcePicker({
: nativeSources.systemAudio);
const anyNativeAudio = sources.some(supportsAudio);
// Source enumeration already owns process identity; do not create a second app scanner.
- const audioApplications = nativeSources.kind === "ready"
- ? [...new Map(nativeSources.sources.filter(target => target.kind === "window")
- .map(target => [`${target.pid}:${target.creationTime}`, target])).values()] : [];
- const exclusionKey = excludeAudio?.kind === "window" ? `${excludeAudio.pid}:${excludeAudio.creationTime}` : "";
+ const applications = nativeSources.kind === "ready" ? audioApplications(nativeSources.sources) : [];
+ const exclusionKey = excludeAudio ? audioApplicationKey(excludeAudio) : "";
const canExcludeAudio = activeTab === "display" && nativeSources.kind === "ready" && nativeSources.processAudioExclusion;
- const missingExclusion = !!excludeAudio && !audioApplications.some(target => `${target.pid}:${target.creationTime}` === exclusionKey);
+ const missingExclusion = !!excludeAudio && !applications.some(target => audioApplicationKey(target) === exclusionKey);
const exclusionUnavailable = activeTab === "display" && shareAudio && !!excludeAudio && (!canExcludeAudio || missingExclusion);
const refreshing = activeTab === "camera" ? cameraSources.busy : nativeSources.kind === "loading";
const refreshLabel = t(refreshing ? "host.sourcePicker.loading" : "host.sourcePicker.refresh");
@@ -373,21 +372,8 @@ export function CaptureSourcePicker({
{!vis && <span>{t("host.sourcePicker.excludeAudio")}{excludeAudio ? ` · ${excludeAudio.title}` : ""}</span>}
<Glyph name="chevron" size={14} />
</summary>
- <div className="lr-capture-device">
- <select id={`${pickerId}-exclude-audio`} value={exclusionKey}
- aria-label={t("host.sourcePicker.excludeAudio")}
- aria-describedby={`${pickerId}-exclude-hint`} disabled={selectionDisabled}
- onChange={event => setExcludeAudio(audioApplications.find(target => `${target.pid}:${target.creationTime}` === event.target.value))}>
- <option value="">{t("host.sourcePicker.excludeNone")}</option>
- {missingExclusion && <option value={exclusionKey} disabled>{excludeAudio?.title} · {t("host.sourcePicker.excludeMissing")}</option>}
- {audioApplications.map(target => <option key={`${target.pid}:${target.creationTime}`} value={`${target.pid}:${target.creationTime}`}>
- {target.title}
- </option>)}
- </select>
- <small id={`${pickerId}-exclude-hint`} className={vis ? "visually-hidden" : undefined}>
- {t(excludeAudio ? "host.sourcePicker.excludeAudioHint" : "host.sourcePicker.excludeAudioChoose")}
- </small>
- </div>
+ <AudioExclusionSelect sources={applications} value={excludeAudio}
+ showLabel={false} disabled={selectionDisabled} onChange={setExcludeAudio} />
</details>
) : null}
</div>
diff --git a/src/client/components/living/Header.tsx b/src/client/components/living/Header.tsx
index 6af40ec2..288dadef 100644
--- a/src/client/components/living/Header.tsx
+++ b/src/client/components/living/Header.tsx
@@ -43,39 +43,17 @@ export function LedStrip({
);
}
-export function HeaderControls({ diagnosticControl }: { diagnosticControl?: React.ReactNode } = {}) {
+/** Shared explicit opt-in/export action; starting diagnostics reloads the page. */
+export function BrowserDiagnosticsButton() {
const { vis, t } = useCopy();
- const { theme, toggle } = useTheme();
const [debugExport, setDebugExport] = useState<"idle" | "busy" | "failed">("idle");
- const themeTitle = t(theme === "dark" ? "theme.light" : "theme.dark");
- const themeButton = (
- <button
- type="button"
- className="lr-btn"
- style={{ minWidth: 40, height: 40, borderRadius: 999 }}
- aria-label={themeTitle}
- onClick={(event) => {
- // Pointer activation must not pin the hint open; keyboard keeps focus.
- if (event.detail !== 0) event.currentTarget.blur();
- toggle();
- }}
- >
- <Glyph name={theme === "dark" ? "sun" : "moon"} size={16} draw="theme-toggle" />
- {vis ? null : (
- <span className="lr-cap">
- {t(theme === "dark" ? "theme.light.short" : "theme.dark.short")}
- </span>
- )}
- </button>
- );
const debugTitle = t(!browserDebugEnabled ? "debug.startHint" :
debugExport === "failed" ? "debug.exportFailed" : "debug.exportHint");
const debugButton = (
<button
type="button" className={`lr-btn${browserDebugEnabled ? " is-on" : ""}`} disabled={debugExport === "busy"}
aria-label={debugTitle} aria-busy={debugExport === "busy" || undefined}
- onClick={(event) => {
- if (event.detail !== 0) event.currentTarget.blur();
+ onClick={() => {
if (!browserDebugEnabled) {
// Start collection before connection owners attach their observers.
// Preserve the current route, access parameters and invitation fragment.
@@ -97,6 +75,36 @@ export function HeaderControls({ diagnosticControl }: { diagnosticControl?: Reac
debugExport === "failed" ? "common.retry" : "debug.export")}</span>}
</button>
);
+ return <Tooltip kind={!browserDebugEnabled ? "debug-start" : debugExport === "failed" ? "debug-export-failed" : "hint-debug-export"}
+ tone={debugExport === "failed" ? "bad" : debugExport === "busy" ? "busy" : "off"}
+ motion={debugExport === "failed" ? "still" : debugExport === "busy" ? "progress" : "demo"}
+ text={vis ? undefined : debugTitle} place="below" align="end">{debugButton}</Tooltip>;
+}
+
+export function HeaderControls({ diagnosticControl }: { diagnosticControl?: React.ReactNode } = {}) {
+ const { vis, t } = useCopy();
+ const { theme, toggle } = useTheme();
+ const themeTitle = t(theme === "dark" ? "theme.light" : "theme.dark");
+ const themeButton = (
+ <button
+ type="button"
+ className="lr-btn"
+ style={{ minWidth: 40, height: 40, borderRadius: 999 }}
+ aria-label={themeTitle}
+ onClick={(event) => {
+ // Pointer activation must not pin the hint open; keyboard keeps focus.
+ if (event.detail !== 0) event.currentTarget.blur();
+ toggle();
+ }}
+ >
+ <Glyph name={theme === "dark" ? "sun" : "moon"} size={16} draw="theme-toggle" />
+ {vis ? null : (
+ <span className="lr-cap">
+ {t(theme === "dark" ? "theme.light.short" : "theme.dark.short")}
+ </span>
+ )}
+ </button>
+ );
return (
<span className="lr-top-right lr-header-controls">
<LanguageControl />
@@ -104,12 +112,7 @@ export function HeaderControls({ diagnosticControl }: { diagnosticControl?: Reac
{themeButton}
</Tooltip>
{diagnosticControl !== null && <span className="lr-header-diagnostic">
- {diagnosticControl === undefined ? <Tooltip kind={!browserDebugEnabled ? "debug-start" : debugExport === "failed" ? "debug-export-failed" : "hint-debug-export"}
- tone={debugExport === "failed" ? "bad" : debugExport === "busy" ? "busy" : "off"}
- motion={debugExport === "failed" ? "still" : debugExport === "busy" ? "progress" : "demo"}
- text={vis ? undefined : debugTitle} place="below" align="end">
- {debugButton}
- </Tooltip> : diagnosticControl}
+ {diagnosticControl === undefined ? <BrowserDiagnosticsButton /> : diagnosticControl}
</span>}
</span>
);
diff --git a/src/client/components/living/ShareFailureHelp.tsx b/src/client/components/living/ShareFailureHelp.tsx
new file mode 100644
index 00000000..4c4a6575
--- /dev/null
+++ b/src/client/components/living/ShareFailureHelp.tsx
@@ -0,0 +1,59 @@
+import { useId, useRef, useState } from "react";
+import type { StatusDescriptor } from "../../ui/media-status";
+import { useCopy, type CopyKey } from "../../ui/copy";
+import { Glyph } from "../../ui/icons";
+import { Comic } from "./Comic";
+import { HintComic, isHintKind } from "./hints";
+import { BrowserDiagnosticsButton } from "./Header";
+import { StatusIndicator } from "./StatusIndicator";
+import "./share-failure-help.css";
+
+/** The current status owns this disclosure; closing/replacing it retains no error history. */
+export function ShareFailureHelp({ status, label, code, checks }: {
+ status: StatusDescriptor; label: string; code: string; checks: CopyKey[];
+}) {
+ const { lang, vis, t } = useCopy();
+ const dialog = useRef<HTMLDialogElement>(null);
+ const titleId = useId();
+ const [open, setOpen] = useState(false);
+ const [copied, setCopied] = useState<"idle" | "done" | "failed">("idle");
+ const hint = (status.tooltip ?? status.comic)!;
+ const guide = `https://piik.tv/docs/${lang === "zh" ? "zh/" : ""}troubleshooting.html`;
+ return <>
+ <StatusIndicator status={status} label={label} onActivate={() => {
+ setCopied("idle");
+ setOpen(true);
+ dialog.current?.showModal();
+ }} />
+ <dialog ref={dialog} className="lr-share-help" aria-labelledby={titleId} onClose={() => setOpen(false)}>
+ {open && <>
+ <header><h2 id={titleId}>{vis && <Glyph name="alert" size={20} />}<span className={vis ? "visually-hidden" : undefined}>{t("shareHelp.title")}</span></h2>
+ <button type="button" className="lr-btn" aria-label={t("common.close")} autoFocus onClick={() => dialog.current?.close()}>
+ <Glyph name="x" size={18} />
+ </button>
+ </header>
+ <div className="lr-share-help-scene" aria-hidden="true">
+ {isHintKind(hint) ? <HintComic kind={hint} tone={status.tone} /> : <Comic kind={hint} theme="paper" tone={status.tone} />}
+ </div>
+ <p className={vis ? "visually-hidden" : "lr-share-help-reason"}>{label}</p>
+ <code>{code}</code>
+ <ol className={vis ? "visually-hidden" : undefined}>
+ {checks.map(key => <li key={key}>{t(key)}</li>)}
+ <li>{t("shareHelp.report")}</li>
+ </ol>
+ {!vis && code.startsWith("app/") && <p className="lr-share-help-note">{t("shareHelp.appDebug")}</p>}
+ <nav aria-label={t("shareHelp.title")}>
+ <a className="lr-btn" href={guide} target="_blank" rel="noopener noreferrer" aria-label={t("shareHelp.guide")}>{!vis && t("shareHelp.guide")}<Glyph name="arrowRight" size={16} /></a>
+ <BrowserDiagnosticsButton />
+ <button type="button" className="lr-btn" aria-label={t(copied === "done" ? "shareHelp.copied" : "shareHelp.copy")} onClick={() => {
+ // Deliberately excludes URLs, invitation credentials and raw exceptions.
+ const version = import.meta.env.VITE_PIIK_VERSION ?? "development";
+ void Promise.resolve().then(() => navigator.clipboard.writeText(`Piik Web ${version}\n${label}\n${code}`)).then(
+ () => setCopied("done"), () => setCopied("failed"));
+ }}><Glyph name={copied === "done" ? "check" : "copy"} size={16} />{!vis && t(copied === "done" ? "shareHelp.copied" : "shareHelp.copy")}</button>
+ </nav>
+ <span role="status">{copied === "failed" ? t("shareHelp.copyFailed") : ""}</span>
+ </>}
+ </dialog>
+ </>;
+}
diff --git a/src/client/components/living/StatusIndicator.tsx b/src/client/components/living/StatusIndicator.tsx
index 643a8b70..e82dc252 100644
--- a/src/client/components/living/StatusIndicator.tsx
+++ b/src/client/components/living/StatusIndicator.tsx
@@ -5,24 +5,28 @@ import { Tooltip } from "./Tooltip";
import "./status-indicator.css";
/** One icon for one status; text and visual hints explain the same fact. */
-export function StatusIndicator({ status, label }: {
+export function StatusIndicator({ status, label, onActivate }: {
status: StatusDescriptor;
label?: string;
+ onActivate?: () => void;
}) {
const { vis, t } = useCopy();
const hint = (status.tooltip ?? status.comic)!;
const text = label ?? t(status.labelKey);
+ const description = onActivate ? `${text} · ${t("shareHelp.open")}` : text;
const indicator = (
<button
type="button"
className="lr-status-indicator"
data-tone={status.tone}
data-pulse={status.pulse || undefined}
- aria-label={text}
+ aria-label={description}
+ aria-haspopup={onActivate ? "dialog" : undefined}
+ onClick={onActivate}
>
<Glyph name={status.icon} size={17} />
</button>
);
- return <Tooltip toggleOnClick kind={hint} tone={status.tone} motion={status.pulse ? "progress" : "still"}
- text={vis ? undefined : text}>{indicator}</Tooltip>;
+ return <Tooltip toggleOnClick={!onActivate} kind={hint} tone={status.tone} motion={status.pulse ? "progress" : "still"}
+ text={vis ? undefined : description}>{indicator}</Tooltip>;
}
diff --git a/src/client/components/living/hints/index.tsx b/src/client/components/living/hints/index.tsx
index da275944..d080d3b4 100644
--- a/src/client/components/living/hints/index.tsx
+++ b/src/client/components/living/hints/index.tsx
@@ -51,6 +51,7 @@ export const HINT_KINDS: readonly HintKind[] = [
"hint-admission-invite",
"hint-quality",
"hint-audio-quality",
+ "hint-exclude-audio",
"hint-degrade-pref",
"hint-prefer-resolution",
"hint-prefer-framerate",
diff --git a/src/client/components/living/hints/set3.tsx b/src/client/components/living/hints/set3.tsx
index e080466c..3f06b238 100644
--- a/src/client/components/living/hints/set3.tsx
+++ b/src/client/components/living/hints/set3.tsx
@@ -54,6 +54,30 @@ ${rmBlock(["vls-audio-quality-wave"], [[".vls-audio-quality-wave", "stroke-dasho
<text x={240} y={88} fill="var(--ink)" fontSize={11} textAnchor="middle">kb/s</text>
</>;
+const hintExcludeAudio: HintScene = ({ theme }) => <>
+ <style>{`
+.vls-exclude-wave{stroke-dasharray:3 5;animation:vlsExcludeWave var(--comic-duration,3.2s) linear var(--comic-repeat,1) both}
+.vls-exclude-cut{animation:vlsExcludeCut var(--comic-duration,3.2s) ease-out var(--comic-repeat,1) both}
+@keyframes vlsExcludeWave{from{stroke-dashoffset:16}to{stroke-dashoffset:0}}
+@keyframes vlsExcludeCut{0%,8%{opacity:0;transform:translateY(-3px)}25%,100%{opacity:1;transform:none}}
+${rmBlock(["vls-exclude-wave"], [[".vls-exclude-wave", "stroke-dashoffset:0"]], false)}
+${rmBlock(["vls-exclude-cut"], [[".vls-exclude-cut", "opacity:1;transform:none"]], false)}
+`}</style>
+ <Frame x={4} w={152} theme={theme} /><Frame x={164} w={152} theme={theme} result />
+ {[0, 1].map(panel => <g key={panel} transform={`translate(${panel * 160} 0)`}>
+ <Pawn x={22} yb={81} s={7} eyes host />
+ {[25, 61].map((y, app) => <g key={y}>
+ <rect x={41} y={y - 9} width={27} height={23} rx={4} stroke="var(--ink)" strokeWidth={1.8} fill="var(--paper)" />
+ <path d={`M42 ${y - 2}h25`} stroke="var(--ink)" strokeWidth={1.5} />
+ <path d={`M48 ${y + 8}l5-5 7 5`} stroke={SKY} strokeWidth={2} fill="none" />
+ {panel && !app ? <path className="vls-exclude-cut" d="m77 20 10 10m-10 0 10-10" stroke="var(--ink)" strokeWidth={2.5} strokeLinecap="round" />
+ : <path className="vls-exclude-wave" d={`M74 ${y + 2}H91L101 46`} stroke="var(--ink)" strokeWidth={1.8} fill="none" />}
+ </g>)}
+ <MiniTv x={103} y={31} w={37} h={25} />
+ <path d="M147 37q5 6 0 12" stroke="var(--ink)" strokeWidth={1.5} fill="none" />
+ </g>)}
+</>;
+
function PreferenceHint({ theme, preference }: Parameters<HintScene>[0] & {
preference: "resolution" | "balanced" | "framerate";
}) {
@@ -286,6 +310,7 @@ ${rmBlock(["vls-export-report", "vls-export-arrow"], [[".vls-export-report,.vls-
export const SET3_SCENES: Record<Set3Kind, HintScene> = {
"hint-quality": hintQuality,
"hint-audio-quality": hintAudioQuality,
+ "hint-exclude-audio": hintExcludeAudio,
"hint-degrade-pref": hintDegradePref,
"hint-prefer-resolution": props => <PreferenceHint {...props} preference="resolution" />,
"hint-prefer-framerate": props => <PreferenceHint {...props} preference="framerate" />,
diff --git a/src/client/components/living/share-failure-help.css b/src/client/components/living/share-failure-help.css
new file mode 100644
index 00000000..088b0042
--- /dev/null
+++ b/src/client/components/living/share-failure-help.css
@@ -0,0 +1,30 @@
+.lr-share-help {
+ width: min(520px, calc(100vw - 24px));
+ max-height: calc(100dvh - 24px);
+ box-sizing: border-box;
+ padding: 20px;
+ color: var(--ink);
+ background: var(--paper);
+ border: 1px solid var(--control-edge);
+ border-radius: 24px;
+ box-shadow: var(--control-shadow), 0 12px 36px #101a2c33;
+ text-align: left;
+ overflow-wrap: anywhere;
+ overscroll-behavior: contain;
+}
+.lr-share-help::backdrop { background: #101a2c66; }
+.lr-share-help[open] { animation: lr-share-help-enter 180ms var(--spring); }
+.lr-share-help header { display: flex; gap: 16px; align-items: center; justify-content: space-between; }
+.lr-share-help h2 { margin: 0; font-size: 18px; }
+.lr-share-help header button { min-width: 40px; min-height: 40px; padding: 8px; }
+.lr-share-help-scene { width: min(260px, 100%); margin: 16px auto; }
+.lr-share-help-reason { font-weight: 700; line-height: 1.6; margin: 12px 0 6px; }
+.lr-share-help code { color: var(--muted); font-size: 12px; }
+.lr-share-help ol { padding-inline-start: 22px; line-height: 1.65; font-size: 14px; }
+.lr-share-help li + li { margin-top: 10px; }
+.lr-share-help-note { color: var(--muted); line-height: 1.6; font-size: 12px; }
+.lr-share-help nav { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 18px; }
+.lr-share-help nav .lr-btn { white-space: normal; }
+.lr-share-help [role="status"] { font-size: 12px; color: var(--danger); }
+@keyframes lr-share-help-enter { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: none; } }
+@media (prefers-reduced-motion: reduce) { .lr-share-help[open] { animation: none; } }
diff --git a/src/client/locales/en.ts b/src/client/locales/en.ts
index 10db1465..762cac69 100644
--- a/src/client/locales/en.ts
+++ b/src/client/locales/en.ts
@@ -74,10 +74,10 @@ export const en: Record<CopyKey, string> = {
"client.launch.go": "Open Piik",
"client.launch.starting": "Preparing Piik",
"client.launch.error": "Piik could not start",
- "client.launch.reopen": "Check the reason above and the terminal for details, then close and reopen Piik to try again. Enable Debug launch first if you need to record logs.",
+ "client.launch.reopen": "Check the error above and the terminal, then reopen Piik. Use Debug launch to record logs.",
"client.launch.debug": "Debug launch",
"client.launch.debugHint": "Record App and browser diagnostics for this launch. Press D in the terminal to export App logs.",
- "client.launch.loadFailed": "Could not read the launcher settings; retry",
+ "client.launch.loadFailed": "Could not read launcher settings; reload to retry",
"client.update.available": "A newer Piik release is available",
"client.update.differentBuild": "This build differs from the official release",
"client.update.official": "An official Piik release is available",
@@ -118,7 +118,7 @@ export const en: Record<CopyKey, string> = {
"host.device.microphone": "Microphone",
"host.device.camera": "Camera",
"host.device.default": "Default device",
- "host.device.missing": "Selected device unavailable",
+ "host.device.missing": "Device unavailable; choose another",
"host.device.refresh": "Refresh devices",
"host.device.listFailed": "Could not load devices. Try refreshing.",
"host.device.permission.microphone": "Turn on the microphone and allow access to see the available devices here.",
@@ -204,21 +204,45 @@ export const en: Record<CopyKey, string> = {
"host.sourcePicker.windowAudio": "Application sound",
"host.sourcePicker.systemAudio": "System sound",
"host.sourcePicker.excludeAudio": "Exclude application audio",
+ "host.sourcePicker.refreshApplications": "Refresh application list",
+ "host.sourcePicker.excludeListFailed": "Could not load applications. Refresh to try again.",
+ "host.fail.sourceAudio": "Could not update source audio. Please try again.",
"host.sourcePicker.excludeNone": "None",
"host.sourcePicker.excludeMissing": "Not listed; select again",
"host.sourcePicker.excludeAudioChoose": "Choose an application window to exclude. If it is missing, open its window and refresh.",
+ "host.sourcePicker.excludeAudioLifetime": "If the app exits, source audio stops. Refresh and select it again.",
"host.sourcePicker.excludeAudioHint": "Share audio from all output devices except the selected process and its children. If it exits, source audio stops until you select again.",
"host.sourcePicker.showCaptureBorder": "Show capture border",
"host.sourcePicker.showCaptureBorderHint": "Turn off to hide the border when Windows allows it. Other captures may keep it visible.",
- "host.sourcePicker.empty": "No sources available",
- "host.sourcePicker.unavailable": "Cannot connect to Piik App. Keep the App running, open this site from the App, then refresh the list. Allow local-network access if asked.",
- "host.sourcePicker.unsupported": "Piik App capture is currently unavailable. Check the encoding setting or the App diagnostics.",
- "host.sourcePicker.failed": "Could not read the App's screen and window list. Refresh to try again; if it keeps failing, collect a Debug report.",
- "native.incompatible": "Piik App and this page are incompatible. Update Piik App and reload this page, or use Browser.",
+ "host.sourcePicker.empty": "No sources available; refresh the list",
+ "host.sourcePicker.unavailable": "Cannot connect to Piik App. Open this site from the App, refresh the list, and allow local-network access if asked.",
+ "host.sourcePicker.unsupported": "App capture is unavailable; check the App diagnostics.",
+ "host.sourcePicker.failed": "Could not load sources; refresh to retry.",
+ "native.incompatible": "App and page versions are incompatible; update the App and reload.",
"native.fail.edge": "Piik App media connection failed",
- "native.fail.browserMedia": "The browser could not create a media connection. Refresh the page or try another browser.",
+ "native.fail.browserMedia": "The browser could not create a media connection; reload to retry.",
"native.fail.signaling": "Piik App signaling failed",
"native.fail.receiver": "Piik App media receive failed",
+ "native.fail.controlDisconnected": "Disconnected from Piik App; check that the App is running, then reload.",
+ "native.fail.requestTimeout": "Piik App timed out; try again in a moment.",
+ "native.fail.invalidResponse": "The page could not read Piik App's response. Update the App and refresh the page.",
+ "native.fail.captureStart": "App capture failed; try another source.",
+ "native.fail.edgePrepare": "Piik App could not prepare the media connection. Enable diagnostics and try again.",
+ "shareHelp.title": "Sharing troubleshooting",
+ "shareHelp.open": "Select for troubleshooting",
+ "shareHelp.source": "Try another ordinary window or screen. Keep the source open and allow screen recording when your system asks.",
+ "shareHelp.compare": "Compare with the Browser source picker. On Windows, also try Auto or VP8 with the same source.",
+ "shareHelp.report": "If it still fails, enable diagnostics, try again and save reports from that attempt. Include the failure message, Piik version and what you were doing.",
+ "shareHelp.appDebug": "For App logs, enable Debug launch on the mode selection page, reproduce the problem, then press D in the terminal to export. The button below records browser diagnostics only.",
+ "shareHelp.site": "Check the site address and your access. For a self-hosted site, check PUBLIC_BASE_URL, ALLOWED_ORIGINS and the reverse proxy configuration; see the guide for steps.",
+ "shareHelp.appConnection": "Check that the App is running and responding. Open this site from the App, refresh the page and allow local network access if your browser asks.",
+ "shareHelp.mediaConnection": "Check that the browser permits WebRTC and local network access, then refresh and try again. You can also compare with another browser.",
+ "shareHelp.permission": "Return to this page, click Share and select a source again. Allow screen recording when your system or browser asks.",
+ "shareHelp.camera": "Check camera permission and the device connection. Close applications using the camera exclusively, then select it again.",
+ "shareHelp.guide": "Open troubleshooting guide",
+ "shareHelp.copy": "Copy failure details",
+ "shareHelp.copied": "Copied",
+ "shareHelp.copyFailed": "Could not copy. Select the error code manually.",
"host.sourcePicker.window": "Share window: {title}",
"host.sourcePicker.display": "Share screen: {title}",
"host.sourcePicker.system": "System screen or window picker",
@@ -247,7 +271,7 @@ export const en: Record<CopyKey, string> = {
"host.roomReplace": "Replace room code",
"host.roomReplaceConfirm": "Replace the room code: this ends the current share and disconnects viewers",
"host.terminated.stale": "Page updated; refresh to continue",
- "host.terminated.session": "This page's session was taken over by another tab",
+ "host.terminated.session": "Another page took over this session; continue there",
"host.terminated.signal": "Server connection terminated; refresh to continue",
"host.notice.qualityApplied": "Share settings applied",
"host.notice.qualitySet": "Quality switched to {label}",
@@ -431,8 +455,8 @@ export const en: Record<CopyKey, string> = {
"viewer.msg.needsPlay": "Tap to play",
"viewer.msg.hostPaused": "Host paused",
"viewer.msg.recovering": "Recovering connection",
- "viewer.msg.routeFailed": "No media route available",
- "viewer.msg.playbackFailed": "The browser cannot play this stream",
+ "viewer.msg.routeFailed": "No media route available; reload to retry",
+ "viewer.msg.playbackFailed": "Cannot play this stream; reload to retry",
"viewer.msg.hostOffline": "Host connection lost",
"viewer.msg.serverError": "Connection service unavailable",
"viewer.msg.notFound": "Room not found",
@@ -444,14 +468,16 @@ export const en: Record<CopyKey, string> = {
"viewer.hint.accessFailed": "Reload this page to try again, or use an invite link from the host.",
"viewer.hint.full": "Try again when a seat opens up.",
"viewer.msg.stale": "Page updated; refresh to continue",
- "viewer.msg.sessionReplaced": "This page's session was taken over by another tab",
+ "viewer.msg.sessionReplaced": "Another page took over this session",
"viewer.msg.signalTerminated": "Connection terminated; refresh to continue",
"viewer.notice.signalRecovering": "Server reconnecting",
"viewer.notice.hostOffline": "Host connection lost; picture may freeze",
"viewer.hint.denied": "Use the host's invite link, or try the room password.",
"viewer.hint.notFound": "Check that the room code belongs to {site}, or open the host’s invite link.",
+ "viewer.hint.closed": "Ask the host to create a new room and send an invite.",
+ "viewer.hint.sessionReplaced": "Continue on the other page, or reload here to reconnect.",
"viewer.hint.invite": "Ask the host for a new invite link.",
- "viewer.hint.generic": "Check your entry point and try again.",
+ "viewer.hint.generic": "Reload this page to try again in a moment.",
"mode.language": "Interface language",
"mode.more": "More languages",
@@ -461,10 +487,10 @@ export const en: Record<CopyKey, string> = {
"theme.dark.short": "Dark",
"theme.light.short": "Light",
- "gate.connectFailed": "Cannot reach the site access service; try again",
+ "gate.connectFailed": "Cannot reach the site; check your connection and retry",
"gate.expired": "Site access expired; verify again",
- "gate.serviceUnavailable": "Site access service unavailable ({status})",
- "api.originNotAllowed": "This address is not allowed by the server (403). Ask the site administrator to check PUBLIC_BASE_URL and ALLOWED_ORIGINS.",
+ "gate.serviceUnavailable": "Site service unavailable ({status}); try again later",
+ "api.originNotAllowed": "The server does not allow this address (403); contact the site administrator.",
"host.notStarted": "Not started",
"host.startCancelled": "Start cancelled",
@@ -478,14 +504,14 @@ export const en: Record<CopyKey, string> = {
"host.quality.title": "{label} · {mbps} Mbps",
"host.audio.title": "{label} · {kbps} kbps ceiling",
"host.roomClosed": "Room closed",
- "host.pause.noTracksResume": "No resumable media tracks in the current share",
+ "host.pause.noTracksResume": "Cannot resume sharing; choose the source again",
"host.pause.signalRecovering": "Server reconnecting; sharing stays paused",
- "host.pause.noTracksPause": "No pausable media tracks in the current share",
+ "host.pause.noTracksPause": "Cannot pause sharing; choose the source again",
"host.pause.stillPaused": "Sharing stays paused",
"host.shareEnded": "The current share has ended",
"host.fail.start": "Failed to start sharing",
"host.err.createConnection": "Failed to create the connection",
- "host.err.codecUnsupported": "This browser cannot use a supported video codec",
+ "host.err.codecUnsupported": "Video codec unsupported; update or try another browser",
"host.fail.source": "Failed to switch share source",
"host.fail.quality": "Failed to apply quality settings",
"host.fail.connection": "Viewer connection handling failed",
@@ -501,8 +527,10 @@ export const en: Record<CopyKey, string> = {
"host.err.updateRoomStatus": "Cannot update room settings right now ({status})",
"host.capture.cancelled": "Screen selection cancelled or not permitted",
"host.capture.noSource": "No shareable screen source available",
- "host.capture.readFailed": "The browser cannot read the selected source right now",
+ "host.capture.readFailed": "Cannot read the selected source; choose it again",
"host.capture.unavailable": "This page cannot start screen sharing",
+ "host.capture.inactive": "Return to this page, then click Share and select a source again.",
+ "host.capture.constraints": "The selected source cannot meet the current picture settings. Lower the settings or choose another source.",
"host.notice.reconnecting": "some viewers are reconnecting",
"host.notice.sfuRecovering": "Server forwarding source switch failed; restoring viewer connections",
"host.password.inputPlaceholder": "Enter password",
diff --git a/src/client/locales/zh.ts b/src/client/locales/zh.ts
index 8a08c6f0..2cff9a46 100644
--- a/src/client/locales/zh.ts
+++ b/src/client/locales/zh.ts
@@ -74,10 +74,10 @@ export const zh = {
"client.launch.go": "进入 Piik",
"client.launch.starting": "正在准备 Piik",
"client.launch.error": "Piik 启动失败",
- "client.launch.reopen": "请查看上方原因和 Piik 终端中的详细信息,关闭并重新打开 Piik 后重试。需要记录日志时,可先开启「诊断启动」。",
+ "client.launch.reopen": "查看上方原因和终端详情,重新打开 Piik 后重试。可开启「诊断启动」记录日志。",
"client.launch.debug": "诊断启动",
"client.launch.debugHint": "本次启动记录 App 和网页诊断。App 日志可在终端按 D 导出。",
- "client.launch.loadFailed": "无法读取启动设置,请重试",
+ "client.launch.loadFailed": "无法读取启动设置,请刷新页面重试",
"client.update.available": "发现新的 Piik 版本",
"client.update.differentBuild": "当前构建与官方发行版不同",
"client.update.official": "可获取 Piik 正式发行版",
@@ -118,7 +118,7 @@ export const zh = {
"host.device.microphone": "麦克风",
"host.device.camera": "摄像头",
"host.device.default": "默认设备",
- "host.device.missing": "所选设备暂不可用",
+ "host.device.missing": "设备不可用,请重新选择",
"host.device.refresh": "刷新设备",
"host.device.listFailed": "暂时无法获取设备,请刷新重试。",
"host.device.permission.microphone": "开启麦克风并允许访问后,可以在这里选择设备。",
@@ -204,21 +204,45 @@ export const zh = {
"host.sourcePicker.windowAudio": "应用声音",
"host.sourcePicker.systemAudio": "系统声音",
"host.sourcePicker.excludeAudio": "排除应用声音",
+ "host.sourcePicker.refreshApplications": "刷新应用列表",
+ "host.sourcePicker.excludeListFailed": "无法获取应用列表,请刷新重试。",
+ "host.fail.sourceAudio": "未能更新来源声音,请重试",
"host.sourcePicker.excludeNone": "不排除",
"host.sourcePicker.excludeMissing": "不在列表中,请重新选择",
"host.sourcePicker.excludeAudioChoose": "选择要排除的应用窗口;未列出的应用请先打开窗口,再刷新。",
+ "host.sourcePicker.excludeAudioLifetime": "应用退出后来源声音会停止,请刷新并重新选择。",
"host.sourcePicker.excludeAudioHint": "分享所有输出设备的声音,但不包含所选进程及其子进程。应用退出后来源声音会停止,需重新选择。",
"host.sourcePicker.showCaptureBorder": "显示采集边框",
"host.sourcePicker.showCaptureBorderHint": "关闭后尝试隐藏黄框;Windows 或其他采集程序可能仍要求显示。",
- "host.sourcePicker.empty": "暂无可用来源",
- "host.sourcePicker.unavailable": "未能连接 Piik App。请保持 App 运行,从 App 打开当前站点后刷新列表;浏览器询问本地网络权限时,请允许访问。",
- "host.sourcePicker.unsupported": "Piik App 采集功能当前不可用。请检查编码设置,或查看 App 诊断信息。",
- "host.sourcePicker.failed": "未能读取 App 的窗口和屏幕列表。请刷新重试;若持续失败,请导出诊断报告。",
- "native.incompatible": "Piik App 与当前页面不兼容。请更新 Piik App 并刷新页面,或使用浏览器。",
+ "host.sourcePicker.empty": "暂无可用来源,请刷新列表",
+ "host.sourcePicker.unavailable": "未连接 Piik App。请从 App 打开本站后刷新列表,并允许浏览器的本地网络访问。",
+ "host.sourcePicker.unsupported": "App 采集暂不可用,请查看 App 诊断信息。",
+ "host.sourcePicker.failed": "无法读取来源列表,请刷新重试。",
+ "native.incompatible": "App 与页面不兼容,请更新 App 并刷新页面。",
"native.fail.edge": "Piik App 媒体连接失败",
- "native.fail.browserMedia": "浏览器无法建立媒体连接。请刷新页面,或换一个浏览器重试。",
+ "native.fail.browserMedia": "浏览器无法建立媒体连接,请刷新页面重试。",
"native.fail.signaling": "Piik App 信令失败",
"native.fail.receiver": "Piik App 媒体接收失败",
+ "native.fail.controlDisconnected": "与 Piik App 的连接已断开,请确认 App 运行后刷新页面。",
+ "native.fail.requestTimeout": "Piik App 响应超时,请稍后重试。",
+ "native.fail.invalidResponse": "Piik App 返回的数据无法识别。请更新 App 并刷新页面。",
+ "native.fail.captureStart": "App 未能采集所选来源,请换一个来源重试。",
+ "native.fail.edgePrepare": "Piik App 未能准备媒体连接。请开启诊断后重试。",
+ "shareHelp.title": "分享排查",
+ "shareHelp.open": "点按查看排查方法",
+ "shareHelp.source": "先换一个普通窗口或屏幕重试,确认来源仍然打开,并允许系统请求的录屏权限。",
+ "shareHelp.compare": "对照试一次「浏览器」选源。Windows 上也可将编码器改为「自动」或 VP8,再试同一来源。",
+ "shareHelp.report": "仍然失败时,开启诊断后再试一次,并保存同一次尝试的报告。请附上失败提示、Piik 版本和当时的操作。",
+ "shareHelp.appDebug": "App 日志需从模式选择页开启「诊断启动」,重现后在终端按 D 导出。下方按钮只记录网页诊断。",
+ "shareHelp.site": "确认当前站点地址和访问权限。自部署站点请核对 PUBLIC_BASE_URL、ALLOWED_ORIGINS 与反向代理配置,具体步骤见排查文档。",
+ "shareHelp.appConnection": "确认 App 仍在运行且没有卡住,从 App 打开当前站点后刷新页面;浏览器询问本地网络权限时,请允许访问。",
+ "shareHelp.mediaConnection": "检查浏览器是否允许 WebRTC 和本地网络访问,再刷新页面重试;也可换一个浏览器对照。",
+ "shareHelp.permission": "回到当前页面,重新点击分享并选择来源;若系统或浏览器询问录屏权限,请允许访问。",
+ "shareHelp.camera": "检查摄像头权限,确认设备已连接且未被其他程序独占,再重新选择摄像头。",
+ "shareHelp.guide": "打开问题排查文档",
+ "shareHelp.copy": "复制失败信息",
+ "shareHelp.copied": "已复制",
+ "shareHelp.copyFailed": "未能复制,请手动选择错误编号",
"host.sourcePicker.window": "分享窗口:{title}",
"host.sourcePicker.display": "分享屏幕:{title}",
"host.sourcePicker.system": "系统屏幕与窗口选择器",
@@ -247,7 +271,7 @@ export const zh = {
"host.roomReplace": "更换房间号",
"host.roomReplaceConfirm": "确认更换房间号:当前分享会结束,观众需要重新加入",
"host.terminated.stale": "页面版本已更新,请刷新后重试",
- "host.terminated.session": "此页面的会话已被另一个标签页接管",
+ "host.terminated.session": "会话已由另一页面接管,请前往该页继续",
"host.terminated.signal": "服务器连接已终止,请刷新后重试",
"host.notice.qualityApplied": "分享设置已应用",
"host.notice.qualitySet": "画质已切换为 {label}",
@@ -431,8 +455,8 @@ export const zh = {
"viewer.msg.needsPlay": "点击播放",
"viewer.msg.hostPaused": "房主已暂停分享",
"viewer.msg.recovering": "正在恢复连接",
- "viewer.msg.routeFailed": "没有可用的媒体线路",
- "viewer.msg.playbackFailed": "浏览器无法播放当前画面",
+ "viewer.msg.routeFailed": "没有可用的媒体线路,可刷新重试",
+ "viewer.msg.playbackFailed": "无法播放当前画面,请刷新重试",
"viewer.msg.hostOffline": "房主连接已中断",
"viewer.msg.serverError": "连接服务暂时不可用",
"viewer.msg.notFound": "房间不存在",
@@ -444,14 +468,16 @@ export const zh = {
"viewer.hint.accessFailed": "刷新页面后重试,或使用房主发来的邀请链接。",
"viewer.hint.full": "等有空位后再试。",
"viewer.msg.stale": "页面版本已更新,请刷新后重试",
- "viewer.msg.sessionReplaced": "此页面的会话已被另一个标签页接管",
+ "viewer.msg.sessionReplaced": "会话已由另一页面接管",
"viewer.msg.signalTerminated": "连接已终止,请刷新后重试",
"viewer.notice.signalRecovering": "服务器连接正在恢复",
"viewer.notice.hostOffline": "房主连接已中断,画面可能停住",
"viewer.hint.denied": "请使用房主发来的邀请链接,或输入房间密码。",
"viewer.hint.notFound": "请确认这是 {site} 的房间号,或打开房主的邀请链接。",
+ "viewer.hint.closed": "请让房主重新创建房间并发送邀请。",
+ "viewer.hint.sessionReplaced": "请前往另一页面继续,或刷新本页重新连接。",
"viewer.hint.invite": "请让房主重新发送邀请链接。",
- "viewer.hint.generic": "请检查入口后重试。",
+ "viewer.hint.generic": "请稍后刷新页面重试。",
"mode.language": "界面语言",
"mode.more": "更多语言",
@@ -461,10 +487,10 @@ export const zh = {
"theme.dark.short": "暗色",
"theme.light.short": "浅色",
- "gate.connectFailed": "无法连接站点访问服务,请重试",
+ "gate.connectFailed": "无法连接站点,请检查网络后重试",
"gate.expired": "站点访问已失效,请重新验证",
- "gate.serviceUnavailable": "站点验证服务暂时不可用 ({status})",
- "api.originNotAllowed": "服务器未允许当前网址 (403)。请联系站点管理员检查 PUBLIC_BASE_URL 和 ALLOWED_ORIGINS。",
+ "gate.serviceUnavailable": "站点服务暂不可用 ({status}),请稍后重试",
+ "api.originNotAllowed": "当前网址不在服务器允许的范围内 (403),请联系管理员。",
"host.notStarted": "尚未开始",
"host.startCancelled": "启动已取消",
@@ -478,14 +504,14 @@ export const zh = {
"host.quality.title": "{label} · {mbps} Mbps",
"host.audio.title": "{label} · {kbps} kbps 上限",
"host.roomClosed": "房间已关闭",
- "host.pause.noTracksResume": "当前分享没有可恢复的媒体轨道",
+ "host.pause.noTracksResume": "无法恢复分享,请重新选择来源",
"host.pause.signalRecovering": "服务器连接正在恢复,分享仍保持暂停",
- "host.pause.noTracksPause": "当前分享没有可暂停的媒体轨道",
+ "host.pause.noTracksPause": "无法暂停分享,请重新选择来源",
"host.pause.stillPaused": "分享仍保持暂停",
"host.shareEnded": "当前分享已经结束",
"host.fail.start": "启动分享失败",
"host.err.createConnection": "创建连接失败",
- "host.err.codecUnsupported": "当前浏览器无法使用支持的视频编码",
+ "host.err.codecUnsupported": "浏览器不支持所需的视频编码,请更新或更换浏览器",
"host.fail.source": "切换分享来源失败",
"host.fail.quality": "应用画质设置失败",
"host.fail.connection": "观看连接处理失败",
@@ -501,8 +527,10 @@ export const zh = {
"host.err.updateRoomStatus": "当前无法更新房间设置 ({status})",
"host.capture.cancelled": "屏幕选择已取消或没有共享权限",
"host.capture.noSource": "没有可用的屏幕分享来源",
- "host.capture.readFailed": "浏览器暂时无法读取所选分享来源",
+ "host.capture.readFailed": "无法读取所选分享来源,请重新选源",
"host.capture.unavailable": "当前页面无法启动屏幕分享",
+ "host.capture.inactive": "请回到当前页面,再点击分享并选择来源。",
+ "host.capture.constraints": "所选来源无法满足当前画面设置。请降低设置或换一个来源。",
"host.notice.reconnecting": "部分观众正在重新连接",
"host.notice.sfuRecovering": "服务器中转的画面来源未切换成功,正在恢复观看连接",
"host.password.inputPlaceholder": "输入密码",
diff --git a/src/client/media/browser-encoding-producer.ts b/src/client/media/browser-encoding-producer.ts
index 799bc7af..4f034315 100644
--- a/src/client/media/browser-encoding-producer.ts
+++ b/src/client/media/browser-encoding-producer.ts
@@ -3,6 +3,7 @@ import { createOpaqueId } from "../lib/opaque-id";
import { debugError, debugEvent } from "../lib/debug";
import { debugRtcFailure, debugRtcStats, debugTrack, observeDebugConnection } from "../lib/debug-webrtc";
import { addRemoteIceCandidate } from "../webrtc/nat-prediction";
+import { normalizeVideoOfferSdp } from "../webrtc/video-codec";
import { encodedStreams } from "./browser-encoding-output";
import {
applyVideoCaptureProfile, configureVideoSender,
@@ -117,7 +118,7 @@ export class BrowserEncodingProducer {
await this.serialize(() => this.applyCurrent());
await send.setLocalDescription(await send.createOffer());
this.checkAlive();
- await receive.setRemoteDescription(send.localDescription!);
+ await receive.setRemoteDescription({ type: "offer", sdp: normalizeVideoOfferSdp(send.localDescription!.sdp) });
await flushReceive();
this.checkAlive();
await receive.setLocalDescription(this.seedLocalAnswer(await receive.createAnswer()));
diff --git a/src/client/native/capture-selection.ts b/src/client/native/capture-selection.ts
index c74c972e..85066d51 100644
--- a/src/client/native/capture-selection.ts
+++ b/src/client/native/capture-selection.ts
@@ -29,3 +29,12 @@ export function nativeCaptureTargetKey(target: NativeCaptureTarget): string {
? `window:${target.sourceId}:${target.pid}:${target.creationTime}`
: `${target.kind}:${target.sourceId}`;
}
+
+export function audioApplicationKey(target: NativeCaptureTarget): string {
+ return target.kind === "window" ? `${target.pid}:${target.creationTime}` : "";
+}
+
+export function audioApplications(sources: NativeCaptureTarget[]): NativeCaptureTarget[] {
+ return [...new Map(sources.filter(target => target.kind === "window")
+ .map(target => [audioApplicationKey(target), target])).values()];
+}
diff --git a/src/client/native/client.ts b/src/client/native/client.ts
index 4a129861..84ae94de 100644
--- a/src/client/native/client.ts
+++ b/src/client/native/client.ts
@@ -64,6 +64,7 @@ async function ungrantedLocalPermission(): Promise<PermissionState | null> {
}
interface PendingRequest<T = unknown> {
+ operation: string;
schema: z.ZodType<T>;
resolve: (value: T) => void;
reject: (error: Error) => void;
@@ -90,6 +91,25 @@ export class NativeCompatibilityError extends Error {
}
}
+/** The control boundary knows the failed operation, not the driver's cause. */
+export class NativeRequestError extends Error {
+ constructor(
+ readonly reason: "unavailable" | "timeout" | "send-failed" | "rejected" | "invalid-response" | "disconnected",
+ readonly operation: string,
+ options?: ErrorOptions,
+ ) {
+ super({
+ unavailable: "Piik App is unavailable",
+ timeout: "Piik App request timed out",
+ "send-failed": "Piik App request failed",
+ rejected: "Piik App request failed",
+ "invalid-response": "Piik App response is invalid",
+ disconnected: "Piik App disconnected",
+ }[reason], options);
+ this.name = "NativeRequestError";
+ }
+}
+
export async function discoverNativeHealth(
{ waitForPermission = true }: NativeDiscoveryOptions = {},
): Promise<NativeHealth | null> {
@@ -657,7 +677,7 @@ export class NativeClient {
timeoutMs: number | null = REQUEST_TIMEOUT_MS,
): Promise<T> {
if (this.closed || this.socket.readyState !== WebSocket.OPEN) {
- return Promise.reject(new Error("Piik App is unavailable"));
+ return Promise.reject(new NativeRequestError("unavailable", type));
}
const id = createOpaqueId();
const began = performance.now();
@@ -669,9 +689,10 @@ export class NativeClient {
: window.setTimeout(() => {
this.pending.delete(id);
debugEvent("native", "request-timeout", { ...details, durationMs: performance.now() - began });
- rejectRequest(new Error("Piik App request timed out"));
+ rejectRequest(new NativeRequestError("timeout", type));
}, timeoutMs);
this.pending.set(id, {
+ operation: type,
schema,
resolve: (value) => {
debugEvent("native", "response", { ...details, durationMs: performance.now() - began, applied: value });
@@ -697,7 +718,7 @@ export class NativeClient {
if (timer !== null) window.clearTimeout(timer);
this.pending.delete(id);
debugError("native", "request-failed", error, { ...details, durationMs: performance.now() - began });
- rejectRequest(new Error("Piik App request failed"));
+ rejectRequest(new NativeRequestError("send-failed", type, { cause: error }));
}
});
}
@@ -719,14 +740,14 @@ export class NativeClient {
if (pending.timer !== null) window.clearTimeout(pending.timer);
const failure = requestFailedResponseSchema.safeParse(value);
if (failure.success) {
- pending.reject(new Error("Piik App request failed", { cause: { code: failure.data.code } }));
+ pending.reject(new NativeRequestError("rejected", pending.operation, { cause: { code: failure.data.code } }));
return;
}
const parsed = pending.schema.safeParse(value);
if (parsed.success) {
pending.resolve(parsed.data);
} else {
- pending.reject(new Error("Piik App response is invalid", { cause: parsed.error }));
+ pending.reject(new NativeRequestError("invalid-response", pending.operation, { cause: parsed.error }));
}
return;
}
@@ -763,7 +784,7 @@ export class NativeClient {
private rejectPending(): void {
for (const request of this.pending.values()) {
if (request.timer !== null) window.clearTimeout(request.timer);
- request.reject(new Error("Piik App disconnected"));
+ request.reject(new NativeRequestError("disconnected", request.operation));
}
this.pending.clear();
}
diff --git a/src/client/native/native-viewer-peer.ts b/src/client/native/native-viewer-peer.ts
index fff61be0..5233373e 100644
--- a/src/client/native/native-viewer-peer.ts
+++ b/src/client/native/native-viewer-peer.ts
@@ -787,15 +787,40 @@ export function offerHasNativeVideoCodec(sdp: string): boolean {
const session = parse(sdp);
const video = session.media.filter((media) => {
const direction = media.direction ?? session.direction ?? "sendrecv";
- return media.type === "video" && media.port > 0 &&
+ const bundled = media.bundleOnly && (session.groups ?? []).some(group =>
+ group.type === "BUNDLE" && String(group.mids).split(" ").includes(String(media.mid)));
+ return media.type === "video" && (media.port > 0 || bundled) &&
(direction === "sendonly" || direction === "sendrecv");
});
if (video.length !== 1) return false;
const media = video[0]!;
const payloads = new Set(parsePayloads(media.payloads ?? ""));
- return media.rtp.some((codec) => payloads.has(codec.payload) &&
- codec.rate === 90_000 && /^(h264|vp8)$/i.test(codec.codec));
+ return media.rtp.some((codec) => {
+ if (!payloads.has(codec.payload) || codec.rate !== 90_000) return false;
+ if (codec.codec.toLowerCase() === "vp8") return true;
+ if (codec.codec.toLowerCase() !== "h264") return false;
+ return nativeH264Format(media.fmtp?.find(fmtp => fmtp.payload === codec.payload)?.config ?? "");
+ });
} catch {
return false;
}
}
+
+function nativeH264Format(fmtp: string): boolean {
+ // Preflight the same encoded-forwarding subset as mediaedge.forwardableH264;
+ // a MIME-only match must not turn unsupported media into an App failure.
+ const parameters = new Map(fmtp.split(";").map(part => {
+ const [key, value] = part.split(/=(.*)/, 2);
+ return [key?.trim().toLowerCase(), value?.trim().toLowerCase()] as const;
+ }));
+ const profile = parameters.get("profile-level-id") ?? "";
+ if (parameters.get("packetization-mode") !== "1" || !/^[0-9a-f]{6}$/.test(profile)) return false;
+ const idc = parseInt(profile.slice(0, 2), 16);
+ const constraints = parseInt(profile.slice(2, 4), 16);
+ const level = parseInt(profile.slice(4), 16);
+ // RFC 6184 Table 5: equivalent Constrained Baseline coding-tool subsets.
+ return ((idc === 0x42 && (constraints & 0x4f) === 0x40) ||
+ (idc === 0x4d && (constraints & 0x8f) === 0x80) ||
+ (idc === 0x58 && (constraints & 0xcf) === 0xc0)) &&
+ [10, 11, 12, 13, 20, 21, 22, 30, 31, 32, 40, 41, 42, 50, 51].includes(level);
+}
diff --git a/src/client/pages/ControlsPreview.tsx b/src/client/pages/ControlsPreview.tsx
index 80826754..8ca03b7e 100644
--- a/src/client/pages/ControlsPreview.tsx
+++ b/src/client/pages/ControlsPreview.tsx
@@ -5,6 +5,8 @@ import { CaptureSourcePicker, type NativeSourceList } from "../components/living
import { LedStrip } from "../components/living/Header";
import { StageTv } from "../components/living/Stage";
import { HostMicrophone, HostMicrophoneSettings } from "../components/living/HostMicrophone";
+import { LiveAudioExclusion } from "../components/living/AudioExclusionSelect";
+import type { NativeCaptureTarget } from "../native/wire";
import { RoomInteractions } from "../components/living/RoomInteractions";
import { RoomChatOverlay, RoomChatToggle } from "../components/living/RoomChatOverlay";
import { RoomInteractionSession } from "../lib/room-interactions";
@@ -41,12 +43,14 @@ const previewCameras: typeof loadCameraPreviews = async (_signal, publish) => pu
{ id: "usb", label: "USB Camera", preview: `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180"><rect width="320" height="180" fill="#e2c5a8"/><path d="M0 25h320M0 157h320" stroke="#cda987" stroke-width="2"/><rect x="53" y="27" width="163" height="124" rx="5" fill="#fffaf0" transform="rotate(-8 135 89)"/><path d="m97 112 30-35 23 25 18-12 18 19" fill="none" stroke="#689b8a" stroke-width="5" stroke-linejoin="round"/><circle cx="166" cy="57" r="11" fill="#ebbd63"/><path d="m245 64 8 77" stroke="#477b73" stroke-width="7" stroke-linecap="round"/><circle cx="266" cy="35" r="19" fill="#f9f5df"/><circle cx="266" cy="35" r="12" fill="#8c6651"/></svg>')}` },
]);
const previewMicrophones = async () => [{ id: "headset", label: "USB Headset" }, { id: "desk", label: "Desk Microphone" }];
+const previewApplications = async () => SOURCES.sources;
export function ControlsPreview() {
const { t, lang, vis } = useCopy();
const en = lang === "en";
const displayPreview = new URLSearchParams(window.location.search).get("source") === "display";
const [sound, setSound] = useState(true);
+ const [excludedAudio, setExcludedAudio] = useState<NativeCaptureTarget | undefined>(SOURCES.sources[2]);
const [microphone, setMicrophone] = useState(false);
const [microphoneVolume, setMicrophoneVolume] = useState(1);
const [voiceProcessing, setVoiceProcessing] = useState(true);
@@ -110,9 +114,13 @@ export function ControlsPreview() {
</div>
<SharingSettings id="preview-sharing-settings" open={sharingSettings}
presets={<QualityPresets selected={preset} onSelect={setPreset} />}
- audio={<HostMicrophoneSettings deviceId={microphoneDevice} onDevice={setMicrophoneDevice} loadDevices={previewMicrophones}
- enabled={microphone} disabled={paused} volume={microphoneVolume} onVolume={setMicrophoneVolume}
- voiceProcessing={voiceProcessing} onVoiceProcessing={setVoiceProcessing} />}
+ audio={<><div className="lr-door-group lr-source-audio-settings">
+ <SwitchItem checked={sound} onChange={setSound} label={t("host.sourcePicker.systemAudio")}
+ hint={sound ? "hint-stop-audio" : "hint-share-audio"} />
+ <LiveAudioExclusion load={previewApplications} value={excludedAudio} onChange={setExcludedAudio} disabled={!sound || paused} />
+ </div><HostMicrophoneSettings deviceId={microphoneDevice} onDevice={setMicrophoneDevice} loadDevices={previewMicrophones}
+ native enabled={microphone} disabled={paused} volume={microphoneVolume} onVolume={setMicrophoneVolume}
+ voiceProcessing={voiceProcessing} onVoiceProcessing={setVoiceProcessing} /></>}
/>
</section>
<section id="option-preview" className="cp-card">
diff --git a/src/client/pages/HostPage.tsx b/src/client/pages/HostPage.tsx
index 02cce2f0..3cfda822 100644
--- a/src/client/pages/HostPage.tsx
+++ b/src/client/pages/HostPage.tsx
@@ -28,6 +28,7 @@ import { WelcomeLine } from "../components/living/WelcomeLine";
import type { CouchEntry } from "../components/living/Couch";
import { SharingSettings } from "../components/living/SharingSettings";
import { HostMicrophone, HostMicrophoneSettings } from "../components/living/HostMicrophone";
+import { LiveAudioExclusion } from "../components/living/AudioExclusionSelect";
import { RoomInteractions } from "../components/living/RoomInteractions";
import { RoomChatOverlay } from "../components/living/RoomChatOverlay";
import type { RoomInteractionSession } from "../lib/room-interactions";
@@ -61,6 +62,7 @@ import {
StaticNoise,
} from "../components/living/Stage";
import { StatusIndicator } from "../components/living/StatusIndicator";
+import { ShareFailureHelp } from "../components/living/ShareFailureHelp";
import {
Btn,
Cap,
@@ -161,7 +163,7 @@ import type {
SignalConnectionState,
} from "../types";
import { HostPeer, type HostMediaPeer } from "../webrtc/host-peer";
-import { NativeClient, NativeCompatibilityError } from "../native/client";
+import { NativeClient, NativeCompatibilityError, NativeRequestError } from "../native/client";
import {
NativeSenderPeer,
shouldUseBrowserQualityCandidate,
@@ -172,6 +174,7 @@ import { NativeMediaBridge, NativeMediaBridgeError } from "../native/media-bridg
import { NativeMediaIngress } from "../native/media-ingress";
import {
defaultNativeCapturePath,
+ nativeCaptureTargetKey,
type NativeCapturePath,
} from "../native/capture-selection";
import type { NativeCaptureTarget } from "../native/wire";
@@ -194,6 +197,8 @@ import {
shouldPauseLocalPreview,
sourceSwitchNotice,
isCapturePermissionFailure,
+ hostFailureCode,
+ hostFailureChecks,
type HostAction,
} from "./host-page-notices";
@@ -204,8 +209,11 @@ type NoticeValue = (
target: "television" | "operation";
comic: ComicKind | HintKind;
tone: ComicTone;
+ failureCode?: string;
};
+type StatusNoticeMessage = string | { key: CopyKey; vars?: Record<string, string>; failureCode?: string };
+
const PREFERENCE_PRESENTATION: Record<
DegradationPreference,
{ icon: GlyphName; hint: CopyKey }
@@ -509,14 +517,14 @@ export function HostPage({
setNoticeValue({ kind: "key", key, vars, target: "operation", comic, tone });
}
function setStatusNotice(
- message: string | { key: CopyKey; vars?: Record<string, string> },
+ message: StatusNoticeMessage,
comic: ComicKind,
tone: ComicTone,
): void {
setNoticeValue({
...(typeof message === "string"
? { kind: "text", text: message }
- : { kind: "key", key: message.key, vars: message.vars }),
+ : { kind: "key", ...message, vars: message.vars }),
target: "television",
comic,
tone,
@@ -527,11 +535,13 @@ export function HostPage({
action: HostAction,
target: NoticeValue["target"] = "operation",
): void {
- if (error instanceof NativeMediaBridgeError) action = "connection";
+ if (error instanceof NativeMediaBridgeError || (error instanceof NativeRequestError &&
+ (["unavailable", "disconnected", "send-failed"].includes(error.reason) || error.operation === "prepare-edge"))) action = "connection";
const permissionMissing = isCapturePermissionFailure(error, action);
setNoticeValue({ kind: "text", text: readableError(error, action), target, tone: permissionMissing ? "warn" : "bad",
+ failureCode: error instanceof ApiError ? `site/http-${error.status}` : hostFailureCode(error, action),
comic: permissionMissing ? "hint-capture-browser" : action === "connection" ? "route-failed" : action === "capture" || action === "source"
- ? "source-failed" : action === "quality" ? "settings-failed" : "warning" });
+ ? "source-failed" : action === "quality" || action === "sourceAudio" ? "settings-failed" : "warning" });
}
function setNoticeErrorKey(
key: CopyKey,
@@ -597,7 +607,7 @@ export function HostPage({
const activeRouteRevisionRef = useRef(0);
const generationRef = useRef(0);
const activeGenerationRef = useRef<number | null>(null);
- const sourceSwitchRef = useRef<{ replacingVideo?: MediaStreamTrack } | null>(null);
+ const sourceSwitchRef = useRef<{ replacingVideo?: MediaStreamTrack; audioOnly?: boolean } | null>(null);
const qualityChangeRef = useRef<object | null>(null);
const pendingQualityChangeRef = useRef<QualitySettings | null>(null);
const qualitySettingsRef = useRef<QualitySettings>(DEFAULT_QUALITY_SETTINGS);
@@ -622,7 +632,12 @@ export function HostPage({
const nativeClientCloseCleanupRef = useRef<(() => void) | null>(null);
const nativeModeRef = useRef(false);
const nativeSourceAudioRef = useRef<boolean | undefined>(undefined);
- const nativeAudioSelectionRef = useRef<{ enabled: boolean; exclude?: NativeCaptureTarget } | null>(null);
+ const nativeSourceSelectionRef = useRef<Extract<ShareSourceSelection, { kind: "native" }> | null>(null);
+ const loadAudioApplications = useCallback(async () => {
+ const client = nativeClientRef.current;
+ if (!client || !nativeModeRef.current) throw new Error("Piik App is unavailable");
+ return client.sources();
+ }, []);
const nativeSourceRequestRef = useRef<object | null>(null);
const nativePreviewTailRef = useRef<Promise<void>>(Promise.resolve());
const nativeSourcePathRef = useRef<NativeCapturePath | null>(null);
@@ -986,7 +1001,7 @@ export function HostPage({
}
function endSharing(
- message: string | { key: CopyKey; vars?: Record<string, string> },
+ message: StatusNoticeMessage,
notifyServer = true,
comic: ComicKind = "share-ended",
tone: ComicTone = "off",
@@ -1207,7 +1222,7 @@ export function HostPage({
await nativeShareCleanupRef.current;
await nativePreviewTailRef.current;
if (!isCurrentShare(generation, shareGeneration)) return null;
- if (nativeClientRef.current !== client) throw new Error("Piik App is unavailable");
+ if (nativeClientRef.current !== client) throw new NativeRequestError("unavailable", "start-share");
// Acquire the required Browser peer before starting capture. Pending
// cancellation owns this bridge, but still closes control to abort startup.
bridge = new NativeMediaBridge(
@@ -1218,13 +1233,13 @@ export function HostPage({
nativeMediaBridgeRef.current === bridge &&
isCurrentShare(generation, shareGeneration)
) {
- endSharing({ key: "host.shareEnded" }, true, "source-failed", "bad");
+ endSharing({ key: "native.fail.edge", failureCode: "app/browser-media/connection" }, true, "route-failed", "bad");
}
},
);
nativeMediaBridgeRef.current = bridge;
nativeSourceAudioRef.current = undefined;
- nativeAudioSelectionRef.current = { enabled: audio, exclude: excludeAudio };
+ nativeSourceSelectionRef.current = selection;
nativeEventCleanup = client.onEvent((event) => {
if (event.shareId !== shareGeneration || !isCurrentShare(generation, shareGeneration) || nativeClientRef.current !== client) return;
if (event.type === "audio-state") {
@@ -1235,7 +1250,7 @@ export function HostPage({
}
if (event.type === "share-ended") {
endSharing(
- { key: event.failed ? "host.shareEnded" : "host.stopNotice" },
+ event.failed ? { key: "host.shareEnded", failureCode: "app/capture/failed" } : { key: "host.stopNotice" },
true,
event.failed ? "source-failed" : "share-ended",
event.failed ? "bad" : "off",
@@ -1262,7 +1277,7 @@ export function HostPage({
await client.stopShare(shareGeneration).catch(() => discardNativeClient(client));
return null;
}
- if (nativeClientRef.current !== client) throw new Error("Piik App is unavailable");
+ if (nativeClientRef.current !== client) throw new NativeRequestError("unavailable", "start-share");
nativeSourceAudioRef.current ??= started.sourceAudio ?? started.audio;
videoCodecRef.current = manualVideoCodecPreference(started.codec);
// Register ownership before waiting for the local bridge. A native edge
@@ -1317,7 +1332,7 @@ export function HostPage({
if (nativeMediaIngressRef.current) {
recoverBrowserFanout(nativeMediaIngressRef.current);
} else if (nativeModeRef.current && activeGenerationRef.current !== null) {
- endSharing({ key: "host.shareEnded" }, true, "source-failed", "bad");
+ endSharing({ key: "native.fail.controlDisconnected", failureCode: "app/control/disconnected" }, true, "route-failed", "bad");
}
});
}
@@ -1558,7 +1573,7 @@ export function HostPage({
nativeShareGenerationRef.current = null;
nativeModeRef.current = false;
nativeSourceAudioRef.current = undefined;
- nativeAudioSelectionRef.current = null;
+ nativeSourceSelectionRef.current = null;
setNativeActive(false);
if (!client || !shareGeneration) {
releaseUnusedNativeClient();
@@ -2839,7 +2854,10 @@ export function HostPage({
) {
return;
}
- const token = {};
+ const previous = nativeSourceSelectionRef.current;
+ const token = { audioOnly: target.kind !== "picker" && !!previous &&
+ nativeCaptureTargetKey(previous.target) === nativeCaptureTargetKey(target) &&
+ previous.showCaptureBorder === showCaptureBorder };
sourceSwitchRef.current = token;
closeCaptureSourcePicker();
setSwitchingSource(true);
@@ -2853,7 +2871,7 @@ export function HostPage({
) return;
// Preserve an exclusion request even on failure: the App mutes source
// audio before replacing it, and the next picker must not default to all.
- if (audio && excludeAudio) nativeAudioSelectionRef.current = { enabled: audio, exclude: excludeAudio };
+ if (audio && excludeAudio && previous) nativeSourceSelectionRef.current = { ...previous, audio, excludeAudio };
await client.replaceShareSource(
shareGeneration,
target,
@@ -2869,17 +2887,18 @@ export function HostPage({
) {
return;
}
- invalidateSenderQualityEvidence();
- nativeAudioSelectionRef.current = { enabled: audio, exclude: excludeAudio };
- if (routePolicyRef.current.topologyOptimization) {
- signalRef.current?.send({ type: "reset-sender-quality" });
- }
+ nativeSourceSelectionRef.current = { kind: "native", client, target, audio, path, showCaptureBorder, excludeAudio };
const activeStream = streamRef.current;
if (activeStream) {
setDetails(
captureDetails(activeStream, true, nativeSourceAudioRef.current),
);
}
+ if (token.audioOnly) return;
+ invalidateSenderQualityEvidence();
+ if (routePolicyRef.current.topologyOptimization) {
+ signalRef.current?.send({ type: "reset-sender-quality" });
+ }
const sfuUpdated = await hostSfuRouteRef.current?.updateProfile(qualitySettingsRef.current) ?? true;
if (
!isCurrentGeneration(generation) ||
@@ -2897,13 +2916,19 @@ export function HostPage({
isCurrentGeneration(generation) &&
sourceSwitchRef.current === token
) {
- setNoticeError(error, "source");
+ setNoticeError(error, token.audioOnly ? "sourceAudio" : "source");
}
} finally {
finishSourceSwitch(token);
}
}
+ function changeNativeSourceAudio(audio: boolean, excludeAudio?: NativeCaptureTarget): void {
+ const selection = nativeSourceSelectionRef.current;
+ if (!selection || selection.target.kind !== "display") return;
+ void switchNativeSource(selection.client, selection.target, audio, selection.path, selection.showCaptureBorder, excludeAudio);
+ }
+
async function switchSource(source?: BrowserCaptureSource, deviceId = ""): Promise<void> {
const generation = activeGenerationRef.current;
if (
@@ -2976,7 +3001,8 @@ export function HostPage({
return;
}
setNoticeValue({ kind: "key", key: error instanceof DOMException && error.name === "NotAllowedError"
- ? "host.camera.denied" : "host.camera.unavailable", target, comic: "source-failed", tone: "warn" });
+ ? "host.camera.denied" : "host.camera.unavailable", target, comic: "source-failed", tone: "warn",
+ failureCode: hostFailureCode(error, action, "camera") });
}
async function changeMicrophone(enabled: boolean, deviceId: string, voiceProcessing = microphoneVoiceProcessing): Promise<void> {
@@ -3546,8 +3572,12 @@ export function HostPage({
}
label={t("host.stageAria")}
indicator={<>
- <StatusIndicator status={hostStatus.television}
- label={statusNotice ? noticeText ?? undefined : undefined} />
+ {statusNotice && noticeText && (statusNotice.failureCode || statusNotice.tone === "bad")
+ ? <ShareFailureHelp key={`${statusNotice.failureCode}:${noticeText}`} status={hostStatus.television}
+ label={noticeText} code={statusNotice.failureCode ?? "status/unknown"}
+ checks={hostFailureChecks(statusNotice.failureCode ?? "status/unknown")} />
+ : <StatusIndicator status={hostStatus.television}
+ label={statusNotice ? noticeText ?? undefined : undefined} />}
<span className="visually-hidden" role="status" aria-live="polite">
{statusNotice ? noticeText : null}
</span>
@@ -3557,7 +3587,7 @@ export function HostPage({
<video ref={videoRef} autoPlay muted playsInline />
) : null}
<RoomChatOverlay session={room ? interactionSession : null}
- visible={phase === "live" && !nativeSources && !sharingPaused && !switchingSource && !localPreviewPaused} />
+ visible={phase === "live" && !nativeSources && !sharingPaused && !(switchingSource && !sourceSwitchRef.current?.audioOnly) && !localPreviewPaused} />
{nativeSources ? (
<CaptureSourcePicker
nativeSources={nativeSources}
@@ -3574,14 +3604,14 @@ export function HostPage({
selectionDisabled={roomMutating || switchingSource || changingQuality}
initialAudio={
nativeActive
- ? nativeAudioSelectionRef.current?.exclude
- ? nativeAudioSelectionRef.current.enabled
+ ? nativeSourceSelectionRef.current?.excludeAudio
+ ? nativeSourceSelectionRef.current.audio
: nativeSourceAudioRef.current ?? false
: true
}
audioLocked={nativeActive && !nativeClientRef.current?.health.nativeMedia.microphone}
initialShowCaptureBorder={showCaptureBorder}
- initialExcludeAudio={nativeAudioSelectionRef.current?.exclude}
+ initialExcludeAudio={nativeSourceSelectionRef.current?.excludeAudio}
/>
) : !stream &&
(phase === "idle" || phase === "ended" || phase === "error") ? (
@@ -3650,7 +3680,7 @@ export function HostPage({
) : null}
{/* The picker owns the stage while it is open: a state overlay
painted after it would cover and swallow its controls. */}
- {nativeSources ? null : switchingSource ? (
+ {nativeSources ? null : switchingSource && !sourceSwitchRef.current?.audioOnly ? (
<StageOverlay
icon="refresh"
comic="source-switching"
@@ -3694,7 +3724,7 @@ export function HostPage({
<Btn
id="host-switch-source"
icon="switchSource"
- cap={switchingSource ? "host.switching" : "host.switchSource"}
+ cap={switchingSource && !sourceSwitchRef.current?.audioOnly ? "host.switching" : "host.switchSource"}
title="host.switchSource"
hint="hint-switch-source"
disabled={switchingSource || changingQuality || microphonePending}
@@ -3890,6 +3920,18 @@ export function HostPage({
</div>
</>}
audio={<>
+ {phase === "live" && nativeActive && nativeSourceSelectionRef.current?.target.kind === "display" &&
+ nativeClientRef.current?.health.nativeMedia.microphone && nativeClientRef.current.health.nativeMedia.processAudioExclusion ? (
+ <div className="lr-door-group lr-source-audio-settings">
+ <SwitchItem checked={nativeSourceSelectionRef.current.audio}
+ label={t("host.sourcePicker.systemAudio")} hint={nativeSourceSelectionRef.current.audio ? "hint-stop-audio" : "hint-share-audio"}
+ disabled={microphonePending || switchingSource || changingQuality || sharingPaused}
+ onChange={audio => changeNativeSourceAudio(audio, nativeSourceSelectionRef.current?.excludeAudio)} />
+ <LiveAudioExclusion load={loadAudioApplications} value={nativeSourceSelectionRef.current.excludeAudio}
+ disabled={!nativeSourceSelectionRef.current.audio || microphonePending || switchingSource || changingQuality || sharingPaused}
+ onChange={target => changeNativeSourceAudio(true, target)} />
+ </div>
+ ) : null}
{phase === "live" && (!nativeActive || nativeClientRef.current?.health.nativeMedia.microphone) ? (
<HostMicrophoneSettings enabled={microphoneEnabled}
disabled={microphonePending || switchingSource || changingQuality || sharingPaused}
diff --git a/src/client/pages/StatusPreviewPage.tsx b/src/client/pages/StatusPreviewPage.tsx
index d3aa090b..7c8e4fce 100644
--- a/src/client/pages/StatusPreviewPage.tsx
+++ b/src/client/pages/StatusPreviewPage.tsx
@@ -4,6 +4,8 @@ import { AppHeader, LedStrip } from "../components/living/Header";
import { StageOverlay, StageTv } from "../components/living/Stage";
import { Couch } from "../components/living/Couch";
import { StatusIndicator } from "../components/living/StatusIndicator";
+import { ShareFailureHelp } from "../components/living/ShareFailureHelp";
+import { hostFailureChecks } from "./host-page-notices";
import { LoadingStatus } from "../components/living/WaitingStatus";
import { Pill } from "../components/living/primitives";
import { deriveViewerPresentation } from "../media/viewer-presentation";
@@ -56,6 +58,24 @@ export function StatusPreviewPage() {
<div className="lr-app sp-page" data-comic-reduced-motion={reducedMotion || undefined}>
<AppHeader homeHref="/__status-preview" />
<main className="sp-main">
+ <section className="sp-catalog" id="sharing-troubleshooting">
+ <header><h2>分享失败排查</h2><p>悬停看原因,点击状态图标打开排查;不会自动重试或更改设置。</p></header>
+ <div className="sp-catalog-grid">
+ {([
+ ["native.fail.captureStart", "app/start-share/rejected", "source-failed"],
+ ["native.fail.requestTimeout", "app/start-share/timeout", "source-failed"],
+ ["native.fail.controlDisconnected", "app/start-share/disconnected", "route-failed"],
+ ["native.fail.edge", "app/browser-media/connection", "route-failed"],
+ ["api.originNotAllowed", "site/http-403", "warning"],
+ ["host.capture.cancelled", "browser/NotAllowedError", "hint-capture-browser"],
+ ["host.camera.denied", "camera/NotAllowedError", "source-failed"],
+ ["host.roomInvalid", "status/unknown", "room-not-found"],
+ ] as const).map(([key, code, tooltip]) => <article key={code}>
+ <ShareFailureHelp status={{ icon: "alert", tone: code.endsWith("NotAllowedError") ? "warn" : "bad", tooltip, labelKey: key }} label={t(key)} code={code} checks={hostFailureChecks(code)} />
+ <span>{t(key)}</span>
+ </article>)}
+ </div>
+ </section>
<header className="sp-heading">
<div><p className="sp-kicker">Piik · 状态语义</p><h1>同一事实,各有分寸。</h1>
<p>标题说正在做什么,顶部说明信令,电视下沿图标说明画面;悬停查看图示与文字说明。</p></div>
diff --git a/src/client/pages/ViewerPage.tsx b/src/client/pages/ViewerPage.tsx
index c7458e7b..9207c306 100644
--- a/src/client/pages/ViewerPage.tsx
+++ b/src/client/pages/ViewerPage.tsx
@@ -2013,8 +2013,9 @@ export function ViewerPage({
: failureCode === "ROOM_FULL" ? "viewer.hint.full"
: codeOnlyDenied
? "viewer.hint.denied"
- : failureCode === "ROOM_NOT_FOUND" ||
- failureCode === "ROOM_CLOSED"
+ : failureCode === "ROOM_CLOSED" ? "viewer.hint.closed"
+ : failureCode === "SESSION_REPLACED" ? "viewer.hint.sessionReplaced"
+ : failureCode === "ROOM_NOT_FOUND"
? "viewer.hint.notFound"
: failureCode === "INVALID_TOKEN"
// A grant that the room no longer accepts is not a retry case:
diff --git a/src/client/pages/host-page-notices.ts b/src/client/pages/host-page-notices.ts
index c18aa46d..9585a0c4 100644
--- a/src/client/pages/host-page-notices.ts
+++ b/src/client/pages/host-page-notices.ts
@@ -1,10 +1,12 @@
import type { ServerMessage } from "../../shared/protocol";
+import { NativeRequestError } from "../native/client";
import { NativeMediaBridgeError, NativeMediaBridgeInitializationError } from "../native/media-bridge";
import { currentLang, joinSentences, say, type CopyKey } from "../ui/copy";
export type HostAction =
| "capture"
| "source"
+ | "sourceAudio"
| "quality"
| "connection"
| "room";
@@ -12,6 +14,7 @@ export type HostAction =
const HOST_ACTION_FALLBACK: Record<HostAction, CopyKey> = {
capture: "host.fail.start",
source: "host.fail.source",
+ sourceAudio: "host.fail.sourceAudio",
quality: "host.fail.quality",
connection: "host.fail.connection",
room: "host.fail.room",
@@ -44,6 +47,19 @@ export function hostActionErrorNotice(
error: unknown,
action: HostAction,
): string {
+ if (error instanceof NativeRequestError) {
+ switch (error.reason) {
+ case "unavailable":
+ case "disconnected":
+ case "send-failed": return say("native.fail.controlDisconnected");
+ case "timeout": return say("native.fail.requestTimeout");
+ case "invalid-response": return say("native.fail.invalidResponse");
+ case "rejected":
+ if (error.operation === "start-share") return say("native.fail.captureStart");
+ if (error.operation === "prepare-edge") return say("native.fail.edgePrepare");
+ break;
+ }
+ }
if (error instanceof NativeMediaBridgeInitializationError) return say("native.fail.browserMedia");
if (error instanceof NativeMediaBridgeError) return say("native.fail.edge");
if (isCapturePermissionFailure(error, action)) return say("host.capture.cancelled");
@@ -58,11 +74,45 @@ export function hostActionErrorNotice(
return say("host.capture.readFailed");
case "SecurityError":
return say("host.capture.unavailable");
+ case "InvalidStateError":
+ return say("host.capture.inactive");
+ case "OverconstrainedError":
+ return say("host.capture.constraints");
}
}
return say(HOST_ACTION_FALLBACK[action]);
}
+/** Safe support context: never copy arbitrary exception text or request fields. */
+export function hostFailureCode(error: unknown, action: HostAction, source: "browser" | "camera" = "browser"): string {
+ if (error instanceof NativeRequestError) return `app/${error.operation}/${error.reason}`;
+ if (error instanceof NativeMediaBridgeInitializationError) return "app/browser-media/init";
+ if (error instanceof NativeMediaBridgeError) return "app/browser-media/connection";
+ if (error instanceof DOMException && ["NotAllowedError", "NotFoundError", "NotReadableError",
+ "SecurityError", "InvalidStateError", "OverconstrainedError", "AbortError"].includes(error.name)) {
+ return `${source}/${error.name}`;
+ }
+ return `${source === "camera" ? "camera" : action}/unknown`;
+}
+
+export function hostFailureChecks(code: string): CopyKey[] {
+ const [scope, operation, reason] = code.split("/");
+ if (scope === "camera") return ["shareHelp.camera"];
+ if (scope === "site" || scope === "room") return ["shareHelp.site"];
+ if (scope === "app") {
+ if (["unavailable", "disconnected", "send-failed", "timeout", "invalid-response"].includes(reason)) return ["shareHelp.appConnection"];
+ if (operation === "browser-media" || operation === "prepare-edge") return ["shareHelp.mediaConnection"];
+ if (operation === "start-share" || operation === "capture") return ["shareHelp.source", "shareHelp.compare"];
+ }
+ if (scope === "browser") {
+ return ["NotAllowedError", "SecurityError", "InvalidStateError"].includes(operation)
+ ? ["shareHelp.permission"] : ["shareHelp.source"];
+ }
+ if (scope === "capture" || scope === "source") return ["shareHelp.source"];
+ // A room/session or settings failure is not evidence that capture failed.
+ return [];
+}
+
export function hostServerErrorNotice(code: ServerErrorCode): string {
return say(HOST_SERVER_ERROR_NOTICE[code]);
}
diff --git a/src/client/sfu/peer.ts b/src/client/sfu/peer.ts
index fe60e3ed..bcc03b4a 100644
--- a/src/client/sfu/peer.ts
+++ b/src/client/sfu/peer.ts
@@ -1,6 +1,7 @@
import { observeDebugConnection } from "../lib/debug-webrtc";
import { addRemoteIceCandidate } from "../webrtc/nat-prediction";
import { waitForConnectionOperation } from "../webrtc/connection-operation";
+import { normalizeVideoOfferSdp } from "../webrtc/video-codec";
import type {
ServerMessage,
SfuMedia,
@@ -96,7 +97,7 @@ export class SfuPeer {
}
this.pendingDescription = {
kind: "description",
- description: { type: local.type, sdp: local.sdp },
+ description: { type: local.type, sdp: local.type === "offer" ? normalizeVideoOfferSdp(local.sdp) : local.sdp },
...(media ? { media } : {}),
};
this.flushSignaling();
diff --git a/src/client/styles.css b/src/client/styles.css
index a30b7a4c..0de3389d 100644
--- a/src/client/styles.css
+++ b/src/client/styles.css
@@ -1856,6 +1856,8 @@ html[data-theme="dark"] .lr-switch::after { background: var(--ink); }
.lr-host-share-controls > .lr-comic-tip-wrap:has(#host-stop-share) { margin-inline-start: 4px; padding-inline-start: 8px; border-inline-start: 1px solid var(--control-edge); }
.lr-microphone-settings { min-width: 0; max-width: 440px; gap: 6px; }
.lr-microphone-settings .lr-capture-device { padding: 0; }
+.lr-source-audio-settings .lr-capture-device { padding: 0; }
+.lr-audio-exclusion-select label { display: flex; align-items: center; gap: 6px; cursor: default; }
.lr-microphone-settings > label { display: flex; align-items: center; justify-content: space-between; gap: 12px; font-size: 12px; color: var(--muted); }
.lr-microphone-settings > .lr-comic-tip-wrap { display: flex; width: 100%; }
.lr-microphone-settings input { width: 100%; min-width: 32px; height: 36px; padding: 0; accent-color: var(--action); cursor: pointer; }
diff --git a/src/client/ui/visual-kinds.ts b/src/client/ui/visual-kinds.ts
index 691c6b86..d8a54d3d 100644
--- a/src/client/ui/visual-kinds.ts
+++ b/src/client/ui/visual-kinds.ts
@@ -72,6 +72,7 @@ export type Set2Kind =
export type Set3Kind =
| "hint-quality"
| "hint-audio-quality"
+ | "hint-exclude-audio"
| "hint-degrade-pref"
| "hint-prefer-resolution"
| "hint-prefer-framerate"
diff --git a/src/client/webrtc/host-peer.ts b/src/client/webrtc/host-peer.ts
index 19045722..d89c399b 100644
--- a/src/client/webrtc/host-peer.ts
+++ b/src/client/webrtc/host-peer.ts
@@ -29,6 +29,7 @@ import {
} from "./stats";
import {
applyVideoCodecPreference,
+ normalizeVideoOfferSdp,
type BrowserVideoCodecPreference,
VP8_ONLY_VIDEO_CODEC,
} from "./video-codec";
@@ -703,7 +704,7 @@ export class HostPeer {
connectionId: this.connectionId,
description: {
type: "offer",
- sdp: this.connection.localDescription.sdp,
+ sdp: normalizeVideoOfferSdp(this.connection.localDescription.sdp),
},
})
) {
diff --git a/src/client/webrtc/stats.ts b/src/client/webrtc/stats.ts
index 8f2bee92..2084a606 100644
--- a/src/client/webrtc/stats.ts
+++ b/src/client/webrtc/stats.ts
@@ -413,13 +413,28 @@ function mediaTrackIdentifier(
return stringValue(source, "trackIdentifier");
}
-function mediaSourceRecord(
+export function mediaSourceRecord(
report: RTCStatsReport,
media: StatsRecord | null,
): StatsRecord | null {
- const source = getRecord(report, stringValue(media, "mediaSourceId"));
- return source?.type === "media-source"
- ? source
+ if (!media || media.type !== "outbound-rtp" || media.isRemote === true) return null;
+ if (media.mediaSourceId !== undefined) {
+ const source = getRecord(report, stringValue(media, "mediaSourceId"));
+ return source?.type === "media-source" ? source : null;
+ }
+ if (media.kind !== "video" && media.kind !== "audio") return null;
+ // Some browsers omit the link. Infer it only for one sender and one source
+ // of the same kind; stale/multiple senders or sources remain ambiguous.
+ const senders: StatsRecord[] = [];
+ const sources: StatsRecord[] = [];
+ report.forEach((raw) => {
+ const record = raw as StatsRecord;
+ if (record.kind !== media.kind) return;
+ if (record.type === "outbound-rtp" && record.isRemote !== true) senders.push(record);
+ if (record.type === "media-source") sources.push(record);
+ });
+ return senders.length === 1 && senders[0]!.id === media.id && sources.length === 1
+ ? sources[0]!
: null;
}
diff --git a/src/client/webrtc/video-codec-preflight.ts b/src/client/webrtc/video-codec-preflight.ts
index 975ac272..1084082b 100644
--- a/src/client/webrtc/video-codec-preflight.ts
+++ b/src/client/webrtc/video-codec-preflight.ts
@@ -6,9 +6,11 @@ import {
} from "../media/quality";
import {
applyH264ProbeCodec,
+ normalizeVideoOfferSdp,
type BrowserVideoCodec,
} from "./video-codec";
import { addRemoteIceCandidate } from "./nat-prediction";
+import { mediaSourceRecord } from "./stats";
const PREFLIGHT_DEADLINE_MS = 4_000;
const PREFLIGHT_POLL_MS = 100;
@@ -174,7 +176,7 @@ function readH264ProbeSample(report: RTCStatsReport): H264ProbeSample | null {
}
const outbound = candidates[0]!;
const codec = recordById(report, outbound.codecId);
- const source = recordById(report, outbound.mediaSourceId);
+ const source = mediaSourceRecord(report, outbound);
const mimeType = stringValue(codec?.mimeType);
if (
codec?.type !== "codec" ||
@@ -345,7 +347,7 @@ async function runH264Probe(
const offer = await wait(() => senderConnection.createOffer());
await wait(() => senderConnection.setLocalDescription(offer));
await wait(() => receiverConnection.setRemoteDescription(
- senderConnection.localDescription!,
+ { type: "offer", sdp: normalizeVideoOfferSdp(senderConnection.localDescription!.sdp) },
));
receiverRemoteReady = true;
await wait(() => Promise.all(
diff --git a/src/client/webrtc/video-codec.ts b/src/client/webrtc/video-codec.ts
index 85330e85..2b416059 100644
--- a/src/client/webrtc/video-codec.ts
+++ b/src/client/webrtc/video-codec.ts
@@ -111,3 +111,27 @@ export function applyH264ProbeCodec(
return h264.length > 0 &&
applyCodecs(transceiver, [...h264, ...repairCodecs(codecs)]);
}
+
+/** Remove only attributes of codecs excluded from a locally generated offer.
+ * Firefox can retain them after setCodecPreferences (Mozilla bug 1909443),
+ * making the whole offer unparseable in Chromium. Do not rewrite codec choices,
+ * valid feedback, unknown attributes or answers with asymmetric payload types.
+ */
+export function normalizeVideoOfferSdp(sdp: string): string {
+ let payloads: Set<number> | null = null;
+ let changed = false;
+ const lines = sdp.split(/\r?\n/).filter(line => {
+ if (line.startsWith("m=")) {
+ const fields = line.trim().split(/\s+/);
+ payloads = fields[0] === "m=video" && fields.length >= 4
+ ? new Set(fields.slice(3).map(Number)) : null;
+ }
+ const attribute = /^a=(?:fmtp|rtcp-fb):(\d+)(?:\s|$)/.exec(line);
+ if (payloads && attribute && !payloads.has(Number(attribute[1]))) {
+ changed = true;
+ return false;
+ }
+ return true;
+ });
+ return changed ? lines.join(sdp.includes("\r\n") ? "\r\n" : "\n") : sdp;
+}
diff --git a/tests/client-state.test.ts b/tests/client-state.test.ts
index 85acc488..43272e10 100644
--- a/tests/client-state.test.ts
+++ b/tests/client-state.test.ts
@@ -22,7 +22,7 @@ import {
readDisplayName,
saveDisplayName,
} from "../src/client/lib/display-name.ts";
-import { setCopy } from "../src/client/ui/copy.ts";
+import { say, setCopy } from "../src/client/ui/copy.ts";
import {
clearHostRoom,
clientLaunchURL,
@@ -746,8 +746,8 @@ describe("site access API", () => {
new Response(JSON.stringify({ error: "Origin not allowed" }), { status: 403 }),
));
const message = lang === "zh"
- ? "服务器未允许当前网址 (403)。请联系站点管理员检查 PUBLIC_BASE_URL 和 ALLOWED_ORIGINS。"
- : "This address is not allowed by the server (403). Ask the site administrator to check PUBLIC_BASE_URL and ALLOWED_ORIGINS.";
+ ? "当前网址不在服务器允许的范围内 (403),请联系管理员。"
+ : "The server does not allow this address (403); contact the site administrator.";
for (const request of [
() => authenticateSiteAccess("password"),
() => createRoom("open", null),
@@ -763,7 +763,7 @@ describe("site access API", () => {
vi.stubGlobal("fetch", vi.fn<typeof fetch>().mockResolvedValue(new Response(body, { status: 403 })));
await expect(createRoom("open", null)).rejects.toMatchObject({
status: 403,
- message: expect.not.stringContaining("ALLOWED_ORIGINS"),
+ message: expect.not.stringContaining(say("api.originNotAllowed")),
});
}
});
@@ -835,7 +835,7 @@ describe("site access API", () => {
await expect(getSiteAccess()).rejects.toMatchObject({
status: 503,
- message: "站点验证服务暂时不可用 (503)",
+ message: "站点服务暂不可用 (503),请稍后重试",
});
});
diff --git a/tests/host-page-notice.test.ts b/tests/host-page-notice.test.ts
index b56de011..6a2f86b7 100644
--- a/tests/host-page-notice.test.ts
+++ b/tests/host-page-notice.test.ts
@@ -2,8 +2,11 @@ import { describe, expect, it } from "vitest";
import { setCopy } from "../src/client/ui/copy.ts";
import { NativeMediaBridgeError, NativeMediaBridgeInitializationError } from "../src/client/native/media-bridge";
+import { NativeRequestError } from "../src/client/native/client";
import {
hostActionErrorNotice,
+ hostFailureCode,
+ hostFailureChecks,
hostServerErrorNotice,
shouldPauseLocalPreview,
sourceSwitchNotice,
@@ -12,9 +15,42 @@ import {
setCopy({ lang: "zh" });
describe("host error notices", () => {
+ it("keeps known App failure boundaries and support context without claiming a driver diagnosis", () => {
+ const rejected = new NativeRequestError("rejected", "start-share", { cause: "private source title" });
+ const timeout = new NativeRequestError("timeout", "start-share");
+ const disconnected = new NativeRequestError("disconnected", "start-share");
+ expect(hostActionErrorNotice(rejected, "capture")).toContain("未能采集所选来源");
+ expect(hostActionErrorNotice(timeout, "capture")).toContain("响应超时");
+ expect(hostActionErrorNotice(disconnected, "capture")).toContain("连接已断开");
+ expect(hostFailureCode(rejected, "capture")).toBe("app/start-share/rejected");
+ expect(hostFailureCode(new Error("secret invitation and source"), "capture")).toBe("capture/unknown");
+ expect(hostFailureCode(new DOMException("secret", "UnrecognizedError"), "capture")).toBe("capture/unknown");
+ expect(hostFailureCode(new DOMException("secret", "NotAllowedError"), "capture", "camera")).toBe("camera/NotAllowedError");
+ });
+
+ it.each([
+ ["site/http-403", ["shareHelp.site"]],
+ ["room/unknown", ["shareHelp.site"]],
+ ["app/start-share/rejected", ["shareHelp.source", "shareHelp.compare"]],
+ ["app/start-share/timeout", ["shareHelp.appConnection"]],
+ ["app/control/disconnected", ["shareHelp.appConnection"]],
+ ["app/prepare-edge/disconnected", ["shareHelp.appConnection"]],
+ ["app/prepare-edge/rejected", ["shareHelp.mediaConnection"]],
+ ["app/browser-media/connection", ["shareHelp.mediaConnection"]],
+ ["app/capture/failed", ["shareHelp.source", "shareHelp.compare"]],
+ ["browser/NotAllowedError", ["shareHelp.permission"]],
+ ["browser/NotReadableError", ["shareHelp.source"]],
+ ["camera/NotAllowedError", ["shareHelp.camera"]],
+ ["status/unknown", []],
+ ["connection/unknown", []],
+ ["quality/unknown", []],
+ ["app/update-share/rejected", []],
+ ])("keeps troubleshooting relevant to %s", (code, checks) => {
+ expect(hostFailureChecks(code as string)).toEqual(checks);
+ });
it.each([
- ["zh", "浏览器无法建立媒体连接。请刷新页面,或换一个浏览器重试。"],
- ["en", "The browser could not create a media connection. Refresh the page or try another browser."],
+ ["zh", "浏览器无法建立媒体连接,请刷新页面重试。"],
+ ["en", "The browser could not create a media connection; reload to retry."],
] as const)("identifies Browser initialization failure in %s without blaming capture permission", (lang, notice) => {
setCopy({ lang });
try {
@@ -64,13 +100,16 @@ describe("host error notices", () => {
);
expect(hostActionErrorNotice(sentinel, "room")).toBe("房间操作失败");
expect(hostActionErrorNotice(sentinel, "source")).toBe("切换分享来源失败");
+ expect(hostActionErrorNotice(sentinel, "sourceAudio")).toBe("未能更新来源声音,请重试");
});
it.each([
["NotAllowedError", "屏幕选择已取消或没有共享权限"],
["NotFoundError", "没有可用的屏幕分享来源"],
- ["NotReadableError", "浏览器暂时无法读取所选分享来源"],
+ ["NotReadableError", "无法读取所选分享来源,请重新选源"],
["SecurityError", "当前页面无法启动屏幕分享"],
+ ["InvalidStateError", "请回到当前页面,再点击分享并选择来源。"],
+ ["OverconstrainedError", "所选来源无法满足当前画面设置。请降低设置或换一个来源。"],
])("maps capture DOMException %s", (name, notice) => {
expect(
hostActionErrorNotice(new DOMException("raw-browser-text", name), "capture"),
diff --git a/tests/host-quality-ownership.test.ts b/tests/host-quality-ownership.test.ts
index 05434f2e..302ba4dc 100644
--- a/tests/host-quality-ownership.test.ts
+++ b/tests/host-quality-ownership.test.ts
@@ -8,11 +8,12 @@ import {
type QualitySettings,
} from "../src/client/media/quality";
import { NativeSenderPeer } from "../src/client/native/native-sender-peer";
-import { NativeCompatibilityError } from "../src/client/native/client";
+import { NativeCompatibilityError, NativeRequestError } from "../src/client/native/client";
+import { nativeCaptureTargetKey } from "../src/client/native/capture-selection";
import { NativeMediaBridgeError } from "../src/client/native/media-bridge";
import { reconcileBoundedMediaChildren } from "../src/client/webrtc/media-assignment";
import { debugError, debugEvent, debugOperation } from "../src/client/lib/debug";
-import { hostActionErrorNotice, isCapturePermissionFailure } from "../src/client/pages/host-page-notices";
+import { hostActionErrorNotice, hostFailureCode, isCapturePermissionFailure } from "../src/client/pages/host-page-notices";
// Exercise the actual page owners without mounting capture hardware or a Browser.
const source = ts.createSourceFile("HostPage.tsx", readFileSync(
@@ -63,13 +64,13 @@ function fixture(launchedByClient = true) {
const client = { updateShare: vi.fn(async () => undefined), replaceShareSource: vi.fn(async () => undefined),
startShare: vi.fn(async (): Promise<{ audio: boolean; codec: "h264" }> => ({ audio: false, codec: "h264" })),
onEvent: vi.fn((_listener: (event: unknown) => void) => () => undefined),
- close: vi.fn(), onClose: vi.fn(() => () => undefined),
+ close: vi.fn(), onClose: vi.fn((_listener: () => void) => () => undefined),
health: { nativeMedia: { video: true, hardwareH264: true, softwareVP8: true } },
captureOptions: vi.fn(async () => []), sources: vi.fn(async () => []),
stopReceive: vi.fn(async () => undefined), stopShare: vi.fn(async () => undefined) };
const route = { updateProfile: vi.fn(async () => true), resyncAuthoritative: vi.fn(async (): Promise<void> => undefined) };
const state = {
- debugError, debugEvent, debugOperation, NativeCompatibilityError, NativeMediaBridgeError, isCapturePermissionFailure, DOMException,
+ debugError, debugEvent, debugOperation, NativeCompatibilityError, NativeRequestError, NativeMediaBridgeError, isCapturePermissionFailure, hostFailureCode, DOMException,
launchedByClient, hostRoomSessionAvailable: false,
NativeClient: { connect: vi.fn(async (): Promise<typeof client | null> => null) },
nativeClientConnectRef: ref<Promise<typeof client | null> | null>(null),
@@ -87,13 +88,13 @@ function fixture(launchedByClient = true) {
createRoom: vi.fn(async () => { throw new Error("must not create an empty room"); }),
readPreferredRoomId: () => null, disposeResources: vi.fn(), ApiError: class extends Error {},
- NativeMediaBridge: vi.fn(function () { return bridge; }), manualVideoCodecPreference: vi.fn(),
+ NativeMediaBridge: vi.fn(function (_shareId: string, _client: unknown, _onFailed: () => void) { return bridge; }), manualVideoCodecPreference: vi.fn(),
phase: "live", qualitySettingsRef: ref<QualitySettings>(original), advancedQualityRef: ref<QualitySettings>(original),
qualityChangeRef: ref<object | null>(null), pendingQualityChangeRef: ref<QualitySettings | null>(null),
activeGenerationRef: ref<number | null>(1), streamRef: ref<typeof stream | null>(stream), sourceSwitchRef: ref<object | null>(null),
nativeSourceAudioRef: ref<boolean | undefined>(undefined), setMicrophoneEnabled: vi.fn(),
microphoneVoiceProcessing: true, setMicrophoneVoiceProcessing: vi.fn(),
- nativeAudioSelectionRef: ref<{ enabled: boolean; exclude?: unknown } | null>(null),
+ nativeSourceSelectionRef: ref<Record<string, unknown> | null>(null), nativeCaptureTargetKey,
nativeModeRef: ref(false), nativeClientRef: ref<typeof client | null>(client), nativeShareGenerationRef: ref<string | null>("share"),
hostAudioRef: ref<{ sourceStream: MediaStream } | null>(null),
nativeMediaIngressRef: ref<ReturnType<typeof ingress> | null>(null), nativeMediaBridgeRef: ref(null),
@@ -483,15 +484,31 @@ describe("Host quality ownership", () => {
const path = { adapterIndex: 0, encoderIndex: 0 };
for (const enabled of [true, false, true]) {
await current.context.switchNativeSource(current.client, target, enabled, path, false, excluded);
- expect(current.nativeAudioSelectionRef.current).toEqual({ enabled, exclude: excluded });
+ expect(current.nativeSourceSelectionRef.current).toMatchObject({ target, audio: enabled, excludeAudio: excluded });
expect(current.client.replaceShareSource).toHaveBeenLastCalledWith("share", target, enabled, path, false, enabled ? excluded : undefined);
}
const next = { ...excluded, pid: 321, creationTime: "654" };
current.client.replaceShareSource.mockRejectedValueOnce(new Error("audio unavailable"));
await current.context.switchNativeSource(current.client, target, true, path, false, next);
- expect(current.nativeAudioSelectionRef.current).toEqual({ enabled: true, exclude: next });
+ expect(current.nativeSourceSelectionRef.current).toMatchObject({ target, audio: true, excludeAudio: next });
current.disposeNative();
- expect(current.nativeAudioSelectionRef.current).toBeNull();
+ expect(current.nativeSourceSelectionRef.current).toBeNull();
+ });
+
+ it("changes native source audio without resetting sender quality or SFU publication", async () => {
+ const current = fixture();
+ current.nativeModeRef.current = true;
+ current.routePolicyRef.current.topologyOptimization = true;
+ const target = { kind: "display", sourceId: "2", title: "Display" };
+ const path = { adapterIndex: 0, encoderIndex: 0 };
+ current.nativeSourceSelectionRef.current = { target, path, client: current.client, showCaptureBorder: false, audio: true };
+ const excluded = { kind: "window", sourceId: "3", pid: 123, creationTime: "456", title: "Voice" };
+ await current.context.switchNativeSource(current.client, { ...target, title: "Renamed" }, true, path, false, excluded);
+ expect(current.client.replaceShareSource).toHaveBeenCalledOnce();
+ expect(current.invalidateSenderQualityEvidence).not.toHaveBeenCalled();
+ expect(current.signalRef.current.send).not.toHaveBeenCalled();
+ expect(current.hostSfuRouteRef.current.updateProfile).not.toHaveBeenCalled();
+ expect(current.sourceSwitchRef.current).toBeNull();
});
it.each(["browser", "native"] as const)("keeps the %s selection until room work permits capture", async (kind) => {
@@ -563,6 +580,7 @@ describe("Host quality ownership", () => {
expect(setNoticeValue).toHaveBeenLastCalledWith({
kind: "text", text: hostActionErrorNotice(denied, "capture"),
target: "television", comic: "hint-capture-browser", tone: "warn",
+ failureCode: "browser/NotAllowedError",
});
expect(current.setPhase).toHaveBeenLastCalledWith("idle");
expect(current.createRoom).not.toHaveBeenCalled();
@@ -732,6 +750,7 @@ describe("Host quality ownership", () => {
expect(setNoticeValue).toHaveBeenLastCalledWith({
kind: "text", text: hostActionErrorNotice(denied, "source"),
target: "operation", comic: "hint-capture-browser", tone: "warn",
+ failureCode: "browser/NotAllowedError",
});
expect(current.setPhase).not.toHaveBeenCalled();
expect(current.track.stop).not.toHaveBeenCalled();
@@ -754,6 +773,26 @@ describe("Host quality ownership", () => {
expect(current.activeGenerationRef.current).toBeNull();
});
+ it.each([
+ ["capture", "host.shareEnded", "app/capture/failed", "source-failed"],
+ ["media", "native.fail.edge", "app/browser-media/connection", "route-failed"],
+ ["control", "native.fail.controlDisconnected", "app/control/disconnected", "route-failed"],
+ ])("retains the known %s failure when retiring native sharing", async (kind, key, failureCode, comic) => {
+ const current = fixture();
+ current.generationRef.current = 1;
+ current.nativeClientRef.current = null;
+ current.context.ownNativeClient(current.client);
+ await current.startNative();
+ if (kind === "control") current.client.onClose.mock.calls[0]![0]();
+ else if (kind === "media") current.NativeMediaBridge.mock.calls[0]![2]();
+ else current.client.onEvent.mock.calls[0]![0]({ type: "share-ended", shareId: "share", failed: true });
+ expect(current.setNoticeValue).toHaveBeenLastCalledWith({
+ kind: "key", key, vars: undefined, failureCode, target: "television", comic, tone: "bad",
+ });
+ expect(current.disposeResources).toHaveBeenCalledExactlyOnceWith(true, false);
+ expect(current.activeGenerationRef.current).toBeNull();
+ });
+
it("retains connecting children during reconciliation and rebuilds them after reauthentication", async () => {
const current = fixture(false);
current.nativeClientRef.current = null;
diff --git a/tests/media-source-stats.test.ts b/tests/media-source-stats.test.ts
new file mode 100644
index 00000000..b2ecabe8
--- /dev/null
+++ b/tests/media-source-stats.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+ collectConnectionMetricsFromReport,
+ collectNativeSenderQualityFromReport,
+ createNativeSenderQualityAccumulator,
+ createStatsAccumulator,
+ maxEncodedVideoFrames,
+ mediaSourceRecord,
+} from "../src/client/webrtc/stats.ts";
+
+function report(timestamp = 1_000, trackIdentifier = "video-track") {
+ const records = [
+ { id: "video", type: "outbound-rtp", kind: "video", bytesSent: timestamp * 100,
+ framesEncoded: timestamp * 30 / 1_000, frameWidth: 1280, frameHeight: 720 },
+ { id: "video-source", type: "media-source", kind: "video", trackIdentifier,
+ framesPerSecond: 30 },
+ { id: "audio", type: "outbound-rtp", kind: "audio", bytesSent: timestamp * 16 },
+ { id: "audio-source", type: "media-source", kind: "audio", trackIdentifier: "audio-track" },
+ { id: "received", type: "inbound-rtp", kind: "video" },
+ { id: "remote", type: "remote-outbound-rtp", kind: "video" },
+ ];
+ return new Map(records.map((record) => [record.id, { ...record, timestamp }])) as unknown as RTCStatsReport;
+}
+
+describe("sender source statistics", () => {
+ it("reads the sole same-kind source without mediaSourceId and resets on replacement", () => {
+ const previous = createStatsAccumulator();
+ const sample = (timestamp: number, trackIdentifier = "video-track") =>
+ collectConnectionMetricsFromReport(report(timestamp, trackIdentifier), "send", previous,
+ { trackIdentifier, audioTrackIdentifier: "audio-track" });
+
+ expect(sample(1_000)).toMatchObject({
+ trackIdentifier: "video-track", mediaSourceFramesPerSecond: 30,
+ resolution: "1280x720", intervalFramesEncoded: null, audioBitrateKbps: null,
+ });
+ expect(sample(2_000)).toMatchObject({
+ intervalFramesEncoded: 30, bitrateKbps: 800, audioBitrateKbps: 128,
+ });
+ expect(sample(3_000, "replacement")).toMatchObject({
+ trackIdentifier: "replacement", intervalFramesEncoded: null, bitrateKbps: null,
+ });
+ expect(maxEncodedVideoFrames(report(3_000, "replacement"), "video-track")).toBeNull();
+ expect(maxEncodedVideoFrames(report(3_000, "replacement"), "replacement")).toBe(90);
+
+ const quality = createNativeSenderQualityAccumulator();
+ collectNativeSenderQualityFromReport(report(1_000), "video-track", quality);
+ expect(collectNativeSenderQualityFromReport(report(2_000), "video-track", quality))
+ .toMatchObject({ bitrateKbps: 800, nativeEdgeQualityState: "unknown" });
+ });
+
+ it.each(["media-source", "outbound-rtp"])("does not infer a source with another %s of the same kind", (type) => {
+ const stats = report();
+ (stats as unknown as Map<string, unknown>).set("old", {
+ id: "old", type, kind: "video", timestamp: 1_000, trackIdentifier: "old-track",
+ });
+ expect(mediaSourceRecord(stats, stats.get("video"))).toBeNull();
+ expect(maxEncodedVideoFrames(stats, "video-track")).toBeNull();
+ stats.get("video").mediaSourceId = "video-source";
+ expect(maxEncodedVideoFrames(stats, "video-track")).toBe(30);
+ });
+
+ it.each(["missing", "received", null, ""])("does not replace an invalid explicit reference (%s)", (mediaSourceId) => {
+ const stats = report();
+ stats.get("video").mediaSourceId = mediaSourceId;
+ expect(mediaSourceRecord(stats, stats.get("video"))).toBeNull();
+ });
+});
diff --git a/tests/native-capture-selection.test.ts b/tests/native-capture-selection.test.ts
index c8782a02..a3fc714f 100644
--- a/tests/native-capture-selection.test.ts
+++ b/tests/native-capture-selection.test.ts
@@ -3,6 +3,7 @@ import { createElement } from "react";
import { renderToStaticMarkup } from "react-dom/server";
import { CaptureSourcePicker } from "../src/client/components/living/CaptureSourcePicker";
+import { AudioExclusionSelect } from "../src/client/components/living/AudioExclusionSelect";
import { setCopy, t } from "../src/client/ui/copy";
import {
@@ -62,6 +63,18 @@ describe("native capture source selection", () => {
).toBe("display:2");
});
+ it("keeps a missing exclusion selected and distinguishes a restarted process", () => {
+ setCopy({ lang: "en", vis: false });
+ const restarted = { ...game, creationTime: "654321" };
+ const html = renderToStaticMarkup(createElement(AudioExclusionSelect, {
+ sources: [restarted, { ...restarted, sourceId: "2" }],
+ value: game, onChange: () => {},
+ }));
+ expect(html).toMatch(/<option value="10:123456" disabled="" selected="">/);
+ expect(html.match(/<option value="10:654321"/g)).toHaveLength(1);
+ expect(html).not.toMatch(/<option value="" selected="">/);
+ });
+
it.each(["unavailable", "unsupported", "failed"] as const)("does not describe %s as an empty list or block Browser capture", (kind) => {
for (const mode of ["en", "zh", "vis"] as const) {
const lang = mode === "zh" ? "zh" : "en";
diff --git a/tests/native-client.test.ts b/tests/native-client.test.ts
index 4700674a..b76fc626 100644
--- a/tests/native-client.test.ts
+++ b/tests/native-client.test.ts
@@ -302,13 +302,27 @@ describe("native App private wire", () => {
const unexpected = vi.fn();
client!.onClose(unexpected);
await expect(client!.updateShare("share_123456", DEFAULT_QUALITY_SETTINGS))
- .rejects.toThrow("Piik App request failed");
+ .rejects.toMatchObject({ name: "NativeRequestError", reason: "rejected", operation: "update-share" });
await client!.ping();
expect(sockets[0]!.close).not.toHaveBeenCalled();
expect(unexpected).not.toHaveBeenCalled();
+ vi.useFakeTimers();
+ window.setTimeout = globalThis.setTimeout;
+ window.clearTimeout = globalThis.clearTimeout;
+ const timedOut = expect(client!.sources()).rejects.toMatchObject({ reason: "timeout", operation: "list-sources" });
+ await vi.advanceTimersByTimeAsync(8_000);
+ await timedOut;
+ expect(sockets[0]!.close).not.toHaveBeenCalled();
+ vi.useRealTimers();
+ window.setTimeout = globalThis.setTimeout;
+ window.clearTimeout = globalThis.clearTimeout;
+ const pending = client!.sources();
+ const closedRequest = expect(pending).rejects.toMatchObject({ name: "NativeRequestError", reason: "disconnected", operation: "list-sources" });
sockets[0]!.emitUnexpectedClose();
sockets[0]!.emitUnexpectedClose();
expect(unexpected).toHaveBeenCalledOnce();
+ await closedRequest;
+ await expect(client!.sources()).rejects.toMatchObject({ reason: "unavailable", operation: "list-sources" });
const cleanClient = await NativeClient.connect();
expect(cleanClient).not.toBeNull();
diff --git a/tests/native-viewer-peer.test.ts b/tests/native-viewer-peer.test.ts
index 0e1e42d1..105af08a 100644
--- a/tests/native-viewer-peer.test.ts
+++ b/tests/native-viewer-peer.test.ts
@@ -250,19 +250,63 @@ it("admits one active sending H264 or VP8 video section, not unrelated SDP codec
`m=video ${port} UDP/TLS/RTP/SAVPF ${payload}`,
`a=${direction}`,
`a=rtpmap:96 ${codec}/90000`,
+ "a=fmtp:96 profile-level-id=42e01f;packetization-mode=1",
"",
].join("\r\n");
expect(offerHasNativeVideoCodec(video("H264"))).toBe(true);
expect(offerHasNativeVideoCodec(video("VP8"))).toBe(true);
expect(offerHasNativeVideoCodec(video("VP8", "sendrecv"))).toBe(true);
+ expect(offerHasNativeVideoCodec("a=group:BUNDLE 0\r\n" +
+ video("VP8", "sendonly", 0) + "a=bundle-only\r\na=mid:0\r\n")).toBe(true);
+ expect(offerHasNativeVideoCodec("m=video 9 UDP/TLS/RTP/SAVPF 96 97\r\n" +
+ "a=sendonly\r\na=rtpmap:96 H264/90000\r\na=rtpmap:97 VP8/90000\r\n")).toBe(true);
for (const offer of [
video("VP8", "recvonly"), video("VP8", "inactive"),
video("VP8", "sendonly", 0), video("VP8", "sendonly", 9, 97),
+ video("VP8", "sendonly", 0) + "a=bundle-only\r\na=mid:0\r\n",
video("VP9"), video("H264") + video("VP8"),
"m=audio 9 UDP/TLS/RTP/SAVPF 96\r\na=rtpmap:96 VP8/90000\r\n",
]) expect(offerHasNativeVideoCodec(offer)).toBe(false);
});
+it.each([
+ ["42e01f", "1", true], ["42c01f", "1", true],
+ ["4de01f", "1", true], ["58c01f", "1", true],
+ ["42e00b", "1", true], ["42e033", "1", true], ["42e034", "1", false],
+ ["4d001f", "1", false], ["64001f", "1", false], ["42001f", "1", false],
+ ["42e11f", "1", false], ["42e035", "1", false], ["42e03c", "1", false],
+ ["42e01f=invalid", "1", false],
+ ["", "1", false], ["42e01f", "0", false], ["42e01f", "", false],
+])("matches Native H264 forwarding admission: profile=%s, packetization=%s", (profile, mode, supported) => {
+ const offer = "m=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\n" +
+ "a=rtpmap:96 H264/90000\r\n" +
+ `a=fmtp:96 profile-level-id=${profile};packetization-mode=${mode}\r\n`;
+ expect(offerHasNativeVideoCodec(offer)).toBe(supported);
+});
+
+it("sends an unsupported Native format straight to the Browser without failing the App", async () => {
+ vi.stubGlobal("MediaStream", class { getTracks() { return []; } });
+ const browserSignal = vi.spyOn(ViewerPeer.prototype, "acceptSignal").mockResolvedValue();
+ const acquire = vi.fn(async () => null);
+ const unavailable = vi.fn();
+ const restart = vi.fn(() => true);
+ const peer = new NativeCapableViewerPeer({ iceServers: [] }, {
+ sendSignal: () => true, sendRestartRequest: restart,
+ onStream: () => undefined, onUpdate: () => undefined,
+ }, {}, acquire, unavailable, "session", 2);
+ const offer: SignalPayload = { kind: "description", connectionId: "current", description: {
+ type: "offer", sdp: "m=video 9 UDP/TLS/RTP/SAVPF 96\r\na=sendonly\r\n" +
+ "a=rtpmap:96 H264/90000\r\na=fmtp:96 profile-level-id=64001f;packetization-mode=1\r\n",
+ }};
+ try {
+ await peer.acceptSignal("parent", offer);
+ expect(browserSignal).toHaveBeenCalledExactlyOnceWith("parent", offer);
+ expect(acquire).not.toHaveBeenCalled();
+ expect(unavailable).not.toHaveBeenCalled();
+ expect(restart).not.toHaveBeenCalled();
+ } finally { peer.dispose(); }
+});
+
it("does not create a browser backend after deferred native discovery is disposed", async () => {
let resolveClient: (value: null) => void = () => undefined;
const nativeClient = new Promise<null>((resolve) => {
diff --git a/tests/video-codec-preflight.test.ts b/tests/video-codec-preflight.test.ts
index 2498e521..17dbfe30 100644
--- a/tests/video-codec-preflight.test.ts
+++ b/tests/video-codec-preflight.test.ts
@@ -166,7 +166,7 @@ describe("codec probe lifetime", () => {
vi.useRealTimers();
});
- function fixture(blocked = "", failReceiver = false) {
+ function fixture(blocked = "", failReceiver = false, linkSource = true) {
vi.useFakeTimers();
vi.stubGlobal("window", globalThis);
let resolve!: () => void;
@@ -208,9 +208,9 @@ describe("codec probe lifetime", () => {
const frames = timestamp * 30 / 1_000;
return new Map([
["out", { id: "out", type: "outbound-rtp", kind: "video", timestamp,
- codecId: "codec", mediaSourceId: "source", framesEncoded: frames }],
+ codecId: "codec", mediaSourceId: linkSource ? "source" : undefined, framesEncoded: frames }],
["codec", { type: "codec", mimeType: "video/H264" }],
- ["source", { id: "source", type: "media-source", frames }],
+ ["source", { id: "source", type: "media-source", kind: "video", frames }],
]);
},
},
@@ -278,8 +278,8 @@ describe("codec probe lifetime", () => {
expect(vi.getTimerCount()).toBe(0);
});
- it("keeps a proved H264 result and retires the budget", async () => {
- const f = fixture();
+ it.each([true, false])("keeps proved H264 and retires the budget (source link: %s)", async (linkSource) => {
+ const f = fixture("", false, linkSource);
const run = preferredVideoCodecForTrack(f.source, QUALITY_PROFILES["1080p30"]);
await vi.advanceTimersByTimeAsync(2_000);
await expect(run).resolves.toBe("h264");
diff --git a/tests/video-codec.test.ts b/tests/video-codec.test.ts
new file mode 100644
index 00000000..014d3bab
--- /dev/null
+++ b/tests/video-codec.test.ts
@@ -0,0 +1,29 @@
+import { expect, it } from "vitest";
+import { normalizeVideoOfferSdp } from "../src/client/webrtc/video-codec";
+
+it.each(["\r\n", "\n"])("removes orphan codec attributes within each offered video section (%j)", newline => {
+ const lines = [
+ "v=0", "a=x-session:keep",
+ "m=video 9 UDP/TLS/RTP/SAVPF 120 124", "a=mid:0", "a=ice-ufrag:unchanged",
+ "a=rtpmap:120 VP8/90000", "a=rtpmap:124 rtx/90000", "a=fmtp:124 apt=120",
+ "a=rtcp-fb:120 nack", "a=rtcp-fb:* transport-cc", "a=x-video:keep",
+ "a=fmtp:126 profile-level-id=42e01f", "a=rtcp-fb:126 nack pli",
+ "m=video 9 UDP/TLS/RTP/SAVPF 126", "a=mid:1", "a=rtpmap:126 H264/90000",
+ "a=fmtp:126 profile-level-id=42e01f;packetization-mode=1", "a=rtcp-fb:126 nack",
+ "a=rtcp-fb:120 nack pli",
+ "m=audio 9 UDP/TLS/RTP/SAVPF 0", "a=fmtp:0 keep-audio",
+ "m=application 9 UDP/DTLS/SCTP webrtc-datachannel", "a=sctp-port:5000", "",
+ ];
+ const omitted = new Set([11, 12, 18]);
+ const expected = lines.filter((_line, index) => !omitted.has(index)).join(newline);
+ expect(normalizeVideoOfferSdp(lines.join(newline))).toBe(expected);
+ expect(normalizeVideoOfferSdp(expected)).toBe(expected);
+});
+
+it("preserves valid codec parameters, feedback and opaque data without reserializing SDP", () => {
+ const sdp = "v=0\r\nm=video 9 UDP/TLS/RTP/SAVPF 96 97\r\n" +
+ "a=rtpmap:96 H264/90000\r\na=fmtp:96 profile-level-id=42e034;packetization-mode=1\r\n" +
+ "a=rtpmap:97 rtx/90000\r\na=fmtp:97 apt=96\r\na=rtcp-fb:96 nack\r\n" +
+ "a=rtcp-fb:* transport-cc\r\na=unknown:exact spacing and values\r\n";
+ expect(normalizeVideoOfferSdp(sdp)).toBe(sdp);
+});