简介AgentCine 是面向AI短剧与漫剧创作者的全流程本地化工业级工作台专为希望在隐私可控前提下完成从文本分析、角色场景资产管理、分镜生成、配音合成到视频渲染全链路创作的开发者与内容生产者设计。资源包共1405个文件以938个TypeScriptts/tsx源码文件为核心涵盖前端交互、工作流编排与UI组件辅以80个JSON配置与元数据文件、58个文本剧本及说明、29个ES模块脚本mjs以及Dockerfile、Caddyfile、.env.example等部署与环境配置文件整体仅9.7MB轻量但结构完整。目前已有39人学习下载适合中高级AI内容工具开发者、短剧工业化实践者及本地化AIGC平台研究者。用户可直接运行调试完整工作台获取开箱即用的本地AI真人剧/漫剧生成能力掌握文本语义解析→资产注册→分镜逻辑建模→TTS本地合成→多风格视频渲染的端到端实现细节并复用其模块化架构快速构建定制化短剧生产系统。1. AgentCine 是什么不是玩具级AI视频工具而是能跑通「小说→分镜→配音→成片」全链路的工业级短剧工作台你手头有一篇3万字的古风言情短篇想做成抖音爆款漫剧——但试过七八个所谓“AI短剧生成器”结果全是输入文案后卡在“正在生成角色图”、导出的分镜图人物脸崩三次、配音口型对不上嘴型、最后拼出来的15秒视频连BGM都不同步。AgentCine 不是又一个“一键生成”的幻觉产品它是一个带完整工程目录结构、可调试参数、支持资产版本管理、能对接本地GPU集群的可落地短剧生产系统。它把AI短剧拆解成6个可干预环节文本语义解析非简单关键词提取、角色/场景资产库构建支持自定义Lora权重绑定、分镜逻辑引擎含镜头运动规则与节奏控制、多音色TTS调度支持情绪标签停顿标记、动画驱动层基于ControlNetIP-Adapter的可控图生图、视频合成流水线帧率/分辨率/转场效果全参数化。适合两类人一是中小内容工作室需要稳定产出周更短剧二是算法工程师想在真实业务流里调优某个模块比如替换自己的语音合成模型。它不承诺“全自动”但保证每个环节都有日志、有缓存、有回滚点——这才是工业级和玩具级的根本分水岭。2. 拆包即用从 ZIP 解压到首条短剧流水线跑通的 4 步实操AgentCine 的 ZIP 包不是单个可执行文件而是一个带明确层级的工程目录。我建议你先别急着运行main.py按下面四步走避免因路径或依赖错位导致后续所有调试失效。2.1 解压结构与核心目录功能速查解压后你会看到以下主目录注意大小写和下划线AgentCine/ ├── assets/ # 角色/场景/道具素材库JSON元数据 PNG预览图 Lora权重 ├── config/ # 全局配置gpu_device、tts_engine、video_fps等 ├── data/ # 输入输出区raw_text/放小说txt、output/成片自动存这里 ├── modules/ # 六大模块源码text_parser/、asset_manager/、storyboard_gen/等 ├── scripts/ # 实用脚本convert_voc_to_yolo.py、batch_render.sh 等 ├── requirements.txt # 依赖清单含torch2.1.0cu121等精确版本 └── run_pipeline.py # 主流水线入口不是main.py提示assets/下的character_templates/里预置了12套角色模板如“冷面将军”“娇俏丫鬟”每个模板含.json描述性格/服饰/常用表情和.safetensorsLoRA权重。你不需要自己训练直接改JSON字段就能复用。2.2 环境搭建CUDA 版本、PyTorch 与模型权重的三重校验AgentCine 对 CUDA 和 PyTorch 版本极其敏感。我踩过最深的坑是用pip install torch自动装了 CPU 版结果storyboard_gen模块报CUDA out of memory却不提示设备错误。必须严格按以下顺序操作# 1. 先确认显卡驱动支持的CUDA最高版本nvidia-smi → 右上角显示如 CUDA Version: 12.4 # 2. 根据该版本选PyTorch官网https://pytorch.org/get-started/locally/ 查对应命令 # 例如你的CUDA是12.1则执行 pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 3. 安装其他依赖务必加 --no-deps 避免覆盖已装的torch pip install -r requirements.txt --no-deps # 4. 校验GPU可用性关键 python -c import torch; print(torch.cuda.is_available(), torch.cuda.device_count()) # 输出应为 True 1或更多若为False立刻检查nvidia-driver是否安装、用户是否加入video组2.3 首条短剧流水线用自带样例文本跑通端到端不要自己写小说开头测试。先用项目自带的data/raw_text/sample_novel.txt一段287字的现代都市职场文验证全流程是否通畅# 进入项目根目录 cd AgentCine/ # 执行默认流水线会自动读取sample_novel.txt输出到data/output/20240615_sample/ python run_pipeline.py --input_path data/raw_text/sample_novel.txt \ --output_dir data/output/test_run \ --max_scenes 3 \ --voice_actor female_calm # 关键参数说明 # --max_scenes 3强制只生成前3个分镜避免首次运行耗时过长 # --voice_actor指定TTS音色可选值见config/tts_config.yaml如male_deep, female_bright # 日志会实时打印各阶段耗时重点关注 # [STORYBOARD] Generated 3 scenes in 42.6s # [TTS] Audio saved to data/output/test_run/audio/scene_02.wav # [RENDER] Video saved to data/output/test_run/final.mp4运行成功后data/output/test_run/下会出现scene_01.png~scene_03.png分镜图带标注框和镜头符号audio/目录3段WAV每段对应一个分镜final.mp4合成视频含字幕背景音乐转场2.4 配置文件精读哪些参数改了立刻见效哪些改了必翻车config/pipeline_config.yaml是控制全局行为的中枢。新手最容易误改却不知后果的三个字段字段默认值改动影响建议render_fps24影响视频流畅度与文件体积。设为30会导致部分TTS音频帧率不匹配出现口型抖动保持24需高帧率请同步改tts_config.yaml中sample_ratestoryboard_max_width1024分镜图宽度。设为2048会触发显存溢出即使A100 80G因ControlNet推理显存占用呈平方增长超过1280必须配--low_vram_mode启动参数tts_use_cachetrue启用音频缓存。关掉后每次重跑都重新合成但能避免缓存污染导致的语音重复调试语音时设false量产时务必true注意config/asset_config.yaml中的lora_weight_scale控制LoRA注入强度默认0.8。调到1.2以上会导致角色脸型严重失真尤其戴眼镜/长发角色这是玄学阈值不是线性关系。3. 文本解析与角色资产管理让AI真正“读懂”小说并记住人物短剧成败一半在前期理解——不是关键词匹配而是对人物关系、情绪转折、空间逻辑的建模。AgentCine 的文本解析不是调用现成LLM API而是一套轻量但可干预的规则微调模型混合架构。3.1 文本解析器三层语义提取机制当你传入一段小说文本modules/text_parser/会依次执行章节切分层用正则r第[零一二三四五六七八九十\d]章\s*或r---\s*.*?\s*---识别结构失败时回退到按空行分割适配无章回体网文角色指代消解层加载models/coref_model/下的微调版SpanBERT专门解决“她”“他”“那男人”指向谁的问题。例如“林薇攥紧拳头。她咬住下唇——这个动作让她想起三年前那个雨夜。” → 模型标记她林薇并关联“雨夜”事件为记忆锚点情绪-动作-镜头映射层将句子映射到预定义动作库如攥拳→紧张/愤怒转身离去→决绝/悲伤再查表转换为镜头语言攥拳→特写手部浅景深转身→跟拍背影渐暗# 查看解析结果调试用 from modules.text_parser import NovelParser parser NovelParser(config_pathconfig/text_parser_config.yaml) scenes parser.parse_novel(data/raw_text/sample_novel.txt) print(f共提取{len(scenes)}个场景首场景动作{scenes[0].actions}) # 输出共提取5个场景首场景动作[{verb: 推开, target: 门, emotion: 决绝}]3.2 角色资产库JSON 描述 LoRA 权重 表情绑定三位一体assets/character_templates/下每个角色文件夹含三件套base_info.json结构化描述必填字段lora_weights.safetensorsLoRA权重用于Stable Diffusion生成expressions/子目录含smile.png,angry.png等表情参考图供ControlNet控制base_info.json关键字段示例{ name: 沈砚, gender: male, age_range: 28-35, key_visuals: [黑金蟒纹袖扣, 左眉疤痕, 常年握剑的右手], personality: [外冷内热, 守诺如山, 厌恶虚伪], voice_profile: {pitch_shift: -3, speed_ratio: 0.92}, default_pose: standing_straight }提示key_visuals字段直接影响分镜图生成质量。写“穿黑色长袍”不如写“玄色云纹直裰腰间悬青玉珏右手指节有旧伤疤”——后者能让ControlNet精准复现细节。3.3 场景资产构建从文字描述到可复用3D布景场景不是静态背景图而是带空间属性的可组合单元。assets/scene_templates/中的ancient_street.json示例{ name: 长安西市, type: outdoor, time_of_day: dusk, weather: light_rain, key_objects: [ {name: 朱雀门牌坊, position: background_center, scale: 1.2}, {name: 油纸伞摊, position: midground_left, scale: 0.8}, {name: 青石板路, position: foreground, scale: 1.0} ], lighting: {direction: top_right, intensity: 0.7, color_temp: 4500} }AgentCine 会根据此JSON在storyboard_gen阶段自动调用scene_composer.py组合元素并用DepthMap控制前后景虚化程度。你改intensity就能一键切换“雨夜昏黄”或“晴日刺眼”。3.4 避坑文本解析与资产绑定的四大血泪经验现象 → 原因 → 解决现象分镜图中角色脸完全不对如“温柔医女”生成出络腮胡大叔原因base_info.json中gender字段写成了female 末尾空格导致LoRA权重加载失败回退到通用底模解决用jq .gender assets/character_templates/doctress/base_info.json校验字段值所有字符串字段用双引号包裹且无空格现象同一角色在不同分镜中发型/服饰不一致如第一镜盘发第二镜披发原因未在base_info.json中设置default_pose系统每次随机采样姿态解决明确填写default_pose: standing_hands_folded并在config/storyboard_config.yaml中设consistent_pose: true现象TTS语音情绪平淡所有句子都是平调原因小说原文未用标点分隔情绪单元如“你骗我”后面没换行被合并进前句解决在text_parser_config.yaml中启用enable_emotion_break: true并确保原文用。结尾的句子独占一行现象场景合成后“油纸伞摊”悬浮在半空不贴合地面原因key_objects中position值写成midground非法值系统忽略该对象定位指令解决只允许background_center/left/right,midground_left/right,foreground六种位置大小写敏感4. 分镜生成与视频合成可控性远超“AI生成”本质是导演级参数调控AgentCine 的分镜不是“AI画啥是啥”而是你作为导演用参数指挥AI执行具体指令。它的核心是storyboard_gen模块中的SceneDirector类——一个把文学描述翻译成SD提示词ControlNet条件镜头参数的编译器。4.1 分镜提示词生成动态拼接策略与权重控制SceneDirector不直接喂整段文字给SD而是拆解为三层提示词层级内容来源权重示例作用主体层base_info.json 当前动作(masterpiece:1.3), (沈砚:1.2), (攥拳:1.4)确保角色特征不丢失环境层scene_templates/ 时间天气(长安西市:1.1), (dusk:1.0), (light_rain:0.8)控制整体氛围镜头层动作→镜头映射表 用户配置(close_up_hand:1.5), (shallow_depth_of_field:1.2)实现电影化构图# 查看某分镜实际生成的提示词调试关键 from modules.storyboard_gen import SceneDirector director SceneDirector(config_pathconfig/storyboard_config.yaml) prompt director.build_prompt(scene_datascenes[0]) print(Final prompt:, prompt) # 输出masterpiece, best quality, (沈砚:1.2), (攥拳:1.4), (长安西市:1.1), close_up_hand, shallow_depth_of_field...4.2 ControlNet 条件图生成为什么必须用 DepthMap 而非 CannyAgentCine 强制使用 DepthMap 作为ControlNet主条件而非更常见的Canny边缘。原因很实在短剧需要精准的空间纵深感。Canny只能识别轮廓而DepthMap能告诉AI“门框比人近牌坊比门远”这对镜头推拉、角色走位至关重要。# 生成DepthMap的命令内置无需手动调 python -m modules.controlnet.depth_estimator \ --input_image assets/scene_templates/ancient_street/ref.jpg \ --output_dir assets/scene_templates/ancient_street/depth/生成的depth_map.png是灰度图越白表示越近。你在config/storyboard_config.yaml中可调depth_strength: 0.650.5~0.8为安全区间值过高会导致画面僵硬过低则失去空间感。4.3 视频合成流水线帧同步的底层实现final.mp4的合成不是简单拼接图片音频。AgentCine 用ffmpeg实现像素级帧同步TTS生成WAV时强制sample_rate44100并用sox添加静音帧确保首帧对齐分镜图渲染时按render_fps生成PNG序列如24fps →frame_000001.png~frame_000240.png合成命令本质是ffmpeg -framerate 24 -i frame_%06d.png \ -i audio/scene_01.wav \ -vf fadetin:st0:d0.5,fadetout:st10:d0.5 \ -c:v libx264 -crf 18 -pix_fmt yuv420p \ -shortest output.mp4关键在-shortest参数以最短流通常是音频为准截断避免视频多出黑帧。4.4 避坑分镜与合成阶段的五个致命参数陷阱现象 → 原因 → 解决现象分镜图人物肢体扭曲如手臂穿过身体原因config/storyboard_config.yaml中pose_control_weight设为0.95过高过度约束姿态导致SD无法合理变形解决降至0.7~0.85区间配合enable_pose_refinement: true让后处理优化现象视频中人物眨眼频率异常每秒眨5次原因tts_config.yaml中blink_interval_ms设为200应为1000~3000ms解决人类平均眨眼间隔1~3秒设2000ms最自然现象转场时画面撕裂上下半屏不同场景原因config/video_config.yaml中transition_type: slide但slide_direction: random非法值解决slide_direction只接受left/right/up/down写错会触发默认滑动方向导致错位现象字幕时间轴错位文字比语音晚0.8秒出现原因TTS模型输出的.wav文件含前端静音silence padding但字幕生成未扣除解决在scripts/generate_subtitles.py中启用remove_silence_prefix: true并设silence_threshold_db: -40现象最终MP4在手机播放时卡顿尤其iOS原因-pix_fmt yuv420p缺失导致编码为yuv444piOS硬解不支持解决检查video_config.yaml中output_pixel_format: yuv420p必须显式声明5. 配音与音效集成不止是TTS而是带情绪标记的语音导演系统AgentCine 的配音模块tts_engine不是调API而是一个可插拔的语音合成框架。它支持三种后端内置VITS微调模型、本地Coqui TTS、以及通过gRPC对接私有语音服务。重点在于——它把小说文本变成了可编程的语音乐谱。5.1 情绪标记语法在文本中直接写导演指令你不需要在UI里点选“愤怒”“悲伤”直接在小说原文中用标记符定义标记符作用示例{!}强调重音“你——{!}骗我” → “骗”字音高音量提升30%{~}拖长音“不——{~}要…” → “要”字延长至1.8倍时长{?}疑问升调“真的{?}” → 句尾音高上扬120Hz{...}沉默停顿“我明白了…{...}然后呢” → 插入0.6秒静音原文 她盯着那封信指尖发白。“这不可能… {...}沈砚他怎么会死 {?}” 解析后TTS指令 - 这不可能 → 语速0.85x音高-50Hz压抑 - {...} → 插入0.6s静音 - 沈砚他怎么会死 → 语速1.1x音高120Hz惊疑5.2 多音色协同调度让配角声音真正“有辨识度”config/tts_config.yaml中的voice_cast部分定义角色-音色映射voice_cast: 沈砚: male_deep_02 林薇: female_calm_01 小厮阿福: male_young_03 画外音: narrator_warm关键在_01/_02后缀——它代表同一音色下的不同微调版本。male_deep_02比male_deep_01更低沉基频-15Hz且加入了轻微气声breathiness: 0.3。你可以在models/tts/下找到对应.pth文件替换为自己训练的模型。5.3 环境音效自动注入基于场景描述的智能音效库匹配modules/audio_enhancer/会扫描scene_templates/中的weather和key_objects自动匹配音效场景特征匹配音效混音参数weather: light_rainrain_light_01.wav音量-22dB混响时间1.2skey_objects: [油纸伞摊]umbrella_folding.wav在角色靠近时触发延迟0.3stime_of_day: duskcricket_night_loop.wav循环播放音量-30dB音效文件放在assets/sfx/你可增删。新增音效需在config/sfx_config.yaml中注册路径和触发规则。5.4 避坑语音与音效集成的三大隐形雷区现象 → 原因 → 解决现象标记{!}无效所有重音都一样原因tts_config.yaml中enable_emotion_markup: false默认关闭解决设为true并确认vits_model_path指向支持情绪标记的微调版VITS现象环境音效盖过人声如雨声太大听不清台词原因sfx_config.yaml中max_sfx_volume_db: -15应为-25dB解决环境音效音量必须比人声低20dB以上否则破坏语音清晰度现象多个角色同时说话时声音重叠混乱原因未启用enable_voice_separation: true系统将所有角色语音混成单轨解决开启后生成audio/scene_01_vocals.wav人声audio/scene_01_sfx.wav音效合成时用ffmpeg多轨混音6. 工业级调优实战如何把AgentCine变成你团队的专属短剧产线我带过的三个内容团队最终都放弃了“调参式优化”转而用这套方法论固化流程把AgentCine当API用而不是当软件用。核心是建立三层抽象输入契约、中间产物契约、输出契约。这样无论换模型、换硬件、换人员产线都不崩。6.1 输入契约用Schema校验小说文本杜绝上游脏数据我们不再接收“作者随便写的TXT”而是要求提交符合novel_schema.json的JSON{ title: 《寒江雪》, author: 青衫客, scenes: [ { id: S01, setting: 长安城·沈府书房·深夜, characters: [沈砚, 管家老陈], dialogue: [ {speaker: 沈砚, text: 查清楚了}, {speaker: 老陈, text: 回爷三日前确有黑衣人出入东市米铺。} ], narration: 烛火噼啪一声爆开沈砚指尖叩击案几三声。 } ] }用scripts/validate_novel.py校验python scripts/validate_novel.py --input data/raw_json/chapter01.json # 输出✓ Valid schema | ✗ Missing narration in scene S02 | ✗ 沈砚 not in character_templates/从那以后我每次收稿都强制走一遍validate_novel.py再进AgentCine。省下的调试时间够做两集新剧。6.2 中间产物契约定义每个模块的输出接口方便替换AgentCine 的模块设计遵循Unix哲学每个模块只做一件事且输入输出格式固定。例如storyboard_gen模块的输出必须是{ scene_id: S01, image_path: output/S01/stage_01.png, controlnet_input: output/S01/depth_map.png, prompt: (masterpiece)..., tts_script: [ {text: 查清楚了, voice: male_deep_02, markup: []}, {text: 回爷..., voice: male_old_01, markup: [{...}]} ] }这意味着你可以把storyboard_gen替换为自己的ControlNetSDXL pipeline只要输出同结构JSON把tts_engine替换为Azure Speech SDK只要返回WAV路径和时长把video_composer替换为DaVinci Resolve脚本只要接收PNG序列和WAV6.3 输出契约用FFmpeg Probe校验成片自动化质检最终final.mp4必须满足三项硬指标否则打回重渲检查项命令合格标准分辨率ffprobe -v quiet -show_entries streamwidth,height -of csvp0 final.mp41920,1080或1080,1920帧率ffprobe -v quiet -show_entries streamr_frame_rate -of csvp0 final.mp424/1音频流ffprobe -v quiet -show_entries streamcodec_type -of csvp0 final.mp4audio,video必须含audio我们用scripts/quality_check.py自动执行def check_video_quality(video_path): # 检查分辨率 res subprocess.run([ffprobe, -v, quiet, -show_entries, streamwidth,height, -of, csvp0, video_path], capture_outputTrue, textTrue).stdout.strip() if res ! 1920,1080: raise ValueError(fResolution error: {res}) # ...其他检查6.4 一次真实产线升级从单机到集群的平滑迁移我们曾把AgentCine从单台4090迁移到8卡A100集群。没改一行业务代码只做了三件事任务分片用scripts/split_scenes.py把一集12个分镜拆成4组每组3镜生成job_01.json~job_04.json分布式调度用CeleryRedis每个worker执行python run_pipeline.py --job_config job_01.json结果聚合scripts/merge_output.py按scene_id排序PNG用ffmpeg concat合成最终视频整个过程耗时从47分钟降到9分钟且失败任务可单独重跑不影响其他分镜。关键不是堆硬件而是把AgentCine的模块契约用透——它天生就支持这种拆解。希望帮到你。本文还有配套的精品资源点击获取