在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

obsproject/obs-studio

菜单

媒体源

相关源文件

媒体源是 OBS Studio 中一个多功能组件，可以直接在场景中播放媒体文件或流。它通过 FFmpeg 框架支持各种媒体格式，包括视频文件、音频文件和网络流。

本页面记录了媒体源的实现、架构和配置选项。有关其他捕获源（如游戏捕获或窗口捕获）的信息，请参阅视频源。

1. 概述

媒体源提供以下关键功能

  • 播放本地媒体文件（视频、音频文件、GIF）
  • 从远程 URL 流式传输（HTTP、RTSP、RTMP 等）
  • 硬件加速解码以提高性能
  • 可配置的播放行为（循环播放、播放速度、缓冲）
  • 与 OBS 热键集成以控制播放

该实现是 FFmpeg 插件的一部分，并利用 FFmpeg 广泛的媒体格式支持和解码功能。

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c31-67

2. 架构

媒体源被实现为使用 FFmpeg 进行媒体解码的 OBS 源插件。它遵循 OBS 源插件架构，同时增加了媒体特定功能。

2.1 组件结构

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c240-272 plugins/obs-ffmpeg/obs-ffmpeg-source.c783-807

2.2 数据结构

媒体源主要由 ffmpeg_source 结构定义，该结构包含媒体播放所需的所有状态和配置。

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c31-67

3. 媒体播放管线

媒体源管理媒体数据从文件或流到 OBS 的流程。该管线涉及从打开媒体到在 OBS 中显示媒体的多个阶段。

3.1 播放流程

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c290-316 plugins/obs-ffmpeg/obs-ffmpeg-source.c318-333 plugins/obs-ffmpeg/obs-ffmpeg-source.c240-272

3.2 帧回调

当媒体播放系统解码一个帧时，它会调用相应的回调函数，然后将该帧输出到 OBS

  • get_frame - 处理视频帧并通过 obs_source_output_video 输出它们
  • preload_frame - 在需要时预加载视频帧
  • get_audio - 处理音频数据并通过 obs_source_output_audio 输出它
  • media_stopped - 当媒体播放结束或停止时调用

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c240-288

4. 状态管理

媒体源维护一个状态机来跟踪和控制播放状态。它使用标准的 OBS 媒体状态并提供状态转换功能。

4.1 媒体状态

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c676-717 plugins/obs-ffmpeg/obs-ffmpeg-source.c274-288

4.2 播放控制

媒体源实现了 OBS 媒体控制接口，允许用户通过 UI 或热键控制播放

  • ffmpeg_source_play_pause - 在播放和暂停状态之间切换
  • ffmpeg_source_stop - 停止播放并可选择清除输出
  • ffmpeg_source_restart - 从头开始重新播放
  • ffmpeg_source_get_time / ffmpeg_source_set_time - 处理定位

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c676-752

5. 重连逻辑

对于非本地媒体（网络流），媒体源实现了重连逻辑以处理连接丢失

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c353-386 plugins/obs-ffmpeg/obs-ffmpeg-source.c335-351

6. 配置选项

媒体源提供了许多配置选项来控制播放行为和性能。

6.1 基本选项

选项描述默认
本地文件在本地文件和网络 URL 之间切换true
循环播放是否循环播放媒体false
媒体结束时清除播放结束时显示为空白true
激活时重新开始当源激活时重新开始播放true
硬件解码可用时使用硬件加速false
色彩范围YUV 色彩范围（自动/有限/全）汽车
速度播放速度百分比100%

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c117-128 plugins/obs-ffmpeg/data/locale/en-US.ini71-92

6.2 网络流选项

选项描述默认
缓冲网络缓冲（MB）2 MB
重新连接延迟重新连接前的等待时间10 秒
可定位流是否支持定位false

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c93-115 plugins/obs-ffmpeg/data/locale/en-US.ini71-92

6.3 高级选项

媒体源还支持高级 FFmpeg 选项，这些选项可以直接传递给 FFmpeg 后端进行微调。

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c211-214 plugins/obs-ffmpeg/data/locale/en-US.ini13-14

7. 实现细节

7.1 初始化和注册

媒体源通过标准的 OBS 源注册机制注册到 OBS，使用定义所有回调和属性的 ffmpeg_source 结构。

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c595-633 plugins/obs-ffmpeg/obs-ffmpeg-source.c783-807

7.2 源生命周期

媒体源实现了核心源生命周期回调

  • ffmpeg_source_create - 创建并初始化源
  • ffmpeg_source_destroy - 清理资源
  • ffmpeg_source_update - 更新设置并重新配置播放
  • ffmpeg_source_activate / ffmpeg_source_deactivate - 处理源激活/停用
  • ffmpeg_source_tick - 每帧调用以处理重连和资源清理

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c595-807

7.3 媒体格式支持

媒体源通过 FFmpeg 支持多种媒体格式，包括

  • 视频：MP4、MKV、MOV、FLV、TS、AVI、WebM、GIF
  • 音频：MP3、AAC、OGG、WAV

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c130-133

8. 与 OBS 集成

媒体源与 OBS 的多个系统集成

  1. 属性系统 - 通过 ffmpeg_source_getproperties 提供配置 UI
  2. 热键系统 - 注册热键以控制播放
  3. 媒体控制 - 实现 OBS 媒体控制接口
  4. 过程处理器 - 暴露脚本/API 访问过程

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c135-215 plugins/obs-ffmpeg/obs-ffmpeg-source.c615-629

9. 错误处理

媒体源包含多种场景的错误处理

  1. 网络断开 - 自动重新连接，具有可配置的延迟
  2. 文件缺失 - 与 OBS 文件缺失系统集成
  3. 日志记录 - 详细记录设置和播放事件

来源: plugins/obs-ffmpeg/obs-ffmpeg-source.c217-239 plugins/obs-ffmpeg/obs-ffmpeg-source.c754-782