简介基于Python的iOS屏幕录制工具通过USB连接真实iPhone/iPad设备调用Apple Quicktime协议实现高帧率30~60fps、高画质、低延迟200ms的屏幕共享与音视频采集适合移动端开发调试、自动化测试、操作录屏等场景需要读者具备一定的Python环境配置基础。压缩包共24个文件主体为19个Python脚本另含cfg配置、txt说明、md文档、sh脚本及license授权文件整体仅23KB。项目通过pip安装依赖即可使用支持将H.264视频流通过UDP转发至VLC实时播放也可直接录制h264/wav文件内置了同步、异步、核心媒体处理等模块便于二次开发。资源目前已有452人学习对于希望低成本搭建iOS设备录屏或研究Quicktime协议实现细节的开发者来说是一份轻量而完整的参考实现兼具实用工具与入门代码的双重价值。 第一次被丢到一台只有 Windows 的电脑前面却被要求录制 iOS 真机屏幕的时候我是有些拒绝的。后来我把 ios-screen-record 这个基于 Python 的 Apple Quicktime 协议实现跑通才发现它正好补上了这个缺口不需要 Mac不需要越狱一台普通 PC、一根数据线就能拿到 iOS 设备上正在渲染的视频和音频。这篇文章会从协议原理开始讲再给出一套能直接抄作业的实操流程适合正在搞 iOS 自动化测试、远程演示、Bug 复现录制的朋友参考。1. 把需求拆干净为什么偏偏是 QuickTime 方案1.1 为什么不用 AirPlay 和模拟器四条路线的踩坑经验想拿到 iOS 真实设备的画面市面上大概有四条路。第一条是 AirPlay 投屏把 iPhone 画面镜像到 Apple TV 或其他接收端但你要额外准备接收盒子而且无线投屏的延迟、花屏、音频不同步问题在自动化场景里非常致命。第二条是直接用 Xcode 连接设备可 Xcode 只活在 macOS 上对 Windows 和 Linux 团队来说等于没有。第三条是外接采集卡虽然能拿到原始 HDMI/闪电信号但硬件成本高还要面对 HDCP 这类烦人限制。剩下就是今天说的 QuickTime 方案。macOS 上打开 QuickTime Player用数据线连上 iPhone点击“新建影片录制”就可以实时录制真机画面。实现这套能力靠的是 iOS 设备通过 USB 暴露出的一个屏幕录制服务而 ios-screen-record 就是把这个服务用 Python 重新实现了一遍。它的价值不是“破解”而是把原本只有 QuickTime 播放器能干的事变成了一段可以跑在 CI 机器上的脚本。只要你手头有带 USB 口的电脑就能做同样的事。1.2 Python 在这个方案里真正扮演什么角色很多人一听“协议”两个字就头皮发麻其实这里的协议并没那么玄。Apple Quicktime 协议本质上是一套“服务发现和音视频流传输规则”先弄清设备上有哪些服务再从一个固定端口把编码好的音视频流拉下来。Python 之所以适合做这件事因为它处理 socket、二进制数据、plist 这类东西非常顺手没有 Java/C 那套繁琐的工程框架。我用下来的体会是Python 最大的优势在于“粘合”。真正跑录制时经常要配合 pytest、Appium、FFmpeg 一起工作Python 可以把设备配对、启动录制、自动命名文件、调用 FFmpeg 转码全串起来。而且你不需要懂太多底层网络细节库里已经处理好了 usbmuxd 连接和设备鉴权普通开发者上手成本很低。2. 原理拆解Apple Quicktime 录屏协议到底在传什么2.1 藏在 USB 服务发现背后的三步握手如果你想在 Linux 上徒手实现 QuickTime 录屏就必须理解苹果这套 USB 服务发现流程。iOS 设备通过 USB 连接电脑后电脑端会有一个叫 usbmuxd 的精简进程来管理 USB 通道。一个最简单的调用链是这样客户端先连接 usbmuxd 的 socket接着向设备的 lockdownd 服务发起 plist 格式的请求要求启动某个服务名比如屏幕录制lockdownd 验证通过后返回一个端口号客户端再连上这个端口开始接收二进制流。整个过程很像你去餐厅吃饭usbmuxd 是门口的服务员lockdownd 是负责核对身份的经理屏幕录制服务才是后厨。我们拿着 plist 订单去找服务员经理验过身份后后厨把菜端出来。ios-screen-record 帮我们省掉的正是从“进门”到“坐下”这一路的交涉功夫。如果协议一步出错最常见的表现就是设备半天没反应或者报错说找不到服务这也是后文会提到的排查重灾区。2.2 H.264 与 AAC流里面到底装了什么QuickTime 录制拿到的不像 MP4 那样是一个完整的文件而是一段连续的音视频裸流。iOS 屏幕编码默认走的是 H.264音频走的是 AAC两者交错打包在同一路流里。H.264 的好处是压缩率高对屏幕上的静止文字和 UI 界面尤其友好AAC 则是最常见的音频编码后期封装成 MP4 时基本不用转码。这带来一个实际影响录屏过程一旦中断前面接收到的数据可能因为缺少 mp4 索引而打不开。我的经验是不要直接用 Python 把裸流往文件里塞一定要交给 FFmpeg 做封装。就算录制过程中断FFmpeg 也能通过重建索引的方式把已经收到的 H.264 帧恢复出来。很多新手录了半天发现文件损坏问题就出在这层封装上。3. 实操用 ios-screen-record 录制音频和视频3.1 十分钟跑通第一次录制先说环境准备。这个方案依赖 Python 3.8 以上版本以及 usbmuxd 组件macOS 和 Linux 通常自带Windows 需要单独安装驱动常见做法是使用 Zadig 把 iPhone 的 USB 驱动切换为 WinUSB 兼容驱动否则系统不认识设备。安装好这些后用pip install ios-screen-record拉取依赖再用数据线把 iPhone 连到电脑上。准备就绪后先用设备列表命令确认连接状态idevice_id -l正常情况下会输出一长串 UDID。接着执行录制命令不同版本的库参数略有差异但大致是这个形态python -m ios_screen_record --udid 你的UDID --out screen.mov --audio执行后iPhone 上会同步出现录制中的状态提示。录制期间不要拔出数据线也不要锁屏否则服务会被系统中断。按 CtrlC 结束程序会自动停止录流并生成文件。我第一次跑通的时候只花了不到五分钟比配置 Appium 环境快多了。3.2 几个常用参数与后期封装技巧ios-screen-record 的参数设计并不复杂最常用的是这几个参数作用我的建议--udid指定设备多设备接入时必填避免录错机器--out输出文件路径建议统一放在日期目录方便归档--audio同时录制音频需要系统声音或麦克风时打开--quality画质档位清晰度越高流量越大注意带宽录完拿到的通常是 .mov 或 .h264 裸流我会统一用 FFmpeg 做二次封装顺手压缩到适合上传测试报告的大小ffmpeg -i raw.mov -c:v libx264 -preset fast -crf 23 -c:a aac -b:a 128k final.mp4这里推荐-crf 23属于画质和体积比较均衡的档位。UI 自动化录制不需要原画质压到 1080p 以内能省下不少存储空间也方便附在 Bug 单里发给开发。3.3 一个最小化 Python 复刻骨架如果项目迭代太快、库接口变了或者你想按公司内部流程改造录屏逻辑可以照着下面这个思路写一个最小版本。这不是完整源码而是从协议层面还原的三段式流程足以让你理解库的内部结构。import socket import plistlib import struct def connect_usbmux(): # 连接 usbmuxdmacOS/Linux 使用 unix socketWindows 使用命名管道或 TCP sock socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) sock.connect(/var/run/usbmuxd) return sock def send_plist(sock, payload): body plistlib.dumps(payload) header struct.pack(II, 1, len(body)) sock.sendall(header body) # 1. 先启动 lockdownd 服务拿到屏幕录制服务端口 # 2. 再连接该端口持续读取 H.264/AAC 裸流 # 3. 按时间戳写入文件结束后交给 FFmpeg 封装这段代码省略了鉴权和握手细节但足以说明协议链路usbmuxd 负责找到设备lockdownd 负责开门屏幕录制服务负责吐数据。你完全可以在公司内部做一个自己的封装把抓流、归档、通知测试平台几件事串起来。4. 避坑实录连接与音视频层面的常见问题4.1 连不上设备、配对反复失败的排查我在不同机器上折腾这个方案踩得最多的坑就是“设备明明显示已连接但 idevice_id 查不到”。这通常不是库的问题而是驱动或系统权限的问题。Windows 上先打开设备管理器确认 iPhone 出现在“通用串行总线设备”下而不是“便携设备”里。如果是后者说明 USB 驱动不对需要手动更新为 WinUSB。Linux 上则要检查当前用户是否有权限访问 usbmuxd 的 socket必要时用sudo usermod -a -G plugdev $USER把用户加进设备组。配对失败是另一类高发问题。iPhone 第一次连接电脑时屏幕会弹出“信任此电脑”如果没点USB 服务就无法完成鉴权。处理方式是先拔线重新插上在 iPhone 上点“信任”然后执行idevicepair unpair idevicepair pair如果还不行重启 iPhone 和 usbmuxd 服务通常是最后一道万能药。4.2 只有视频没有音频或者录制中途花屏“画面出来了但没有声音”这个问题我排查过很长时间。最常见的原因是录制命令没加--audio参数屏幕上录麦克风权限的提示被忽略了。iOS 对录音权限管理很严格即使你已经打开了系统声音录制也要去“设置 - 隐私 - 麦克风”里确认当前 App 有录音权限。否则协议已经打开了音频通道但系统拒绝给数据这时候不会报错只会安静地没声音。花屏和文件播放一半就断一般跟 H.264 的关键帧丢失有关。无线干扰、USB 线质量差、设备发热降频都可能造成关键帧丢失导致播放器从中间开始解码时出现大块马赛克。我的建议是尽量用原装 USB 线录制时开启飞行模式关掉后台推送降低系统负载这能明显减少画面异常。4.3 稳定性优化录制开始前的系统设置如果你要跑长时间自动化录制千万不要直接拿测试机就开始。先花半分钟做这几件事打开“设置 - 显示与亮度”把自动锁屏改为永不防止录到一半屏幕熄灭打开“辅助功能 - 动态效果”开启减弱动态效果减少转场动画对 H.264 码率的冲击如果只做 UI 测试建议在“控制中心”手动关掉蓝牙和 Wi-Fi避免网络切换打断 USB 会话。这几步看起来不起眼但对长时间录制很关键。我遇到过连续录制两小时后画面突然停住的情况排查下来就是自动锁屏倒计时被触发。系统层面把干扰因素提前干掉比事后捞日志救文件省心得多。5. 更进一步把录制接进自动化工作流5.1 适配 pytest 和 Appium 的录屏小框架真正把 ios-screen-record 用出价值的地方是把它接进自动化测试链路。我的做法是写一个 pytest fixture在用例开始时调用录制接口用例结束后停止录制并归档文件import pytest import subprocess pytest.fixture def screen_record(): cmd [python, -m, ios_screen_record, --udid, YOUR_UDID, --out, reports/test.mp4, --audio] proc subprocess.Popen(cmd) yield proc.terminate()配合 Appium 做 UI 自动化时这个录制进程和 Appium 会话互不干扰等于给测试用例多了一层“肉眼可回放”的证据。出问题时我能直接点开 MP4 看执行过程比看几百行日志高效得多。也可以再加一步把 MP4 转成 GIF 或缩略图方便直接贴在 Bug 单里。5.2 稳定压倒一切我的设备与协议版本管理经验最后分享一条踩过坑之后总结出来的心得宁可把设备锁定在一个稳定的系统版本上也不要频繁升级 iOS。Apple Quicktime 协议在系统升级后偶尔会有细节调整新的 iOS 大版本可能导致旧版库出现兼容问题。所以我的团队会专门留一台“录制专用机”不装乱七八糟的 App不升级系统只负责跑录屏。另外输出文件的命名和归档要有统一规范我习惯用“用例名时间戳”的格式比如login_check_20250120_143000.mp4避免测试报告里堆满一堆无意义的record.mp4。协议方案可以有很多变体但稳定的环境和规范的输出才是自动化录制能长期跑下去的关键。本文还有配套的精品资源点击获取 告别Mac：用Python和QuickTime协议在Windows上录制iOS真机屏幕
简介基于Python的iOS屏幕录制工具通过USB连接真实iPhone/iPad设备调用Apple Quicktime协议实现高帧率30~60fps、高画质、低延迟200ms的屏幕共享与音视频采集适合移动端开发调试、自动化测试、操作录屏等场景需要读者具备一定的Python环境配置基础。压缩包共24个文件主体为19个Python脚本另含cfg配置、txt说明、md文档、sh脚本及license授权文件整体仅23KB。项目通过pip安装依赖即可使用支持将H.264视频流通过UDP转发至VLC实时播放也可直接录制h264/wav文件内置了同步、异步、核心媒体处理等模块便于二次开发。资源目前已有452人学习对于希望低成本搭建iOS设备录屏或研究Quicktime协议实现细节的开发者来说是一份轻量而完整的参考实现兼具实用工具与入门代码的双重价值。 第一次被丢到一台只有 Windows 的电脑前面却被要求录制 iOS 真机屏幕的时候我是有些拒绝的。后来我把 ios-screen-record 这个基于 Python 的 Apple Quicktime 协议实现跑通才发现它正好补上了这个缺口不需要 Mac不需要越狱一台普通 PC、一根数据线就能拿到 iOS 设备上正在渲染的视频和音频。这篇文章会从协议原理开始讲再给出一套能直接抄作业的实操流程适合正在搞 iOS 自动化测试、远程演示、Bug 复现录制的朋友参考。1. 把需求拆干净为什么偏偏是 QuickTime 方案1.1 为什么不用 AirPlay 和模拟器四条路线的踩坑经验想拿到 iOS 真实设备的画面市面上大概有四条路。第一条是 AirPlay 投屏把 iPhone 画面镜像到 Apple TV 或其他接收端但你要额外准备接收盒子而且无线投屏的延迟、花屏、音频不同步问题在自动化场景里非常致命。第二条是直接用 Xcode 连接设备可 Xcode 只活在 macOS 上对 Windows 和 Linux 团队来说等于没有。第三条是外接采集卡虽然能拿到原始 HDMI/闪电信号但硬件成本高还要面对 HDCP 这类烦人限制。剩下就是今天说的 QuickTime 方案。macOS 上打开 QuickTime Player用数据线连上 iPhone点击“新建影片录制”就可以实时录制真机画面。实现这套能力靠的是 iOS 设备通过 USB 暴露出的一个屏幕录制服务而 ios-screen-record 就是把这个服务用 Python 重新实现了一遍。它的价值不是“破解”而是把原本只有 QuickTime 播放器能干的事变成了一段可以跑在 CI 机器上的脚本。只要你手头有带 USB 口的电脑就能做同样的事。1.2 Python 在这个方案里真正扮演什么角色很多人一听“协议”两个字就头皮发麻其实这里的协议并没那么玄。Apple Quicktime 协议本质上是一套“服务发现和音视频流传输规则”先弄清设备上有哪些服务再从一个固定端口把编码好的音视频流拉下来。Python 之所以适合做这件事因为它处理 socket、二进制数据、plist 这类东西非常顺手没有 Java/C 那套繁琐的工程框架。我用下来的体会是Python 最大的优势在于“粘合”。真正跑录制时经常要配合 pytest、Appium、FFmpeg 一起工作Python 可以把设备配对、启动录制、自动命名文件、调用 FFmpeg 转码全串起来。而且你不需要懂太多底层网络细节库里已经处理好了 usbmuxd 连接和设备鉴权普通开发者上手成本很低。2. 原理拆解Apple Quicktime 录屏协议到底在传什么2.1 藏在 USB 服务发现背后的三步握手如果你想在 Linux 上徒手实现 QuickTime 录屏就必须理解苹果这套 USB 服务发现流程。iOS 设备通过 USB 连接电脑后电脑端会有一个叫 usbmuxd 的精简进程来管理 USB 通道。一个最简单的调用链是这样客户端先连接 usbmuxd 的 socket接着向设备的 lockdownd 服务发起 plist 格式的请求要求启动某个服务名比如屏幕录制lockdownd 验证通过后返回一个端口号客户端再连上这个端口开始接收二进制流。整个过程很像你去餐厅吃饭usbmuxd 是门口的服务员lockdownd 是负责核对身份的经理屏幕录制服务才是后厨。我们拿着 plist 订单去找服务员经理验过身份后后厨把菜端出来。ios-screen-record 帮我们省掉的正是从“进门”到“坐下”这一路的交涉功夫。如果协议一步出错最常见的表现就是设备半天没反应或者报错说找不到服务这也是后文会提到的排查重灾区。2.2 H.264 与 AAC流里面到底装了什么QuickTime 录制拿到的不像 MP4 那样是一个完整的文件而是一段连续的音视频裸流。iOS 屏幕编码默认走的是 H.264音频走的是 AAC两者交错打包在同一路流里。H.264 的好处是压缩率高对屏幕上的静止文字和 UI 界面尤其友好AAC 则是最常见的音频编码后期封装成 MP4 时基本不用转码。这带来一个实际影响录屏过程一旦中断前面接收到的数据可能因为缺少 mp4 索引而打不开。我的经验是不要直接用 Python 把裸流往文件里塞一定要交给 FFmpeg 做封装。就算录制过程中断FFmpeg 也能通过重建索引的方式把已经收到的 H.264 帧恢复出来。很多新手录了半天发现文件损坏问题就出在这层封装上。3. 实操用 ios-screen-record 录制音频和视频3.1 十分钟跑通第一次录制先说环境准备。这个方案依赖 Python 3.8 以上版本以及 usbmuxd 组件macOS 和 Linux 通常自带Windows 需要单独安装驱动常见做法是使用 Zadig 把 iPhone 的 USB 驱动切换为 WinUSB 兼容驱动否则系统不认识设备。安装好这些后用pip install ios-screen-record拉取依赖再用数据线把 iPhone 连到电脑上。准备就绪后先用设备列表命令确认连接状态idevice_id -l正常情况下会输出一长串 UDID。接着执行录制命令不同版本的库参数略有差异但大致是这个形态python -m ios_screen_record --udid 你的UDID --out screen.mov --audio执行后iPhone 上会同步出现录制中的状态提示。录制期间不要拔出数据线也不要锁屏否则服务会被系统中断。按 CtrlC 结束程序会自动停止录流并生成文件。我第一次跑通的时候只花了不到五分钟比配置 Appium 环境快多了。3.2 几个常用参数与后期封装技巧ios-screen-record 的参数设计并不复杂最常用的是这几个参数作用我的建议--udid指定设备多设备接入时必填避免录错机器--out输出文件路径建议统一放在日期目录方便归档--audio同时录制音频需要系统声音或麦克风时打开--quality画质档位清晰度越高流量越大注意带宽录完拿到的通常是 .mov 或 .h264 裸流我会统一用 FFmpeg 做二次封装顺手压缩到适合上传测试报告的大小ffmpeg -i raw.mov -c:v libx264 -preset fast -crf 23 -c:a aac -b:a 128k final.mp4这里推荐-crf 23属于画质和体积比较均衡的档位。UI 自动化录制不需要原画质压到 1080p 以内能省下不少存储空间也方便附在 Bug 单里发给开发。3.3 一个最小化 Python 复刻骨架如果项目迭代太快、库接口变了或者你想按公司内部流程改造录屏逻辑可以照着下面这个思路写一个最小版本。这不是完整源码而是从协议层面还原的三段式流程足以让你理解库的内部结构。import socket import plistlib import struct def connect_usbmux(): # 连接 usbmuxdmacOS/Linux 使用 unix socketWindows 使用命名管道或 TCP sock socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) sock.connect(/var/run/usbmuxd) return sock def send_plist(sock, payload): body plistlib.dumps(payload) header struct.pack(II, 1, len(body)) sock.sendall(header body) # 1. 先启动 lockdownd 服务拿到屏幕录制服务端口 # 2. 再连接该端口持续读取 H.264/AAC 裸流 # 3. 按时间戳写入文件结束后交给 FFmpeg 封装这段代码省略了鉴权和握手细节但足以说明协议链路usbmuxd 负责找到设备lockdownd 负责开门屏幕录制服务负责吐数据。你完全可以在公司内部做一个自己的封装把抓流、归档、通知测试平台几件事串起来。4. 避坑实录连接与音视频层面的常见问题4.1 连不上设备、配对反复失败的排查我在不同机器上折腾这个方案踩得最多的坑就是“设备明明显示已连接但 idevice_id 查不到”。这通常不是库的问题而是驱动或系统权限的问题。Windows 上先打开设备管理器确认 iPhone 出现在“通用串行总线设备”下而不是“便携设备”里。如果是后者说明 USB 驱动不对需要手动更新为 WinUSB。Linux 上则要检查当前用户是否有权限访问 usbmuxd 的 socket必要时用sudo usermod -a -G plugdev $USER把用户加进设备组。配对失败是另一类高发问题。iPhone 第一次连接电脑时屏幕会弹出“信任此电脑”如果没点USB 服务就无法完成鉴权。处理方式是先拔线重新插上在 iPhone 上点“信任”然后执行idevicepair unpair idevicepair pair如果还不行重启 iPhone 和 usbmuxd 服务通常是最后一道万能药。4.2 只有视频没有音频或者录制中途花屏“画面出来了但没有声音”这个问题我排查过很长时间。最常见的原因是录制命令没加--audio参数屏幕上录麦克风权限的提示被忽略了。iOS 对录音权限管理很严格即使你已经打开了系统声音录制也要去“设置 - 隐私 - 麦克风”里确认当前 App 有录音权限。否则协议已经打开了音频通道但系统拒绝给数据这时候不会报错只会安静地没声音。花屏和文件播放一半就断一般跟 H.264 的关键帧丢失有关。无线干扰、USB 线质量差、设备发热降频都可能造成关键帧丢失导致播放器从中间开始解码时出现大块马赛克。我的建议是尽量用原装 USB 线录制时开启飞行模式关掉后台推送降低系统负载这能明显减少画面异常。4.3 稳定性优化录制开始前的系统设置如果你要跑长时间自动化录制千万不要直接拿测试机就开始。先花半分钟做这几件事打开“设置 - 显示与亮度”把自动锁屏改为永不防止录到一半屏幕熄灭打开“辅助功能 - 动态效果”开启减弱动态效果减少转场动画对 H.264 码率的冲击如果只做 UI 测试建议在“控制中心”手动关掉蓝牙和 Wi-Fi避免网络切换打断 USB 会话。这几步看起来不起眼但对长时间录制很关键。我遇到过连续录制两小时后画面突然停住的情况排查下来就是自动锁屏倒计时被触发。系统层面把干扰因素提前干掉比事后捞日志救文件省心得多。5. 更进一步把录制接进自动化工作流5.1 适配 pytest 和 Appium 的录屏小框架真正把 ios-screen-record 用出价值的地方是把它接进自动化测试链路。我的做法是写一个 pytest fixture在用例开始时调用录制接口用例结束后停止录制并归档文件import pytest import subprocess pytest.fixture def screen_record(): cmd [python, -m, ios_screen_record, --udid, YOUR_UDID, --out, reports/test.mp4, --audio] proc subprocess.Popen(cmd) yield proc.terminate()配合 Appium 做 UI 自动化时这个录制进程和 Appium 会话互不干扰等于给测试用例多了一层“肉眼可回放”的证据。出问题时我能直接点开 MP4 看执行过程比看几百行日志高效得多。也可以再加一步把 MP4 转成 GIF 或缩略图方便直接贴在 Bug 单里。5.2 稳定压倒一切我的设备与协议版本管理经验最后分享一条踩过坑之后总结出来的心得宁可把设备锁定在一个稳定的系统版本上也不要频繁升级 iOS。Apple Quicktime 协议在系统升级后偶尔会有细节调整新的 iOS 大版本可能导致旧版库出现兼容问题。所以我的团队会专门留一台“录制专用机”不装乱七八糟的 App不升级系统只负责跑录屏。另外输出文件的命名和归档要有统一规范我习惯用“用例名时间戳”的格式比如login_check_20250120_143000.mp4避免测试报告里堆满一堆无意义的record.mp4。协议方案可以有很多变体但稳定的环境和规范的输出才是自动化录制能长期跑下去的关键。本文还有配套的精品资源点击获取