DramaClaw 的流水线卡在素材导入这步 / 多半是命名和帧率没对齐

素材导入中断时，先把问题从“整批失败”缩小到“某一个文件”。DramaClaw 这类流水线在导入阶段一般会逐个文件读取规格并登记，文件名里带空格、中文括号、#、& 之类字符，或者一批素材里混了不同帧率、不同像素格式，都可能让某个文件读不出来，后面的环节跟着停。可以先看导入记录定位到那个文件，用 ffprobe 读出它的实际参数，把命名和帧率统一后再重跑一次导入。

导入卡在素材导入这步，通常是单个文件的命名或规格不合规，不必把整批素材都当成坏文件。做法是先从导入记录里找出最后一个成功条目和紧随其后的失败条目，用 ffprobe 读出该文件的帧率、分辨率、编码与像素格式，再把命名统一为字母、数字、下划线、连字符，把混合帧率转成统一规格后重新导入，最后用导入记录的条目数、文件数、总时长三项对比确认。若流水线其他环节引用了旧文件名，重命名前需要一并排查。

在导入记录里确认卡在第几个文件

导入记录通常有两种条目：成功条目会带文件名、时长或帧数、状态字段；失败条目则带错误信息、跳过标记，或者干脆停在中间没有后续记录。先把当前这次导入的日志原样保存一份，再从记录尾部往前找：最后一条状态为成功的条目，和它下面第一条失败或缺失的条目，中间那个文件就是优先排查对象。

核对“第几个”是按什么顺序算的：多数流水线按文件名排序处理，而不是按拖入顺序，所以要拿目录清单对照排序位置，别直接数拖进去的先后。
把候选文件单独放进一个只有它自己的目录里跑一次导入，能复现就说明问题在这个文件；不能复现，再回到整批里看是不是顺序或依赖关系导致的。
失败条目里的错误文本要原样记录，后面转码或改名之后可以用它对比是否还出现同样的报错。

用探测命令读出每个素材的帧率、分辨率与编码

定位到文件之后，用 ffprobe 读它真实的视频参数，不要凭文件名或剪辑软件里看到的估计。单文件读取：

ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,width,height,r_frame_rate,avg_frame_rate,pix_fmt \
  -show_entries format=duration \
  -of default=noprint_wrappers=1 "/path/to/import/clip_0001.mp4"

整批扫一遍，把结果贴在一起对比，不一致的那几个会很明显：

for f in /path/to/import/*.mp4; do
  echo "== $f"
  ffprobe -v error -select_streams v:0 \
    -show_entries stream=codec_name,width,height,r_frame_rate,avg_frame_rate,pix_fmt \
    -of csv=p=0 "$f"
done

结果里主要看这几个字段：r_frame_rate 是分数形式（例如 30000/1001、25/1），要按分数理解，不要直接当小数看；avg_frame_rate 与 r_frame_rate 明显不一致，通常说明素材是可变帧率；pix_fmt 常见 yuv420p，出现 10bit 或 422 之类要和流水线其余素材比较；codec_name 混用 h264 与 hevc 也比较容易出问题；width/height 用于确认分辨率是否统一。带音轨的素材再看一眼采样率：

ffprobe -v error -select_streams a:0 \
  -show_entries stream=codec_name,sample_rate,channels \
  -of csv=p=0 "/path/to/import/clip_0001.mp4"

统一命名规则，去掉特殊字符与空格

命名不合规导致的失败，往往在路径解析这一步就发生，跟文件内容无关。建议文件名只保留 A-Z a-z 0-9 _ - 和扩展名，序号部分补齐位数，扩展名统一小写；空格、中文括号、#、&、加号、单双引号、emoji 都建议在导入前去掉。目录层级也尽量浅，避免路径过长。

批量重命名前先整目录备份一份，改坏了还能退回：

mkdir -p /path/to/backup_originals
cp -a /path/to/import/. /path/to/backup_originals/

重命名脚本先做一遍空跑，确认新旧名字对应关系没问题，再去掉 echo 真正执行：

i=0
for f in /path/to/import/*; do
  ext="${f##*.}"
  i=$((i+1))
  printf -v n "%04d" "$i"
  echo mv -- "$f" "/path/to/import/clip_${n}.${ext}"
done

改完之后抽查两件事：一是列一遍文件名，看是否还有空格和非常规字符残留；二是确认文件总数与备份目录一致，没有在重命名过程中互相覆盖。如果流水线里有清单文件、同名字幕或外部对照表引用了原文件名，这些也要同步更新，否则改名本身会变成新的失败点。

把混合帧率素材转成统一规格再导入

命名修好之后仍然失败的，多半是帧率或像素格式不一致。流水线内部通常按一个固定时间基推算帧号和时长，混进可变帧率或另一个帧率的素材，时间轴就对不上。建议把整批素材都转成同一帧率、同一像素格式再导入，下面示例选定 25fps 与 1920×1080，实际取值按项目要求替换：

ffmpeg -i "/path/to/import/clip_0001.mp4" \
  -vf "fps=25,scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,setsar=1" \
  -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium \
  -c:a aac -ar 48000 -ac 2 \
  -movflags +faststart \
  "/path/to/normalized/clip_0001.mp4"

其中 fps 过滤器负责把可变帧率压成恒定帧率；没有音轨的素材去掉 -c:a 相关参数，或改用 -an，免得转码阶段报错。转完之后用第 2 节的 ffprobe 命令复核：r_frame_rate 与 avg_frame_rate 应当一致且等于目标帧率，pix_fmt、分辨率、编码格式应当是设定的值，duration 与源文件相差不大（有剪辑裁切时以实际内容为准）。不要一次转完整批，先转一个文件导入验证，通过后再批量处理。

重新导入并对比导入记录完成验证

重跑时建议换一个新的导入批次或清空上次的导入结果，避免和旧记录混在一起看不出差别。顺序是先导单个此前失败的文件，确认它这次能过；再把整批导进去。

核对条目数：导入记录里的条目数量应等于目录里的文件数量，用 ls -1 /path/to/normalized | wc -l 数一遍做对照。
核对状态：逐条看是否还有失败、跳过或警告条目，重点确认之前记下的那条错误文本没有再出现。
核对时长：把导入记录里的总时长与素材实际时长之和比较，两者接近说明没有文件被截断或漏读。

素材时长求和可以用 ffprobe 累加：

total=0
for f in /path/to/normalized/*.mp4; do
  d=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$f")
  total=$(awk -v a="$total" -v b="$d" 'BEGIN{print a+b}')
done
echo "$total"

如果重跑后失败条目换成了另一批文件，说明问题不在单个素材，而要回到流水线配置侧检查：导入目录的扫描规则、允许的扩展名列表、帧率上限或时长阈值这类参数，需要结合具体环境确认。改名和转码都应保留原始备份，确认流水线后续环节也按新文件名接通之后，再考虑清理备份。