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

hacksider/Deep-Live-Cam

菜单

扩展指南

相关源文件

目的与范围

本指南旨在为希望扩展Deep-Live-Cam应用程序的新功能或修改现有功能的开发人员提供指导。它侧重于扩展架构、创建自定义帧处理器以及将其集成到系统中。有关通用架构的信息，请参阅技术架构，有关项目结构详情，请参阅项目结构。

扩展架构概述

Deep-Live-Cam采用模块化插件架构，主要围绕可以串联处理图像和视频的“帧处理器”。该系统旨在允许开发人员创建与现有管道无缝集成的新帧处理器。

来源：modules/processors/frame/core.py10-18 modules/core.py178-194

帧处理器接口

要创建兼容的帧处理器，您的模块必须实现特定的接口。帧处理器通过Python的导入系统在运行时动态加载。

必需的方法

每个帧处理器模块都必须实现这些必需的方法

来源：modules/processors/frame/core.py12-18

方法目的返回值
pre_check()验证环境，下载模型bool (如果检查通过则为 True)
pre_start()在处理开始前验证输入bool (准备开始则为 True)
process_frame()处理单个帧处理后的帧
process_image()处理单个图像文件无
process_video()处理视频帧无

来源：modules/processors/frame/face_swapper.py30-38 modules/processors/frame/face_swapper.py41-55 modules/processors/frame/face_swapper.py101-119 modules/processors/frame/face_swapper.py241-254 modules/processors/frame/face_swapper.py257-264

创建自定义帧处理器

请按照以下步骤创建新的帧处理器

  1. 在 modules/processors/frame/ 目录中创建一个新的 Python 文件
  2. 实现所有必需的接口方法
  3. 为您的处理器定义全局变量

基本模板

这是一个新帧处理器的模板

来源：modules/processors/frame/face_swapper.py1-25 modules/processors/frame/face_swapper.py30-55 modules/processors/frame/face_swapper.py213-238

帧处理器注册和加载

帧处理器由系统自动注册和加载。无需显式注册——系统使用Python的导入系统动态加载处理器。

来源：modules/processors/frame/core.py21-31 modules/processors/frame/core.py33-41 modules/core.py178-194

与全局配置集成

您的处理器可以访问和修改在 modules.globals 中定义的全局配置。主要配置选项包括：

配置目的类型
execution_providers硬件加速提供者列表
many_faces处理帧中的多个面部布尔值
map_faces将特定源面部映射到目标面部布尔值
keep_fps保持原始视频帧率布尔值
keep_audio在处理后的视频中保留音频布尔值
fp_ui帧处理器的 UI 状态字典

要为您的处理器添加 UI 集成

来源：modules/core.py63-82 modules.core.py84-88

处理模型

Deep-Live-Cam 对模型管理进行了标准化。请遵循以下实践：

  1. 将您的模型放在 models/ 目录中
  2. 在 pre_check() 中使用 conditional_download() 下载缺失的模型
  3. 使用提供的执行提供者进行硬件加速

模型加载示例

来源：modules/processors/frame/face_swapper.py30-38 modules/processors/frame/face_swapper.py58-67 models/instructions.txt

Pipeline集成

下图显示了您的自定义处理器如何集成到帧处理管道中

来源：modules/processors/frame/core.py79-84 modules/core.py178-194

多线程注意事项

系统使用多线程并行处理帧。您的处理器应处理这些注意事项：

  1. 为共享资源（模型等）使用线程锁
  2. 确保全局变量的线程安全
  3. 尽可能使用无状态设计

来源：modules/processors/frame/face_swapper.py20-21 modules/processors/frame/face_swapper.py58-67 modules/processors/frame/core.py69-76

命令行集成

为了使您的处理器可以通过命令行使用，请确保它包含在 modules/core.py 文件中的 --frame-processor 参数选项中。

来源：modules/core.py37

实际示例：创建背景模糊处理器

这是一个简单的处理器示例，可以模糊检测到的面部周围的背景

  1. 创建 modules/processors/frame/background_blur.py
  2. 实现必需的接口方法
  3. 添加逻辑来检测面部并模糊面部区域以外的所有内容

实现将包括

故障排除扩展

常见问题和解决方案

  1. 模块未加载：确保您的模块实现了所有必需的接口方法。
  2. 性能问题：使用 modules.globals.execution_providers 通过硬件加速。
  3. 内存泄漏：正确释放资源，特别是 GPU 资源。
  4. 线程错误：确保共享资源的线程安全。
  5. 模型错误：验证模型路径和格式与执行提供者的兼容性。

最佳实践

  1. 遵循现有的代码风格和模式
  2. 使用全局状态更新机制向用户提供反馈：update_status("Message", NAME)
  3. 优雅地处理异常，以防止管道崩溃
  4. 编写模块化、可重用的代码
  5. 优化计算密集型操作以提高性能
  6. 如果适用，请使用 torch.cuda.empty_cache() 释放 GPU 资源

来源: modules/processors/frame/face_swapper.py modules/core.py173-176 modules/core.py162-160

扩展依赖项

如果您的处理器需要额外的依赖项，请将其添加到 requirements.txt 文件中。如果依赖项仅由您的特定处理器使用，请考虑将其设为可选。

来源: requirements.txt