ComfyUI-ShellAgent-Plugin

This repository provides utility nodes for defining inputs and outputs in ComfyUI workflows. These nodes are essential for running ShellAgent apps with ComfyUI, but they can also be used independently to specify input/output variables and their requirements explicitly.

Installation

To install, either:

1. Download or clone this repository into the ComfyUI/custom_nodes/ directory.
2. Use the ComfyUI-Manager.

Features

Input Nodes

• Input Text
• Input Image
• Input Float
• Input Integer
• Input Video

Each input node supports setting a default value and additional configuration options.

Output Nodes

• Save Image
• Save Images
• Save Video - VHS (视频组合与加密节点)
• Output Text
• Output Float
• Output Integer

---

🎬 视频输出功能详解

Video Combine Encrypt 节点

这个节点将图像序列合成视频,支持多种格式和高级编码选项。

🎯 快速开始 (推荐新手)

基本配置:

1. 连接图像序列到 images 输入
2. 设置 frame_rate (默认24fps)
3. 选择 format: video/h264-mp4 (推荐,Mac/iOS兼容)
4. 点击执行

结果: 生成Mac兼容的高质量MP4视频

---

📋 支持的视频格式

格式	描述	Mac兼容	适用场景
video/h264-mp4 ✅	H.264 标准格式	✅ 完美	日常使用,社交媒体,网页
video/h265-mp4	H.265 高压缩	✅ 支持	节省空间,4K视频
video/vp9-webm	VP9 网页格式	✅ 支持	网页嵌入,流媒体
video/mov	QuickTime格式	✅ 完美	Mac原生格式
video/avi	AVI旧格式	✅ 支持	兼容性需求
video/h264-advanced ⚙️	H.264 高级模式	⚠️ 取决于配置	自定义参数
video/h264-high444 🎥	H.264 High 4:4:4	❌ 不兼容	专业后期制作
video/ffmpeg-manual 🔧	完全手动模式	⚠️ 取决于配置	专家级自定义

---

⚙️ 高级参数说明

当选择 h264-advanced 或 ffmpeg-manual 格式时,可以使用以下可选参数:

编码参数:

• advanced_preset: 编码速度 (ultrafast → veryslow)

  • medium (推荐): 速度与质量平衡
  • slow: 更好的质量,编码更慢
  • fast: 更快的编码,质量略低

• advanced_crf: 质量控制 (0-51)

  • 0: 无损 (文件巨大)
  • 18-20: 视觉无损 (推荐)
  • 23-28: 高质量,适中文件大小
  • 51: 最差质量

• advanced_pix_fmt: 像素格式

  • yuv420p ✅: Mac/iOS兼容 (推荐)
  • yuv444p ⚠️: 最高质量,但Mac不兼容
  • yuv444p10le: 10位高质量,Mac不兼容

• advanced_tune: 优化类型

  • none (默认): 通用优化
  • film: 适合电影内容
  • animation: 适合动画
  • grain: 保留胶片颗粒
  • stillimage: 适合静态图片序列

色彩参数:

• advanced_colorspace: 色彩空间 (bt709/bt601/bt2020nc)
• advanced_color_range: 色彩范围 (tv=16-235 / pc=0-255)

专家参数:

• advanced_x264_params: x264高级参数字符串
  • 例如: aq-mode=3:aq-strength=0.8:deblock=-1,-1

---

🎓 使用场景示例

场景1: 日常视频发布到社交媒体

format: video/h264-mp4
quality: 85
# 自动使用 yuv420p, Mac/手机完美播放

适用: YouTube, Bilibili, 抖音, 朋友圈

---

场景2: 高质量视频存档

format: video/h264-mp4
quality: 95
# 或使用高级模式:
format: video/h264-advanced
advanced_crf: 18
advanced_preset: slow
advanced_pix_fmt: yuv420p  # 保持兼容性

适用: 珍贵视频保存,原始素材备份

---

场景3: 专业后期制作 (仅Windows/Linux)

format: video/h264-high444
# 或使用高级模式:
format: video/h264-advanced
advanced_pix_fmt: yuv444p  # 最高色彩保真度
advanced_crf: 16
advanced_preset: slow

注意:

• ⚠️ 生成的视频Mac无法播放
• 适合作为后期制作的中间格式
• 最终发布前需转换为yuv420p

---

场景4: 绿幕抠像视频

format: video/h264-advanced
advanced_pix_fmt: yuv444p  # 色度边缘更锐利
advanced_tune: film
advanced_crf: 16

适用: 绿幕/蓝幕特效制作,色键抠像

---

🔍 YUV420p vs YUV444p 对比

特性	YUV420p (推荐)	YUV444p (专业)
Mac兼容性	✅ 完美支持	❌ 不支持
iOS兼容性	✅ 完美支持	❌ 不支持
文件大小	📉 小	📈 大50%
色彩精度	⭐⭐⭐⭐ (95%)	⭐⭐⭐⭐⭐ (100%)
适用场景	日常使用	专业后期

详细说明: 查看 VIDEO_FORMATS_GUIDE.md

---

💡 最佳实践建议

1. 默认配置: 90%的情况使用 video/h264-mp4 即可
2. 质量优先: 如需更高质量,调整 quality 参数到 95
3. Mac兼容: 永远选择 yuv420p 像素格式
4. 专业制作: 仅在Windows/Linux上使用 yuv444p
5. 发布前转换: yuv444p视频发布前转换为yuv420p

---

⚠️ 常见问题

Q: 视频在Mac上显示黑屏? A: 使用了yuv444p格式。解决:选择 video/h264-mp4 重新生成

Q: 如何获得最佳质量且Mac兼容? A: 使用 video/h264-advanced + yuv420p + crf=18 + preset=slow

Q: 专业后期用什么格式? A: 使用 video/h264-high444 或 advanced_pix_fmt=yuv444p

---

其他功能

加密功能

• encrypt: 启用后,输出文件将被XOR加密
• 加密文件无法直接播放或查看
• 使用相同密钥可解密

音频混流

• 连接 audio 输入可自动将音频混流到视频中
• 支持MP4, WebM, AVI格式
• 自动选择合适的音频编解码器

VAE解码

• 连接 vae 输入可自动解码latent图像
• 适用于Stable Diffusion等生成式模型的输出

---

📖 更多文档

• VIDEO_FORMATS_GUIDE.md: YUV格式详细解释和使用指南
• comfyui-h264-high444/: 独立的H.264 High 4:4:4编码节点

---

Convert Widgets to ShellAgent Inputs

A widget can be easily converted into a ShellAgent Input node of the appropriate type by right-clicking on the widget and selecting the option from the menu.