简介面向 iOS 直播开发者的 RTMP 推流 SDK 资源对应 Pili 直播 SDK 的 PLCameraStreamingKit 老版本内置采集模块支持 H.264/AAC 编码与硬编软编切换并具备美颜、背景音乐、水印等直播常用能力且提供丰富的数据与状态回调方便按业务定制。压缩包共 594 个文件、约 4.97MB以 h 头文件、m/mm 源码、md 说明文档为主体另有静态库 a、工程配置、脚本及资源文件等整体结构清晰便于按模块查阅和集成。目前已有 641 人浏览学习。资源既包含可直接链接的静态库也包含完整源码适合希望深入研究推流实现、基于回调定制功能或排查编码集成问题的中高级 iOS 工程师是一份可运行的参考实现。对于需要维护旧版推流功能或深入理解推流细节的团队这套源码能提供直接参考。1. 为什么 iOS 推流选 RTMP不只是延迟低而是生态太成熟做 iOS 直播推流第一反应就是“用 RTMP 还是 WebRTC”。我的结论比较直接如果你做的是单主播向 CDN 分发、观众端用 HLS/FLV 播放的常规直播RTMP 是当前 iOS 上集成成本最低、踩坑资料最全的方案。WebRTC 强在双向低延迟但服务器要自建、信令要自己维护、客户端还要处理 ICE 穿透一个推流 SDK 根本装不下HLS 延迟太高不适合连麦互动。而 RTMP 走 TCP没有 UDP 那套丢包重传的玄学问题CDN 厂商的接入文档基本都是按 RTMP 写的你只要把流推到指定地址剩下的切片、分发、多码率转码都有人帮你做。这个 SDK 的价值就是把采集、编码、封包、推流这一整条链路封装成一个能被业务方快速集成的黑匣子让你不用从 VideoToolbox 和 RTMP 握手协议写起。2. RTMP 推流 SDK 的内部构成采集、编码、协议栈是怎么协作的拿到一个 iOS 推流 SDK先别急着拖进工程。你要清楚它内部至少有三层采集层负责把摄像头的图像和麦克风的声音变成原始的 PCM / BGRA 数据编码层负责把原始数据压成 H.264 和 AAC协议层负责把编码后的帧按 RTMP 的 chunked 格式打包并通过 TCP 发出去。这三层中任何一层出了问题表现都是“画面卡顿”或“声音断续”但排查路径完全不同。2.1 采集层AVCaptureSession 决定画质下限iOS 端采集基本绕不开AVCaptureSession。摄像头采集输出的格式一般是kCVPixelFormatType_32BGRA摄像头方向在竖屏下需要做旋转处理否则推出去的流在播放端是横着的。麦克风采集通常用AVAudioEngine的 input node格式是AVAudioFormat采样率一般设 44.1kHz 或 48kHz声道数双声道但很多 CDN 或播放器对双声道支持不好常见做法是推流前统一转成单声道。采集层最容易犯的错是把预览和编码混在一起。我见过某个直播项目的做法是直接从预览 layer 上抓帧去编码结果画面模糊不说帧率还上不去。正确的做法是预览用AVCaptureVideoPreviewLayer编码从AVCaptureVideoDataOutput的代理回调里拿CVPixelBuffer两条路径互不干扰。// 在 AVCaptureVideoDataOutput 的代理回调里拿到原始帧 func captureOutput(_ output: AVCaptureOutput, didOutput sampleBuffer: CMSampleBuffer, from connection: AVCaptureConnection) { // 根据当前设备方向旋转连接 if connection.isVideoRotationAngleSupported(90) { connection.videoRotationAngle 90 } // 把 BGRA 的 pixel buffer 交给编码器 encoder.encode(sampleBuffer) }这段代码里videoRotationAngle是 iOS 17 之后推荐的方向设置 API旧系统用的是videoOrientation。旋转必须在采集连接层做而不是在编码后加旋转滤镜否则会多一次像素拷贝高分辨率下对 CPU 的消耗非常明显。另一个隐含参数是videoMirrored前置摄像头如果不做镜像主播看预览是正常的但观众端看到的画面是反的这个在 UI 层处理比在 SDK 里处理好因为美颜模块通常也需要知道当前的镜像状态。2.2 编码层硬编优先时间戳才是同步的关键iOS 上有两套编码路径VideoToolbox 硬编 H.264 / AudioToolbox 硬编 AAC或者用纯软件编码器。硬编的能耗和效率优势很明显但它的码率控制是黑匣子你给它设了AVVideoAverageBitRateKey它不保证实时精确到这个值实际码率会随着画面复杂度波动。软编可控性更强但 iPhone 在 1080p 30fps 下软编会明显发热长时间直播有降频掉帧的风险。编码层最容易被忽视的是PTS和DTS。H.264 允许 B 帧B 帧的显示顺序和解码顺序不一致导致CMSampleBuffer的时间戳和编码器输出的顺序不是一一对应的。推流到 RTMP 时服务端按 DTS 排序写入 FLV播放器按 PTS 展示如果你把时间戳传错轻则音画不同步重则播放器画面抖动甚至黑屏。很多 SDK 为了省事直接丢弃 B 帧强制profile baseline换取时间戳上的安全代价是同等码率下的画质下降。// 设置 H.264 编码参数时明确关闭 B 帧简化时间戳处理 NSDictionary *compressProps { AVVideoAverageBitRateKey: (800 * 1000), AVVideoMaxKeyFrameIntervalKey: (60), AVVideoProfileLevelKey: AVVideoProfileLevelH264MainAutoLevel, }; NSDictionary *settings { AVVideoCodecKey: AVVideoCodecTypeH264, AVVideoWidthKey: (720), AVVideoHeightKey: (1280), AVVideoCompressionPropertiesKey: compressProps, };编码参数里AVVideoMaxKeyFrameIntervalKey是按帧数算的 GOP不是按秒算的。如果你设置 60 帧间隔且帧率是 30fps那每 2 秒出一个关键帧这个节奏对直播来说偏大一般建议 GOP 控制在 1 到 2 秒。还要注意AVVideoProfileLevelKey用 Main profile 且关闭 B 帧兼容性和画质的折中最好。2.3 协议层RTMP 握手、chunk size 与时间戳映射RTMP 的协议细节很多但你集成 SDK 时只需要关心三个表现层的问题连接能否建立、推流是否断线、延迟是否在可接受范围。握手阶段是严格的 C0/C1/C2 交互任何一端超时都会导致连接失败SDK 内部通常把握手的超时时间设置在 3 到 5 秒超过这个时间直接回调连接失败避免业务层傻等。chunk size 的影响很多人不知道。RTMP 默认的 chunk size 是 128 字节但视频帧动辄几十 KB如果一直用默认值一个大帧会被拆成几百个 chunk每个 chunk 还有 12 字节的头开销浪费带宽不说TCP 的 Nagle 算法可能还会把多个小包合并增加延迟。所以 SDK 在握手成功后一般会发一条set chunk size消息把大小提到 4096 或 8192。你可以在抓包工具里确认这个协商是否生效如果没生效多半是服务端不支持或被防火墙拦截了。# 用 tcpdump 观察推流过程中的 RTMP 信令交互 sudo tcpdump -i en0 -A tcp port 1935 -c 200这个命令用于排查推流连接是否建立、服务端是否回包。注意 RTMP 默认端口是 1935但很多 CDN 会把推流端口设计成非标准端口抓包前要先确认你实际连的端口。如果抓包看到大量 TCP 重传说明当前上行网络不稳这时候调什么码率都是治标重传导致的延迟增长才是直播卡顿的根因。3. 集成落地解压 SDK、配置权限、写出最小推流代码拿到压缩包后第一步不是看文档而是看目录结构。一个好的 SDK zip 里应该有.framework或.xcframework二进制、头文件、一个可运行的示例工程以及变更记录或接入文档。缺少示例工程的 SDK 要格外小心说明作者没有对集成流程做充分验证。3.1 解压并识别 SDK 包结构常见做法是先创建一个独立目录把 zip 解压进去再用命令查看文件层级避免直接在下载目录里操作污染环境。重点关注以下几点framework 是静态库还是动态库、是否包含模拟器架构、示例工程用的语言是 Objective-C 还是 Swift。mkdir -p ~/work/rtmp-sdk cd ~/work/rtmp-sdk unzip ../LivePushSDK.zip # 查看 framework 支持的架构 lipo -info LivePushSDK.framework/LivePushSDK # 输出示例: Architectures in the fat file: arm64 x86_64lipo输出里如果只有arm64说明这个 framework 不支持模拟器运行你需要在真机上调试或者要求 SDK 方提供包含x86_64的版本。在 xcframework 时代这种兼容问题已经少见但老项目里仍可能遇到。另外如果 framework 是动态库你需要检查工程的Embed Frameworks阶段是否正确配置否则一运行就报image not found。3.2 Info.plist 权限与后台模式配置推流需要相机和麦克风权限这两个权限缺少描述字符串时App 会在调用时直接闪退。这属于必填项不需要 SDK 文档提醒也应该加上。如果你的直播场景允许主播切后台后音频继续推流需要在UIBackgroundModes里声明audio但这个配置有 App Store 审核风险审核员会质疑你为什么要后台收音频尤其是纯直播类应用通常不建议开启而是切后台时主动断开推流。keyNSCameraUsageDescription/key string需要访问相机以进行视频直播/string keyNSMicrophoneUsageDescription/key string需要访问麦克风以采集直播声音/string这里要注意iOS 对麦克风权限的提示文案如果写得太含糊用户在第一次弹窗时拒绝后续只能去系统设置里手动打开App 内无法二次触发系统弹窗。所以文案要写得足够具体比如说明“直播时你的声音会被推送给观众”而不是笼统的“需要使用麦克风”。另外如果你在模拟器上调试相机和麦克风都是模拟的权限系统行为与真机不同不建议用模拟器验证完整推流链路。3.3 最小推流代码从连接、推流到断开SDK 的 API 设计大同小异核心是三个动作配置推流参数、连接 RTMP 服务器、开始推流。下面这段 Swift 代码展示的是完整的最小闭环业务侧只需持有推流器实例并监听状态回调即可。import UIKit import LivePushSDK class LiveRoomViewController: UIViewController { private lazy var pusher: LivePusher { let config LivePusherConfig() config.videoSize CGSize(width: 720, height: 1280) config.fps 30 config.bitrate 1_200_000 config.audioSampleRate 44100 return LivePusher(config: config) }() override func viewDidLoad() { super.viewDidLoad() // 预览画面挂到视图上 pusher.setPreviewView(view) pusher.delegate self } objc func startPush() { // rtmp://example.com/live/stream_key 是推流地址 pusher.startPush(url: rtmp://push.example.com/live/abc123) } objc func stopPush() { pusher.stopPush() } } extension LiveRoomViewController: LivePusherDelegate { func pusher(_ pusher: LivePusher, stateDidChange state: LivePusherState) { // 状态机: connecting - connected - pushing - reconnecting - stopped } func pusher(_ pusher: LivePusher, didFailWithError error: Error) { // 连接失败、编码失败、服务端断开都会走这里 } }这段代码里有几个参数值得单独说。videoSize用的是物理像素不是逻辑像素720x1280 意味着竖屏 720p它决定编码分辨率的上限而不是裁剪成这个比例。bitrate是平均码率单位是 bps所以 1_200_000 代表 1.2Mbps在 720p 30fps 下属于中等偏下的码率适合上行带宽一般的主播。startPush里传的 URL 如果带了鉴权参数比如?tokenxxx或/stream_key?sign...SDK 一般会原样拼到 RTMP URL 上但某些服务端的鉴权格式要求token放在 app 名后面而非 query这个要跟 CDN 厂商确认不是 SDK 自己能决定的。4. 上线前必调的推流参数分辨率、码率、GOP 与音频采样率很多开发者集成完 SDK 后能推流成功但播出来的画面要么模糊、要么延迟高、要么声音和画面对不上。问题基本都出在参数配置上。这一章给出一组我常用的起步值以及每个参数的调节逻辑和上限。4.1 分辨率与码率从带宽倒推画质而不是从画质倒推带宽分辨率决定了像素数量码率决定了描述这些像素的预算。同样是 720p用 800kbps 推和用 2Mbps 推画质差一个档次。反过来的问题更常见主播家里上行带宽只有 2Mbps你却把码率设成 2400kbps结果就是频繁断流和长时间加载。我在接直播项目时第一步先确认主播的典型上行带宽再决定推流参数。分辨率帧率推荐码率区间适用场景540p (960x540)24-30600-900 kbps户外、网络不稳定720p (1280x720)301.2-1.8 Mbps普通室内直播1080p (1920x1080)302.5-4 Mbps游戏直播、专业设备画质是玄学但码率不是。低于推荐下限画面会出现明显的块状噪声尤其是快速移动的画面高于推荐上限不一定是坏事但会挤占上行带宽和 CDN 转码资源而且播放端如果网速不够反而会频繁缓冲。建议在推流器里内置三档码率阶梯让主播手动切换或按网络质量自动切换。4.2 GOP、帧率与音画同步两个秒级参数的平衡GOP 就是两个关键帧IDR 帧之间的间隔。直播场景下 GOP 太大观众端进入直播时等待关键帧的时间就越长很多播放器策略是“有 IDR 才开始播放”所以 GOP 2 秒会造成观众打开直播后最多黑屏 2 秒甚至更久。GOP 太小关键帧数量变多同样码率下画质会被压缩得更厉害。我一般控制在 1 到 2 秒区间码率足够高时取 2 秒网络差时取 1 秒代价是同等码率下画质略降。音画同步问题经常被忽视。音频编码器是按采样率累加时间戳的视频编码器是按帧间隔累加的两边漂移的速率不同。SDK 内部通常以音频时间戳为主时钟视频时间戳做对齐因为人耳对音频抖动的敏感度远比视觉高。你要检查的是 SDK 是否暴露了音画同步的开关有的 SDK 默认关闭导致推流时间一长声音比画面快出几十毫秒越积越多。4.3 弱网参数缓冲阈值、丢帧策略与重连间隔RTMP 基于 TCPTCP 不会丢包但会重传重传导致拥塞拥塞导致延迟增长。弱网场景下最有效的策略不是加缓冲而是丢帧。具体做法是本地维护一个发送队列当队列长度超过阈值比如 300ms 或 500ms就丢弃非关键帧直接编码新的关键帧让播放端迅速恢复到低延迟状态。// 弱网丢帧策略的伪代码逻辑 - (void)onSendQueueFull { // 队列积压超过阈值时清空待发送的非关键帧 [self.videoFrameQueue removeAllFramesExceptKeyFrame]; // 请求编码器立即输出一个新的关键帧 [self.encoder forceGenerateKeyFrame]; // 音频不丢只丢视频保证语音通话不断 }丢帧策略要注意边界如果队列积压已达到 2 秒以上说明网络已经堵塞到推不了任何数据了这时候应该断开重连而不是继续堆积。重连间隔一般用递增策略第一次 1 秒第二次 2 秒最多不超过 10 秒避免在信号恢复前狂打服务端导致封 IP。5. 避坑指南iOS RTMP 推流 SDK 最常见的 5 个翻车现场这一部分是我实际集成和后期维护中反复踩过的坑。每一条都是先描述现象再给原因和解决办法你可以按图索骥省去自己排查的时间。5.1 现象预览黑屏但服务端能看到流原因有两个。第一你没有把预览 layer 的videoGravity设置为适合的缩放模式导致画面被裁剪到屏幕外第二你的推流器实例是局部变量被 ARC 提前释放了预览虽然挂上了 view但 dispatch source 已经停了。第二种更隐蔽因为推流可能还在继续但预览不动了。解决把推流器设置为控制器的一个强引用属性并且在viewDidLayoutSubviews重新设置预览 frame因为旋转屏幕时预览 layer 不会自动跟着变。如果推流器没有暴露预览 layer而只是接受一个 view那么 SDK 内部一般会创建AVCaptureVideoPreviewLayer并替换掉 view 的layerClass此时不要手动操作 view 的 layer 层级否则会发生冲突。5.2 现象切后台再回来声音消失但画面正常原因iOS 对后台音频有严格的会话管理。切后台时音频 session 进入不活跃状态麦克风被系统关闭回到前台后没有重新激活AVAudioSession。很多 SDK 只在初始化时设置过一次 session没有监听UIApplicationDidBecomeActiveNotification。解决在前台恢复时主动重新设置音频 session 并重启音频采集。代码上要在didBecomeActive回调里调用AVAudioSession.sharedInstance().setActive(true)并且确认setCategory参数用的是.playAndRecord否则麦克风和扬声器不能同时工作。5.3 现象直播 1 小时后内存持续上涨最后被系统杀死原因视频硬编输出CMSampleBuffer后如果没有及时释放CVPixelBuffer或者发送队列里帧对象被 NSArray 持有而没有做容量上限就会逐步积累到上百兆。更隐蔽的是某些 SDK 在弱网丢帧时的回调里不断创建新对象导致 autorelease pool 峰值过高。解决先做粗定位用 Instruments 的 Leaks 模板检测观察CMSampleBufferCreate或CVPixelBufferCreate的调用频率。常规手段是对发送队列做上限控制比如最多存放 30 帧超过就丢旧帧同时检查 SDK 是否提供内存回收的接口有的 SDK 需要直在切换清晰度时调用一次flush来清理编码器内部缓冲。5.4 现象推流地址加了鉴权 token 后握手失败原因RTMP URL 的鉴权参数有两种常见格式一种是 query 参数如?signabcdef另一种是 path 参数如/live/stream_key?signabcdef或/live/stream_key/abcdef。服务端解析方式不同SDK 如果只会拼接不打散就会出现握手数据被鉴权串污染的情况。解决先用播放器工具直接拉流测试 URL 是否可用排除 SDK 兼容问题。如果确认是 SDK 拼 URL 的问题就在接入层自己做一次 URL 预处理把鉴权参数放到 SDK 提供的独立字段里或者手动拼好完整地址再传给推流器。5.5 现象偶尔出现画面卡住 1 到 2 秒然后突然跳帧日志里没有错误原因这是 TCP 拥塞导致的延迟突增不是编码错误。RTMP 的 ACK 机制在带宽不足时会自动降低发送速度SDK 如果没做发送队列积压检查就会一直把数据塞进 socket播放端表现为画面停顿后快进。解决开启 SDK 的弱网自适应选项让它在发送队列超过阈值时主动丢帧并请求重发关键帧。如果 SDK 没提供这个能力你需要自己监控socket可写状态或发送队列长度在外部调用forceGenerateKeyFrame来打断积压。6. 进阶让推流质量可量化比调参更能救命前面讲的所有参数最终都要有验证手段。我的习惯是给直播工程加一个内部调试面板显示三个指标上行实时码率、发送队列长度、音视频时间戳差值。这三个指标能覆盖 80% 的推流问题。上行实时码率大于设定的平均码率说明网络有富余可以尝试提档持续低于设定码率的 60%说明网络开始拥塞SDK 大概率在靠丢帧硬撑。发送队列长度正常是 0 到 2 帧如果持续堆积超过 15 帧说明发送速率已跟不上编码产出的速率此时即使画面不卡延迟也在悄悄增加。时间戳差值在 0 到 100ms 之间都是正常范围如果超过 300ms 且持续增长就要怀疑音频 session 被系统打断后没有重新对时。弱网自适应的实现思路不复杂关键在于要敢切。我见过不止一个团队做好了码率阶梯检测逻辑但不敢真的切换理由是怕切换瞬间画面黑屏。实际上切换码率时主动发一个关键帧播放端感知度极低远比网络持续恶化导致断流强。入门项目先做两档切换比如 720p 1.2Mbps 和 540p 800kbps切换阈值用 5 秒内的平均发送队列长度不要用瞬时值否则网络抖动会触发频繁切换画面反而更差。另一个习惯是把 SDK 的重连逻辑当成最后防线而不是主要依赖它。重连意味着断流观众端会经历加载转圈体验大打折扣。与其指望重连快不如在弱网刚开始时就主动降级让推流链路一直保持存活。我在某个项目里把降级阈值设得比较激进宁可让画面模糊一点也要保证不卡断结果观众留存数据明显好过之前“保持清晰但时不时缓冲”的版本。后来我总结出一条经验直播场景里模糊的画面能看完卡顿的画面会骂人。到这里这个方向值不值得投入已经很清楚了。只要你的业务是单主播向 CDN 分发RTMP 推流 SDK 依然是 iOS 端最省力的选择。把这一章的监控面板加进工程再配合前面几章的参数和避坑经验你大概率能少走我当年走过的那段弯路。希望帮到你。本文还有配套的精品资源点击获取