feat!: expand media controls and simplify App connections

[TNTcraftHIM]

Problem and outcome / 问题与结果

Piik's media settings were coupled to a small preset list, and using native App capture on a Site required a separate launcher mode. This release separates numeric media requests from presets and bounded runtime admission, remembers successfully applied settings, and lets a running App serve an explicitly approved Site independently of Local/public room startup.

The same phase repairs confirmed capture-retirement, ICE discovery, media-recovery and storage failures. P2P-first routing, one room authority and the existing Browser/Native media owners remain. This phase targets v2.0.0 with incompatible Web/App contracts. The owner authorized publication after final acceptance; the verified package and deployment records own delivery completion.

Release notes

中文

Piik 2.0 扩展了画质设置，简化了 App 与站点的连接，并集中修复采集和断线恢复问题。本次升级调整了通信协议，App 与所用站点需要一起升级。

新功能与改进

• 自定义画面设置： 保留三档推荐预设，支持填写分辨率上限、1–240 帧的帧率上限和 0.1–240 Mbps 的视频码率上限。滑动条沿用常用范围，更高数值可直接填写并显示为“自定义”。帧率范围随画幅变化，可请求 1080p240、1440p144、4K60 和超宽画面；输出保留来源比例。
• 自定义音频质量： 在原有三档音频预设之外，可填写 6–320 kbps 的来源音频码率上限。
• 双端 App 协同连接： 启用增强 NAT 穿透后，适用的重试可协调双方 App 准备 UDP 连接；首次连接仍走普通 ICE，不适用时继续现有流程。已通过受控网络验证，实际连通性仍取决于双方网络。
• 记住分享设置： 下次打开时恢复已应用的画面与音频质量。仅用浏览器时按站点保存；通过新版 App 使用时，更换临时公网邀请网址也能保留设置。
• 更直接地连接 App： 启动页提供本地房间和公网邀请，首次默认选择公网邀请。使用已有站点时，保持 App 运行，在站点点击 App 并确认授权即可。App 打开的本地房主页自动获得授权，站点按钮会显示 App 就绪状态。启动页可查看或取消授权；从另一个站点连接并批准，会替换原授权。
• 置顶聊天窗口： 支持的桌面浏览器可将聊天移入独立置顶窗口，保留当前消息、草稿和阅读位置；关闭窗口后回到原页面。

修复

• 连接与恢复： 完善备用 STUN 与 NAT 采样信息的处理；重新收集 ICE 候选时刷新网卡地址。修正观众重连的机会计数、本机媒体连接恢复，以及恢复后遗留的发送队列和带宽统计问题。保留视频编码对应的标准重传能力，改善网络地址变化后的画面恢复。
• 采集稳定性： 修正 Windows 停止采集或预览时的异步资源释放问题，保留采集边框偏好，更快跳过无法正常输出的编码器。采集与应用音频能力按实际接口探测，不再按 Windows 版本号排除；修正 Linux Portal 来源识别和早期采集失败通知，改善摄像头与原生采集的画面比例处理。
• 状态与清理： 房间失效时及时释放 App 连接和待完成的选源请求；本地或公网房间启动失败时，App 保持待机并保留其他已授权站点的连接；公网邀请启动失败保留底层错误。修正启动页旧查询覆盖新设置的问题，并限制原生连接准备的待完成任务。SFU 诊断区分房主发布和观众接收状态。
• 其他维护： 收到尚不支持的表情时跳过该效果；修正 SQLite 写入失败后的事务恢复。Gitee 镜像可独立重试，官网交互、指南和依赖同步更新。App 连接失败时提供重试与下载入口；统一选源设置与自定义数值的反馈。减少重复的随机短语，仅在持续等待时定时轮换。

升级须知

2.0 与 1.x 不能混用。 自建站点请更新 Server 和连接该站点的 App，并刷新所有分享与观看页面。本地房间或公网邀请用户请停止分享、关闭旧 App，完整解压新版程序包后重新发送邀请链接。

本次不变更房间数据库结构。重启会中断正在进行的分享；麦克风、采集权限和设备选择不会自动恢复。4K60 等设置是输出上限，实际清晰度与帧率取决于来源、设备和网络。macOS/Linux 采集及部分移动设备仍需更多实机反馈。

English

Piik 2.0 adds more control over sharing quality, simplifies connecting the App to a Site, and fixes capture and connection-recovery failures. The communication contracts change in this release: update the App and its Site together.

Highlights

• Custom picture settings: Keep the three recommended presets or enter a resolution ceiling, a 1–240 fps limit and a 0.1–240 Mbps video bitrate limit. Sliders retain their familiar ranges; higher entered values are clearly marked as custom. Frame-rate limits depend on picture size, admitting requests such as 1080p240, 1440p144, 4K60 and ultrawide pictures while preserving source proportions.
• Custom audio quality: Enter a 6–320 kbps source-audio bitrate limit alongside the three existing audio presets.
• Coordinated App connections: With enhanced NAT traversal enabled, eligible retries can coordinate UDP preparation between two Apps. The first attempt remains ordinary ICE, and ineligible preparation continues through the existing path. Controlled network checks pass; real-world connectivity still depends on both networks.
• Remember sharing settings: Restore successfully applied picture and audio quality next time. Browser-only use saves settings per site; an updated App can retain them across changing temporary public-invitation addresses.
• Connect the App from a Site: The launcher offers Local room and Public invite, with Public invite selected on first use. For an existing Site, keep the App running, click App on the Site and confirm its authorization. Host pages opened locally by App are authorized automatically, and the Site button reflects verified App readiness. View or revoke approval in the launcher. Connecting and approving another Site replaces the previous approval.
• Always-on-top chat: Supported desktop browsers can move chat into a separate always-on-top window while retaining messages, drafts and reading position. Closing the window returns chat to the page.

Fixes

• Connections and recovery: Improve fallback STUN discovery and NAT survey handling, and refresh interface addresses during ICE gathering. Fix Viewer recovery-opportunity accounting, local media-connection recovery, stale send queues and bandwidth accounting after recovery. Preserve standard video retransmission when selecting a codec to improve picture recovery after network-address changes.
• Capture stability: Fix asynchronous Windows resource retirement after capture or preview ends, retain the capture-border preference, and reject non-performing encoder candidates earlier. Detect capture and process-audio support through actual APIs rather than Windows-version gates. Correct Linux Portal target identification and early capture-failure delivery; improve source-aspect handling for camera and native capture.
• State and cleanup: Release App connections and pending source selection when room authority ends. Keep the App on standby and preserve other authorized Site connections when interactive Local/public room startup fails. Retain underlying public-invitation startup errors. Prevent stale launcher reads from replacing newer settings, bound pending native connection-preparation work, and distinguish Host publication from Viewer reception in SFU diagnostics.
• Maintenance: Skip unsupported incoming reaction effects, recover SQLite transactions after write failures, and retry Gitee mirroring independently. Update website interactions, guides and dependencies; clarify App connection recovery, source-selection settings and custom-value feedback. Reduce repeated playful captions, with timed rotation reserved for ongoing waits.

Upgrading

2.0 and 1.x cannot be mixed. For a hosted Site, update its Server and connected Apps, then refresh every Host and Viewer page. For Local rooms or Public invites, stop sharing, close the old App, extract the complete new package and send a fresh invitation.

The room database schema is unchanged. Restarting interrupts active shares; microphone activation, capture permission and device selection are not restored automatically. Settings such as 4K60 are output ceilings: actual resolution and frame rate depend on the source, device and network. macOS/Linux capture and some mobile devices still need more physical-device feedback.

Verification / 验证

• Product candidate: 24a28738241b9012c0476386356a515aab21f1a5, built as v2.0.0. Final full candidate CI covers core validation, vulnerabilities, races, five App packages and both Server/container targets without publishing. Later commits extend race coverage, correct the capture test fixture's inherited Go race-exit delay, and update documentation/staged website screenshots; shipped product code is unchanged. Additional control/loopback race checks use that updated collector. Product shutdown deadlines and test assertions are unchanged.
• Local Web acceptance passes 91 files / 1,612 tests, type checking and production build. Full Go/native checks, Windows capture compilation, five-repeat control regressions, website/documentation build and repository checks pass. Existing documentation-size and bundle-size warnings remain visible.
• The Windows candidate's original descriptor, revision and SHA-256 are checked before extraction and packaged Local/control acceptance. All candidate packages pass the release publisher's read-only identity/checksum verification.
• Serial Windows native H.264 Host acceptance passes live/paused/custom/4K settings, background/source recovery and stop/re-share. VP8 two-room SFU and H.264 SFU-only checks pass live quality/audio changes, subscription/page-reload recovery and retirement; stopping one room preserves the other room's media. Browser-to-App fanout and App-exit fallback also pass. Gates clean their processes, profiles and listeners. These checks do not establish sustained game/4K performance.
• The final network run passes 37 cases and six negative controls, with 32 actual media outcomes and five unavailable observations. It covers all Browser/App pairings, IPv6, remapping, STUN backup, outages, quality recovery, healthy siblings and SFU policies. Sequential-NAT App/App preparation delivers media; a mixed sequential case also connects in this run, without a claim of deterministic benefit. Fault controls reject absent faults/frozen video and verify cancellation/cleanup. No public success percentage is inferred.
• Twenty Viewer topology acceptance delivers increasing decoded frames to all Viewers, preserves the two-copy bound and recovers from relay loss. Invitation privacy checks find no grant leakage in requests, cookies, persistent storage or logs. Both are bounded synthetic-source checks, not public-network endurance.
• Current UI checks cover Chinese/English/visual, both themes and 320/360/768/1366-pixel layouts, numeric limits, source selection, App approval/revocation, architecture downloads and reader navigation. Chat/PiP retains draft/history/scroll and returns to the page on close; retirement and refused opening clean up. Real Host/Viewer UI chat continues after capture stops and while the Host is absent. Film controls, mute/seek/end/replay, mobile containment and pointer-close unloading pass. README stills and the staged launcher now use current navigation. Scoped axe checks report no violations; contrast and physical assistive-technology coverage are not certified.
• Physical macOS/Linux capture, limited decoders, mixed HDR displays, mobile permissions and sustained game/4K use retain their evidence limits. Unmatched field reports remain open. Gitee activation and public-domain checks are publication postflight; original v1.9.2 artifact/mirror recovery already passed without remote writes.

Boundaries and contributor credit / 边界与贡献

The candidate uses Browser/server v24 and Native control v10; capture v7 and SQLite schema 2 are unchanged. Numeric wire values remain separate from codec/allocation admission. H.264/VP8, framework-owned adaptation and automatic P2P-first routing remain; this candidate adds neither codecs, room voice, end-to-end HDR, surround audio nor Magicsock.

Local controls confirm specific repairs, not the causes of unmatched user reports or a measured increase in NAT success rate. The STUN report in #471 remains subject to paired endpoint/network evidence. Gitee's separate workflow activation still needs post-merge verification; its original-artifact and anonymous-download path has passed against v1.9.2.

The Linux Portal fix from @AkazaAkali in #470 is incorporated with original commit authorship and the co-author trailer below. #462 and #469 propose higher audio rates and 4K; neither patch is merged. Their preset-expansion implementation is superseded by the independently established numeric-media contract, so overlapping functionality alone does not warrant merging or co-authorship. #475 identifies the Linux desktop entry’s missing terminal controls; that defect is independently corrected without accepting tray or Browser-owned process-exit additions. The settings request in #460 is implemented; issue/PR closure remains part of release follow-up.

Co-authored-by: AkazaAkalin 478080766@qq.com