简介面向C#开发者的FFmpeg API调用实例包填补了C#语言下调用FFmpeg原生接口示例稀少的空白。该工程演示如何通过API方式拉取RTMP流并实时播放核心思路是利用ffmpeg.autogen库与FFmpeg原生函数完全同名的特性将网上常见的C/C代码直接移植到C#只需在方法前加上“ffmpeg.”前缀即可。压缩包共含145个文件其中111个.h头文件用于声明接口16个.dll运行库提供底层能力8个.cs源码文件展示调用逻辑另含3个可执行程序和完整的解决方案/工程配置文件包体仅25.46MB适合快速下载研究。已有9702人学习使用对于想绕过C环境、在C#中直接操控FFmpeg的开发者而言这份资源提供了清晰的移植范例、可用DLL和可直接编译的工程结构能显著降低API方式的集成门槛。1. 为什么说“API方式拉RTMP流”比命令行更值得做C#开发FFmpeg例子用API方式让FFmpeg拉取RTMP流并播放表面看只是个播放Demo但真正落地过的人会明白命令行派和API派的差距不在能不能出画面而在延迟、断开恢复、取帧和控制权的差别。命令行方式通常起一个ffmpeg.exe子进程往UDP或文件管道里推流再另起播放器读链路长、延迟高、崩溃依赖外部进程最关键的是拿不到帧数据做不了画面分析或二次处理。API方式把FFmpeg库直接嵌进C#进程里自己控制拉流、解码、重连和渲染适合做实时监控、直播伴侣、设备预览这类需要“既要能播又要能管”的桌面或服务端程序。这篇笔记就把整个流程拆开讲新手能照着跑通熟手能少踩几个我踩过的坑。2. C#接入FFmpeg API选绑定库、初始化日志与网络栈2.1 封装库与P/Invoke绑定怎么选在C#里调FFmpeg常见做法不是自己从零声明几百个extern方法而是用一套开源的C#绑定库。这类库把FFmpeg的C接口翻译成C#能调用的函数签名有的还顺手封装了AVFrame到Bitmap的转换。我建议先分清两种用法一种是“封装库”把打开、解码、转码封装成高级对象写起来快但遇到特殊需求时容易卡在封装层另一种是“P/Invoke绑定库”只做函数签名翻译逻辑还是你自己写灵活但代码量大。我一般选后者理由很简单RTMP流场景有太多不确定性封装库往往把超时、丢帧、重连策略隐藏起来出问题时黑匣子一样不好查。而绑定库暴露的就是FFmpeg原生API网上查到的FFmpeg C代码几乎能一行行对照着改写到C#里。代价是要自己管理内存AVPacket和AVFrame都是非托管对象用完后得手动unref和free这点在C#里特别容易翻车。还有个关键决策x86还是x64。FFmpeg的native库编译版本必须和C#项目平台一致。我遇到过几次诡异的内存崩溃最后发现是项目在AnyCPU下跑64位进程加载了32位的dll函数指针错位直接AccessViolation。所以要在一开始就把平台锁定成x64省得后面排查半天。2.2 初始化三件事日志级别、网络模块和输入参数拿到绑定库后第一步不是急着打开RTMP地址而是先做三件初始化设置日志级别、初始化网络层、准备打开输入流的参数。日志级别很重要RTMP拉流失败时FFmpeg会打一堆日志默认级别很啰嗦我一般设为AV_LOG_WARNING只保留警告和错误方便在输出窗口里看到关键信息。// 1. 日志级别只在警告和错误时输出避免刷屏 FFmpegApi.av_log_set_level(FFmpegApi.AV_LOG_WARNING); // 2. 网络模块初始化RTMP属于网络协议必须调用 FFmpegApi.avformat_network_init();这两行看起来简单但漏掉第二个会导致后续avformat_open_input返回找不到协议的错误。日志回调也要在这里想清楚FFmpeg的日志输出会从native线程回调到C#不能在里面直接操作UI控件否则跨线程异常或者死锁。我通常把日志收集到一个队列里UI定时器再去消费。然后是输入参数。RTMP拉流时需要告诉FFmpeg这是直播流、缓冲多大、超时多久。这些参数通过AVDictionary传给avformat_open_inputAVDictionary* options null; // 表示按直播方式解析不会当成文件读取很多rtmp流不设这个会阻塞 FFmpegApi.av_dict_set(options, rtmp_live, live, 0); // 缓冲大小单位毫秒数值越小延迟越低但网络抖动时更容易断 FFmpegApi.av_dict_set(options, rtmp_buffer, 1000, 0); // socket超时单位微秒这里设成3秒 FFmpegApi.av_dict_set(options, timeout, 3000000, 0);这几个参数的取值直接影响直播延迟和稳定性。rtmp_live必须设否则FFmpeg可能把直播流当成flv文件去读读到末尾就返回EOF然后你以为断流了。rtmp_buffer建议从1000毫秒起步画面卡顿就调大延迟变大就调小这个在后面章节会细说。2.3 最小拉流代码先拿到AVFormatContext初始化完成后就可以打开RTMP流了。这个步骤的核心是拿到AVFormatContext它相当于整个输入的“总调度器”后面所有流信息都挂在它上面。string url rtmp://example.com/live/stream; // 分配上下文注意绑定库里通常返回指针 AVFormatContext* pFormatCtx FFmpegApi.avformat_alloc_context(); if (pFormatCtx null) { throw new Exception(avformat_alloc_context failed); } // 打开输入流options里的key-value会在这里生效 int ret FFmpegApi.avformat_open_input(pFormatCtx, url, null, options); if (ret 0) { // 返回值是负数对应的是AVERROR码需要翻译成可读信息 throw new Exception($avformat_open_input failed: {FFmpegApi.AvErrorToString(ret)}); } // 读取流信息解析出视频流、音频流的编码参数 ret FFmpegApi.avformat_find_stream_info(pFormatCtx, null); if (ret 0) { throw new Exception(avformat_find_stream_info failed); } // 找到一路视频流-1表示没找到 int videoStreamIndex FFmpegApi.av_find_best_stream( pFormatCtx, AVMediaType.AVMEDIA_TYPE_VIDEO, -1, -1, null, 0); if (videoStreamIndex 0) { throw new Exception(no video stream found); }这段代码有个容易忽略的点avformat_open_input的第一个参数传的是指针的指针因为函数内部可能重新分配上下文。绑定库里如果已经帮你包了一层可能是out参数但如果是纯P/Invoke必须用。另一个注意点是avformat_find_stream_info会阻塞一段时间它要读一部分数据去探测编码参数。对于RTMP直播流探测时间默认可能到几秒如果想快一点可以在options里加analyzeduration和probesize这两个参数控制探测的数据量和时长后面会给出具体建议。拿到videoStreamIndex后就可以进入解码流程了。这一步的验证标准很简单如果日志没报错且videoStreamIndex 0说明RTMP地址、网络、协议解析都通了接下来要处理的是怎么把这些数据变成画面。3. 解码RTMP流并渲染到窗口从AVPacket到Bitmap3.1 解码循环AVPacket到AVFrameRTMP流里的视频数据是以AVPacket形式被av_read_frame读出来的但AVPacket是压缩数据不能直接显示。需要交给解码器转换成AVFrameAVFrame里才是一帧完整的图像数据。这个转换过程在现代FFmpeg里是send_packet和receive_frame配合完成的。// 根据视频流里的编码ID找到对应解码器 AVCodec* codec FFmpegApi.avcodec_find_decoder( pFormatCtx-streams[videoStreamIndex]-codecpar-codec_id); if (codec null) { throw new Exception(codec not found); } // 分配解码器上下文并用流的参数填充它 AVCodecContext* codecCtx FFmpegApi.avcodec_alloc_context3(codec); FFmpegApi.avcodec_parameters_to_context(codecCtx, pFormatCtx-streams[videoStreamIndex]-codecpar); FFmpegApi.avcodec_open2(codecCtx, codec, null); // 分配AVPacket和AVFrame循环里复用 AVPacket* packet FFmpegApi.av_packet_alloc(); AVFrame* frame FFmpegApi.av_frame_alloc(); while (!stopped) { // 读取一包数据这里会阻塞后面单独讲超时和线程 int ret FFmpegApi.av_read_frame(pFormatCtx, packet); if (ret 0) { // 返回EOF或错误需要判断是断流还是正常结束 break; } // 只处理属于视频流的包 if (packet-stream_index videoStreamIndex) { // 把压缩包送给解码器 int sendRet FFmpegApi.avcodec_send_packet(codecCtx, packet); if (sendRet 0) { // 可能丢包或解码器状态异常继续读下一包 av_packet_unref(packet); continue; } // 循环取出所有可用的帧 while (FFmpegApi.avcodec_receive_frame(codecCtx, frame) 0) { // 这里拿到了一帧YUV数据 ProcessFrame(codecCtx, frame); } } // 必须unref否则内存泄漏很明显跑几分钟就涨几百MB FFmpegApi.av_packet_unref(packet); }这里的关键点是av_read_frame和avcodec_receive_frame的配合关系。av_read_frame读到的可能不是视频包可能是音频包或字幕包所以要用stream_index过滤。avcodec_send_packet并不保证立刻输出一帧它内部有缓冲机制所以要用while循环把receive_frame返回的每一帧都取走直到它返回AVERROR(EAGAIN)表示暂时没有帧了。新手最容易写错的是只调一次receive_frame结果画面掉帧、解码延迟越来越大。3.2 像素格式转换为什么RTMP流不能直接上屏从解码器拿到的AVFrame绝大多数情况下是YUV420P格式。这种格式是给编码和传输用的屏幕显示需要的是BGR或BGRA。直接拿YUV数据去构造Bitmap会得到颜色完全错乱的画面这不是代码bug而是像素格式不匹配。转换需要用到FFmpeg的swscale库。它负责把YUV420P转成BGR24同时做分辨率缩放。int width codecCtx-width; int height codecCtx-height; // 创建转换上下文输入是解码器输出的像素格式输出是BGR24 SwsContext* swsCtx FFmpegApi.sws_getContext( width, height, codecCtx-pix_fmt, width, height, AV_PIX_FMT_BGR24, FFmpegApi.SWS_BILINEAR, null, null, null); if (swsCtx null) { throw new Exception(sws_getContext failed); } // BGR24每像素3字节按行对齐 byte[] rgbBuffer new byte[width * height * 3]; unsafe { fixed (byte* pBuf rgbBuffer[0]) { // 指向输出缓冲区的指针数组sws_scale按这个拿到输出地址 byte* dstData1 pBuf; int dstLinesize1 width * 3; FFmpegApi.sws_scale( swsCtx, frame-data, frame-linesize, 0, height, dstData1, dstLinesize1); } }这段代码里最容易踩坑的是行对齐。FFmpeg解码出来的帧linesize不一定等于width乘以像素字节数因为底层会有对齐。但sws_scale在输出BGR24时可以帮我们处理对齐前提是输出的linesize填的是width乘3而不是某个手动计算的对齐值。如果你发现画面偏绿、偏色或者有锯齿纹先检查rgbBuffer的大小和dstLinesize1是否一致。另一个坑是sws_getContext如果输入尺寸是奇数某些分辨率下转换会失败RTMP流一般不会但如果是海康等设备过来的自定义分辨率要注意做偶数对齐。3.3 用桌面窗体显示解码帧拿到BGR24的byte[]之后显示就是一个拷贝问题。我一般用桌面窗体的PictureBox通过Bitmap的LockBits把字节拷进去避免逐像素SetPixel这种慢操作。// 把BGR24字节数组拷贝到Bitmap内存区 Bitmap bmp new Bitmap(width, height, PixelFormat.Format24bppRgb); BitmapData bd bmp.LockBits( new Rectangle(0, 0, width, height), ImageLockMode.WriteOnly, PixelFormat.Format24bppRgb); try { Marshal.Copy(rgbBuffer, 0, bd.Scan0, rgbBuffer.Length); } finally { bmp.UnlockBits(bd); } // 切到UI线程再赋值这里假设pictureBox是窗体内的控件 if (pictureBox.InvokeRequired) { pictureBox.BeginInvoke(new Action(() { pictureBox.Image?.Dispose(); pictureBox.Image bmp; })); } else { pictureBox.Image?.Dispose(); pictureBox.Image bmp; }这里有两件事值得记住。第一Bitmap的PixelFormat必须是24bppRgb和sws输出的BGR24对应如果你用32bpp的BitmapRGB数据会错位画面会花。第二Marshal.Copy是整块拷贝LockBits保证了内存布局是连续的所以不要试图逐行拷贝那样既慢又容易错。旧Bitmap一定要Dispose否则显示几小时后内存涨到你怀疑人生。4. RTMP拉流必调参数延迟、超时与断线重连4.1 缓冲参数延迟和稳定性的平衡RTMP直播流天然有延迟FFmpeg内部为了平滑播放会维护一个缓冲队列。这个队列越大画面越稳定但延迟越高越小画面越实时但网络抖动时更容易卡顿或断流。这是个需要反复试探的参数。参数名作用建议值rtmp_buffer直播缓冲单位毫秒500 ~ 2000max_delay最大延迟单位微秒500000 ~ 2000000analyzeduration探测时长单位微秒500000 或更小probesize探测数据量单位字节1024 ~ 5120我一般先设rtmp_buffer1000max_delay1000000跑30分钟看延迟和卡顿情况。如果画面经常卡把rtmp_buffer加到1500或2000如果延迟太大降到500。注意这些参数要在avformat_open_input之前通过AVDictionary设置打开之后改不了。换一句话说你在代码里看到的options参数就是拉流的“第一道链路配置”。还有一个非常容易忽略的延迟来源解码buffer。有人把所有帧都放进队列再用定时器慢慢取结果画面越走越慢。正确做法是只保留最新帧丢弃累积帧后面第6章会展示具体实现。4.2 超时参数快速失败比一直等待更重要RTMP拉流最让人头疼的情况是网络断了但av_read_frame一直阻塞界面卡在最后一帧程序像死了一样。原因是没有设置socket超时FFmpeg在TCP层可能等很久才报错。我建议在options里显式设置超时// 超时时间单位是微秒这里设置3秒 FFmpegApi.av_dict_set(options, timeout, 3000000, 0); // 打开连接的超时单位微秒针对TCP握手阶段 FFmpegApi.av_dict_set(options, rtmp_conn_timeout, 3000000, 0);注意distinguishtimeout影响的是建立连接后的socket读写rtmp_conn_timeout影响的是RTMP握手阶段。如果网络很不稳定建议两个都设。设成0表示不设超时等多久都有可能。实际项目里我会把超时控制在3到5秒这样断线后可以在5秒内进入重连逻辑而不是干等30秒。设置超时之后av_read_frame返回的主要错误有两类一是AVERROR_EOF表示流结束二是AVERROR(ETIMEDOUT)或AVERROR(EAGAIN)表示网络超时但没有彻底断。这两种情况都应该进入重连判断而不是直接退出。4.3 断线重连策略不能只while循环很多教程写的重连就是死循环里反复open但实际跑起来会发现一个问题每次open失败后立即重试会让CPU飙高同时可能被服务器临时封IP。常见做法是加退避等待并且把打开失败的日志输出到自己的系统里。private AVFormatContext* OpenStreamWithRetry(string url, int maxRetry, int baseDelayMs) { AVFormatContext* ctx null; for (int i 0; i maxRetry; i) { ctx TryOpenOnce(url); if (ctx ! null) { return ctx; } // 每次失败后等待时间递增避免疯狂请求 int delay baseDelayMs * (i 1); Thread.Sleep(delay); // 这里输出日志第几次重试、等了多久 } return null; }重连时还需要注意音频流的重新初始化。如果只重新打开format context没有重新打开codec context继续用旧的解码器去解新流可能会遇到编码参数变化导致的崩溃。我习惯在断线重连时把codecCtx、swsCtx全部释放再从头走一遍第2章和第3章的顺序。5. 避坑C#调用FFmpeg API的典型翻车现场5.1 画面花屏或颜色偏色现象能出画面但颜色明显不对或者有斜向条纹。原因像素格式不匹配。最常见的是拿YUV的AVFrame直接构造Bitmap或者sws输出格式用的是BGRA但Bitmap声明成BGR24。解决先确认解码器的pix_fmt再确认sws输出的格式最后确认Bitmap的PixelFormat三者必须串成一条线。我习惯在调试时打印这三个值能省很多时间。5.2 播放几秒后画面不再刷新程序不退出现象窗口停在某一帧控制台没有新日志程序像是卡住。原因av_read_frame阻塞在socket读上超时参数没设置或者设置了但没生效。解决检查options里的timeout是否传进了avformat_open_input确认绑定库的av_dict_set方法签名没有用错。另一个隐蔽点是在UI线程里直接跑拉流循环UI消息阻塞会导致循环停转必须把拉流循环放到独立线程。5.3 音画不同步音频播放器越跑越快现象只显示画面声音没有或者画面和声音对不上。原因RTMP流里音频和视频是交错存储的av_read_frame轮流读出音视频包如果你只处理视频包而丢弃音频包解码器的时间线就乱了。解决要么把音频也解码出来并交给音频输出要么在显示帧时基于视频流的dts做时间控制。做监控类应用时可以忽略音频但做直播播放器时绕不开音频时间戳同步。5.4 avcodec_send_packet时直接AccessViolation崩溃现象程序启动后几秒内崩溃报非法访问内存地址。原因codecCtx没有完成初始化就调用send_packet最常见的是没有调用avcodec_parameters_to_context或者调用avcodec_open2失败后没检查返回值。解决打开解码器时严格按“find_decoder → alloc_context3 → parameters_to_context → open2”四步走每步都检查返回值。如果open2返回负数把错误码翻译成日志打出来不要跳过。5.5 日志回调里操作UI导致死锁或闪退现象程序不定期卡死卡死时正好有网络错误日志输出。原因FFmpeg的日志回调运行在native工作线程直接使用Invoke同步等待UI线程而UI线程可能正在等待拉流线程退出形成互相等待。解决日志回调里只把字符串放进线程安全队列UI线程用定时器取绝不在回调里做MessageBox、简单的控件赋值都不行。这属于C#和native交互时的经典坑排查起来很花时间。6. 进阶把拉流播放做成可复用的后台帧队列当你把前面流程跑通后下一步就别再把解码和UI写在一起了。真实项目里拉流模块往往要同时服务预览、录像、帧分析多个消费方。我习惯的做法是用一个后台线程持续拉流解码把最新帧的字节数组放进一个固定容量的队列UI线程只从队列里取最新一帧显示。这个结构最大的好处是拉流线程不会被UI卡顿拖住UI慢的时候队列自动丢旧帧保证显示始终接近实时。ConcurrentQueuebyte[] frameQueue new ConcurrentQueuebyte[](); int maxQueueSize 3; // 解码线程里每拿到一帧转换后的rgbBuffer void ProcessFrame(byte[] rgbBuffer) { // 如果队列满了先丢最旧的一帧保证延迟可控 if (frameQueue.Count maxQueueSize) { frameQueue.TryDequeue(out _); } // 注意要拷贝因为rgbBuffer会被复用 byte[] copy new byte[rgbBuffer.Length]; Buffer.BlockCopy(rgbBuffer, 0, copy, 0, rgbBuffer.Length); frameQueue.Enqueue(copy); } // UI侧定时器每30毫秒取一次 void OnUiTimer() { if (frameQueue.TryDequeue(out byte[] latest)) { pictureBox.Image?.Dispose(); pictureBox.Image ConvertRgbToBitmap(latest); } }队列容量我通常设成3帧对应30fps时约100毫秒缓冲既不会因为UI抖动导致长时间黑屏也不会让延迟超过人眼可感知的范围。如果要降低到“毫秒级延迟”可以把容量设成1帧但UI线程稍有卡顿就会丢帧。容量大小没绝对标准建议做成可配置项放到配置文件里上线后按现场网络情况调整。关于“边下边播”的理解我再说一句很多开发者以为边下边播是把整个流先存下来再播实际上直播场景里更常见的是“边收边弃只保留最近一帧”。如果你还需要录像那就在ProcessFrame里同时写一个文件流把packet或frame数据写进去但别放进同一个队列否则录像会拖垮拉流线程。我自己的一个习惯是把超时、缓冲、队列容量这三个参数都暴露成启动配置而不是硬编码。因为不同客户的网络环境差异比想象中大很多同一套参数在这个网络流畅换一个现场就频繁断流。参数可配置才能在线上不重新编译发布就能调优。最后说一点教训当年第一次做RTMP播放器时我图省事把解码和渲染放在同一个循环里结果UI一卡就导致拉流缓冲区越堆越满延迟从2秒涨到10秒用户直接要退货。后来改成后台线程加帧队列问题就没了。做流媒体这种东西解耦永远比省代码重要。希望帮到你。本文还有配套的精品资源点击获取