【免费下载链接】SideScreen项目地址https://gitcode.com/gh_mirrors/si/SideScreen点击查看免费下载SideScreen 是一款把 Mac 屏幕镜像到 Android 平板的开源副屏工具它最精妙的部分藏在协议层H.265HEVC优先、H.264 自动回退的双编码协商以及客户端主动上报解码能力上限的机制。本文带你从连接握手到逐帧协商完整看懂这套低配设备也能流畅镜像的设计思路无需任何 Swift/Kotlin 基础。一、为什么需要协商而不是直接开播Mac 端默认用 H.265 编码屏幕画面压缩效率最高、码率最省但现实中的 Android 设备千差万别部分平板没有硬件 HEVC 解码器只能用 H.264有些芯片虚报 HEVC 支持——解码器能启动却永远不输出画面结果就是一块黑屏解码能力有每秒宏块数预算芯片标称支持 4K但只够解 4K15fps跑 60fps 会卡死。如果 Mac 不加判断地按 H.265 高分辨率硬推低配设备要么打不开、要么黑屏。所以 SideScreen 在开播前做了一轮解码能力协商decoder capability negotiation客户端先自我体检、再上报预算Mac 据此决定用什么编码、多大分辨率开播。下面按时间顺序拆解全过程。二、第 1 步认证握手Handshake无线连接建立后双方先完成认证。协议用 4 字节魔数magic number标识消息方向定义在 HandshakeCodec.swift 与 AuthHandshake.kt 中魔数方向含义SSWA客户端 → Mac认证请求[魔数 4][令牌 32][名称长度 1][名称 N]SSWRMac → 客户端认证响应[魔数 4][状态 1]SSPC客户端 → Mac配对码请求8 位数字配对码SSPRMac → 客户端配对码响应成功时携带 32 字节令牌一个容易被忽略的细节SSPC 请求和 SSWA 请求的固定前缀都是 37 字节。这样老版本 Mac 读到完整前缀后会发现魔数不认识明确回答invalidMagic而不是在短读上卡死——客户端就能提示用户请升级 Mac 应用而不是无限等待。三、第 2 步客户端自我体检——什么才算可用的 HEVC 解码器体检逻辑全部在 CodecCapabilities.kt 中。它遍历系统的MediaCodecList用一套严格的过滤器isUsableHardwareDecoder判断有没有可用的硬件 HEVC 解码器。注意有不等于能用有两类设备被刻意排除、强制走 H.264纯软解 HEVC名称以c2.android./omx.google.开头的谷歌软解码器速度远达不到实时镜像要求厂商坏硬件解码器展锐Unisoc/Spreadtrum平台的omx.sprd.hevc、c2.sprd.*——解码器能配置、能启动却从不向 Surface 输出任何帧用户看到的就是一块黑屏。两种情况这些设备都有正常的硬件 H.264 解码器所以 H.264 才是可靠路径。还有个失败即放行fail open设计如果探测本身抛异常就默认有 HEVC保持旧版行为宁可走老路也不让协商环节把连接搞断。体检结果浓缩为一个属性streamMime——有硬件 HEVC 就报HEVC否则报AVCH.264后续所有上报都基于它。四、第 3 步客户端连发能力消息协议的精髓连接成功后客户端在发第一帧之前按固定顺序发送几条能力声明消息StreamClient.kt类型名称载荷作用9clientAvcOnly无我没有 HEVC 解码器请改用 H.26411clientDecoderLimits4 字节上报自己最大可解码尺寸宽×高12clientSupportsDesktopGeometry无我能正确区分桌面尺寸和实际推流尺寸8clientSupportsFrameMetadata无声明支持带时间戳的视频帧顺序有讲究9和11必须先于8发出。因为 Mac 收到8后立即完成协议启动、锁定编码参数——如果 AV-only 声明来得晚Mac 就会用 H.265 开播了协商作废。clientDecoderLimits的 4 字节载荷也藏着巧思每字节的最高位恒为 1。老版本 Mac 遇到不认识的消息类型时是逐字节跳过的最高位为 1 的载荷字节永远不会和真实的消息类型值都不超过 13撞车于是老 Mac 能安全跳过整个载荷而不破坏后续字节对齐——新消息对旧主机零伤害。上报的尺寸本身也是算过账的maxStreamSize会以 60fps 为参考帧率REFERENCE_FPS用areSizeAndRateSupported检查宏块预算从面板尺寸开始按 0.95 倍逐步缩小最多 40 轮直到芯片真解得动。它和标称最大尺寸nominalMaxDecodeSize刻意分成两个概念——后者只读size上限会高估芯片能力仅作最后兜底。五、第 4 步Mac 的决策——H.265 优先H.264 回退Mac 端StreamingServer.swift收到连接后并不立刻开播而是留出一个100 毫秒窗口新客户端会在窗口内把9/11/12声明发齐Mac 据此完成协商老客户端什么都不发它压根不知道这些消息100ms 后 Mac 自动回退到旧版协议开播。这就是协商但不强制的核心协议按能力渐进增强新旧版本可以互通。窗口结束、协议定稿时finishProtocolStartupMac 做三件事定编码clientIsAvcOnly为真则h264否则hevc回执仅对发过9的客户端回一条10codecSelected消息1 字节载荷wireId0HEVC1H.264定义于 CodecLimits.swift。之所以只回给声明过的客户端是因为老客户端遇到未知消息类型会直接断开——绝不能主动打扰定尺寸并开播先回调onCodecNegotiated切换编码器VideoEncoder.swift 据此在kVTProfileLevel_HEVC_Main和kVTProfileLevel_H264之间二选一再发送displayConfig告诉客户端最终推流尺寸。如果11的尺寸消息因为网络慢姗姗来迟连接已开播Mac 不会让它白等下一轮连接——当场按新上限重新计算尺寸并补发displayConfig实现迟到也能生效。六、尺寸怎么算解码预算 16 像素对齐最终推流分辨率由 ScreenCapture.swift 的encodeSize决定逻辑分三层工具函数在 CodecLimits.swift客户端报过上限最常见路径上限是芯片在 60fps 下的面积预算。如果 Mac 实际以 120/144fps 推流帧数翻倍、预算不变scaleLimit就把每边乘上 √(60/fps) 缩小面积clampToClientLimit还会自动处理横竖屏方向差异——预算本质是宏块面积跟哪边长无关没报上限 走 H.264套用保守下限 1920×1088clampForAvc——AVC-only 设备多为低端平板真实能力不低于 H.264 Level 4.x没报上限 走 HEVC按物理像素原尺寸推。所有结果都会向下取整到16 的倍数——这是编码宏块对齐要求不对齐会导致解码失败或花屏。单元测试 CodecLimitsTests.swift 覆盖了横屏、竖屏、超宽屏、旋转场景验证这套 clamp 逻辑的正确性。这套设计让 HiDPI 桌面在平板上真正受益macOS 按 2x 渲染Mac 端先降采样到客户端解得动的上限再编码比直接抓 1x 画面更清晰同时保证解码不超预算。七、客户端的收尾重建解码器与降级提示协商结果回到客户端后的处理见 MainActivity.kt有两个关键防御解码器 mime 必须与协商结果一致onStreamCodecSelected收到codecSelected后检查——若当前解码器是 HEVC 而流是 H.264立即释放并重建解码器。否则会出现H.264 帧喂给 HEVC 解码器的死局解码器不报错、不出帧永久黑屏AVC-only 设备延迟建解码器在codecSelected到达前不创建解码器避免先建一个 HEVC 解码器又要拆掉的浪费。万一遇到老版本 Mac不支持协商、收不到codecSelected客户端不会静默黑屏而是明确提示This device has no HEVC decoder. Update the SideScreen Mac app to enable H.264 support.——把该升级哪一端直接告诉用户这是排障体验上很加分的一点。八、一图流总结完整协商时序Android 客户端 Mac 主机 | SSWA [令牌设备名] ──────────── | 认证握手或 SSPC 配对码 | ────────────── SSWR [ok] | | 9 clientAvcOnly可选 | | 11 clientDecoderLimits可选── | | 12 desktopGeometry ──────────── | | 8 frameMetadata ────────────── | 100ms 窗口结束协议定稿 | | 定编码 定尺寸clamp/预算 | ──── 10 codecSelected仅AVC | | ────────── 1 displayConfig | | ═══════ 视频帧H.265 或 H.264════ |九、值得借鉴的三个设计哲学能力声明优于能力探测Mac 从不猜设备水平一切以上报为准且上报失败就回退保守默认值渐进增强双向兼容新消息只回给 opt-in 的客户端载荷字节最高位恒为 1新旧请求固定前缀等长——老版本不会卡死、不会错位、不会误断连黑屏是第一要防范的故障从坏硬件 HEVC 黑名单、解码器 mime 校验到老 Mac 显式提示整条链路都在消灭静默失败。十、延伸阅读核心源码路径模块路径握手与配对码编解码HandshakeCodec.swift · AuthHandshake.kt服务端协议与协商决策StreamingServer.swift编码格式与尺寸预算CodecLimits.swift · VideoEncoder.swift推流尺寸计算ScreenCapture.swift解码器体检与上限探测CodecCapabilities.kt客户端消息收发StreamClient.kt · VideoDecoder.kt协商处理与降级提示MainActivity.kt尺寸算法单元测试CodecLimitsTests.swift理解了这个协商机制你就抓住了 SideScreen 兼容从旗舰平板到老款低价设备的关键——不是把所有设备拉满而是让每台设备跑在自己最舒服的档位上。赞分享【免费下载链接】SideScreen项目地址https://gitcode.com/gh_mirrors/si/SideScreen点击查看免费下载相关推荐NanoKVM视频流技术解析MJPEG、H.264和H.265编码对比NanoKVM视频流技术解析MJPEG、H.264和H.265编码对比 想要打造高效稳定的远程KVM解决方案NanoKVM作为一款经济实惠的多功能RISC物联网嵌入式音视频后端untrunc代码架构深度剖析理解AVC/H.264与HEVC/H.265编解码器支持untrunc代码架构深度剖析理解AVC/H.264与HEVC/H.265编解码器支持 untrunc是一个专业的视频修复工具专门用于恢复损坏的MP4、MO音视频视频处理深入理解PettingZoo AEC与Parallel API选择最适合你项目的接口深入理解PettingZoo AEC与Parallel API选择最适合你项目的接口 PettingZoo作为多智能体强化学习环境的API标准提供了两种核心人工智能深度学习机器学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
