Heygem数字人系统输出命名规则：文件名生成逻辑与修改方式
1. 系统简介与背景
HeyGem 数字人视频生成系统是一款基于人工智能技术的音视频合成工具，能够将输入音频与人物视频进行深度对齐，实现口型同步的高质量数字人视频生成。该系统由开发者“科哥”在原始版本基础上进行了二次开发，推出了支持批量处理的 WebUI 版本，显著提升了多任务场景下的使用效率。
系统核心功能包括：
- 支持多种常见音频和视频格式
- 提供单个处理与批量处理两种模式
- 内置实时进度反馈与结果预览机制
- 自动生成结构化输出文件并支持一键打包下载
其中，输出文件的命名规则是用户在实际使用过程中常关注的重点问题，尤其在批量生成多个视频时，清晰、可追溯的文件名对于后期管理至关重要。
2. 输出文件命名机制解析
2.1 默认命名逻辑
当系统完成数字人视频生成后，会在outputs目录下保存结果文件。其默认命名遵循以下格式：
{原始视频文件名}_audio_{原始音频文件名}.{扩展名}示例说明：
假设上传的视频文件为teacher_a.mp4，音频文件为lesson_intro.wav，则生成的视频文件名为：
teacher_a_audio_lesson_intro.mp4命名组成部分详解：
| 组成部分 | 来源 | 说明 |
|---|---|---|
{原始视频文件名} | 用户上传的视频文件（不含路径） | 保留原文件名主体，用于标识源视频身份 |
_audio_ | 固定连接符 | 标识该视频已绑定特定音频 |
{原始音频文件名} | 用户上传的音频文件（不含路径） | 表明驱动口型的音频来源 |
{扩展名} | 源视频格式或系统统一设定 | 通常继承自输入视频格式 |
注意：若音频或视频文件名包含空格或特殊字符（如
(,),#,&），系统会自动将其替换为下划线_或删除，以确保文件系统兼容性。
2.2 批量处理中的命名策略
在批量处理模式中，系统会对多个视频应用同一段音频，此时命名规则保持一致，但体现出明显的批量化特征。
实际案例：
- 音频文件：
welcome_message.mp3 - 视频列表：
student_01.mp4student_02.mp4teacher_front.mp4
生成的输出文件如下：
student_01_audio_welcome_message.mp4 student_02_audio_welcome_message.mp4 teacher_front_audio_welcome_message.mp4这种命名方式具有以下优势：
- ✅ 明确区分不同源视频
- ✅ 清晰反映所使用的驱动音频
- ✅ 支持按名称排序快速查找对应关系
- ✅ 便于后续自动化脚本处理（如剪辑、归档）
2.3 文件存储路径结构
所有生成的视频均保存在项目根目录下的outputs/文件夹中，具体路径为：
./outputs/generated_videos/系统还会根据日期自动生成子目录，格式为YYYYMMDD，例如：
./outputs/generated_videos/20251219/每次运行生成任务时，系统会将新文件存入当天日期对应的文件夹内，避免历史结果被覆盖。
最终完整路径示例：
./outputs/generated_videos/20251219/student_01_audio_welcome_message.mp4该设计实现了时间维度上的隔离管理，有助于长期项目的数据留存与审计追踪。
3. 自定义输出命名的方法
虽然系统默认命名规则已具备良好的可读性和组织性，但在某些业务场景下，用户可能希望进一步自定义输出文件名，例如加入编号、项目代号或去除冗余信息。
目前可通过以下两种方式进行修改：
3.1 方法一：前端界面重命名（临时方案）
在 WebUI 的“生成结果历史”区域，用户可以：
- 预览生成的视频
- 下载指定文件
- 通过手动记录映射表的方式实现逻辑重命名
⚠️ 注意：当前 WebUI 不支持直接在界面上修改输出文件名，此操作需在下载后本地重命名。
适用场景：
- 小规模输出（<10 个文件）
- 对外交付前的最终整理阶段
建议做法：
原文件名：student_01_audio_welcome_message.mp4 新文件名：ProjectA_Module1_Intro_CN_01.mp43.2 方法二：修改后端代码实现自定义命名（推荐）
要从根本上改变输出命名逻辑，需修改系统后端处理脚本。该系统基于 Python + Gradio 构建，核心生成逻辑位于inference.py或batch_process.py文件中。
修改步骤如下：
步骤 1：定位文件生成函数
打开batch_process.py，找到负责保存视频的函数，通常形如：
def save_generated_video(video_path, audio_path, output_dir): base_video = os.path.splitext(os.path.basename(video_path))[0] base_audio = os.path.splitext(os.path.basename(audio_path))[0] output_name = f"{base_video}_audio_{base_audio}.mp4" output_path = os.path.join(output_dir, output_name) # ... 视频写入逻辑 return output_path步骤 2：插入自定义命名逻辑
可根据需求添加时间戳、序列号、项目前缀等元素。例如：
import datetime def generate_custom_filename(video_path, audio_path, index=None, prefix=""): base_video = os.path.splitext(os.path.basename(video_path))[0] base_audio = os.path.splitext(os.path.basename(audio_path))[0] timestamp = datetime.datetime.now().strftime("%H%M%S") idx_str = f"{index:03d}" if index is not None else "" # 自定义格式：{前缀}_{序号}_{原视频}_by_{音频简写}_{时间戳}.mp4 output_name = f"{prefix}{idx_str}_{base_video}_by_{base_audio[:5]}_{timestamp}.mp4" return output_name步骤 3：集成到主流程
替换原有命名调用：
# 修改前 # output_name = f"{base_video}_audio_{base_audio}.mp4" # 修改后 output_name = generate_custom_filename(video_path, audio_path, index=i, prefix="DG_")效果示例：
| 原始命名 | 自定义命名 |
|---|---|
student_01_audio_welcome_message.mp4 | DG_001_student_01_by_welco_142345.mp4 |
优点：
- ✅ 支持自动化编号
- ✅ 可嵌入项目标识
- ✅ 时间精确到秒，防止冲突
- ✅ 适合大规模生产环境
3.3 推荐命名模板
以下是几种适用于不同场景的推荐命名格式：
| 场景 | 推荐格式 | 示例 |
|---|---|---|
| 教学课件 | {课程代号}_{章节}_{角色}_{语言}.mp4 | MATH101_CH3_teacher_zh.mp4 |
| 客服播报 | {城市}_{业务类型}_{日期}_{序号}.mp4 | shanghai_refund_20251219_001.mp4 |
| 营销视频 | {品牌}_{产品线}_{地区}_{版本}.mp4 | NovaPhone_X_series_eu_v2.mp4 |
| 内部测试 | {test}_{模块}_{时间戳}.mp4 | test_lipsync_142345.mp4 |
这些模板可通过上述代码方式灵活实现，并作为配置项固化到系统中。
4. 常见问题与解决方案
4.1 文件名重复怎么办？
现象：两次使用相同音视频组合生成文件，导致覆盖风险。
原因分析：
- 系统未在文件名中加入时间戳或唯一标识
- 多次运行未清空输入队列
解决方案：
- 在命名中加入
datetime时间戳（精确到秒） - 或启用自动递增索引（如
_v1,_v2） - 修改代码加入判重逻辑：
if os.path.exists(output_path): name_only = output_name.rsplit('.', 1)[0] ext = output_name.rsplit('.', 1)[1] counter = 1 while os.path.exists(os.path.join(output_dir, f"{name_only}_v{counter}.{ext}")): counter += 1 output_name = f"{name_only}_v{counter}.{ext}"4.2 特殊字符导致保存失败
现象：文件名含中文括号、冒号等字符时，Linux 系统报错。
根本原因：
- Linux 文件系统不支持
:、?、*、|等符号 - Windows 虽有限支持，但仍建议规避
修复方法：
在文件名生成前加入清洗函数：
def sanitize_filename(filename): invalid_chars = r'[<>:"/\\|?*\x00-\x1F]' cleaned = re.sub(invalid_chars, '_', filename) # 避免连续下划线 cleaned = re.sub(r'_+', '_', cleaned) return cleaned.strip('_')调用位置：
output_name = sanitize_filename(output_name)4.3 如何实现全局命名策略配置？
更高级的做法是将命名规则抽象为可配置模板，通过 JSON 或环境变量控制。
示例配置文件config/naming.json：
{ "template": "{prefix}_{index:03d}_{video}_{audio_short}_{time}", "prefix": "DIGITAL_HUMAN", "audio_length": 5, "time_format": "%H%M%S" }然后在代码中加载并解析模板，实现无需改代码即可调整命名风格。
5. 总结
HeyGem 数字人视频生成系统的输出命名机制采用“视频名_audio_音频名”的默认格式，结构清晰、语义明确，适用于大多数基础使用场景。在批量处理中，这一命名方式能有效维持音视频配对关系，便于后期检索与管理。
然而，在实际工程落地中，用户往往需要更高的灵活性。通过修改后端代码中的文件命名函数，可实现高度定制化的输出格式，如加入项目前缀、序列编号、时间戳等关键字段，从而满足企业级内容生产的标准化要求。
此外，建议开发者在未来版本中引入：
- 前端命名模板配置界面
- 输出路径自定义选项
- 文件去重与冲突提示机制
这将进一步提升系统的易用性与专业性。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
