nodes/myshell-ai-ComfyUI-ShellAgent-Plugin
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
6889f22fcf89ca734de491580a7a4485adf0fe31
myshell-ai-ComfyUI-ShellAge…/README.md
T
ArxchiboboandClaude Sonnet 4.5 a15d4b255e feat: 集成H.264高级编码功能,支持yuv420p/yuv444p格式 
新增功能:
- 添加3个新视频格式: h264-advanced, h264-high444, ffmpeg-manual
- 新增9个高级参数: preset, tune, crf, pix_fmt, colorspace等
- 支持yuv420p (Mac兼容) 和 yuv444p (专业后期) 像素格式
- 实现三级模式: 标准模式/高级模式/手动模式
- 自动处理High444 profile和色彩元数据

代码改进:
- 优化VIDEO_FORMATS字典,添加兼容性标记
- 扩展INPUT_TYPES,添加完整的高级参数支持
- 增强_create_video方法,智能处理不同模式
- 调整默认CRF值从19到20 (Mac推荐值)

文档新增:
- VIDEO_FORMATS_GUIDE.md: YUV格式完整教程
- QUICK_REFERENCE.md: 快速参考卡片
- USAGE_GUIDE.md: 详细使用指南
- INTEGRATION_SUMMARY.md: 技术整合总结
- COMPLETION_REPORT.md: 完成报告

工具脚本:
- simple_check.py: 简单验证脚本
- verify_integration.py: 完整验证脚本

h264-high444模块:
- 独立的H.264 High 4:4:4编码节点
- 支持专业yuv444p格式
- 完整的色彩管理和高级参数

技术亮点:
- 向后兼容,不影响现有工作流
- 默认配置确保Mac/iOS兼容性
- 清晰的兼容性标注和中文提示
- 完善的三层文档体系

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-04 13:34:12 +08:00

235 lines
6.1 KiB
Markdown
Raw Blame History

# ComfyUI-ShellAgent-Plugin
This repository provides utility nodes for defining inputs and outputs in ComfyUI workflows. These nodes are essential for running [ShellAgent](https://github.com/myshell-ai/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: 日常视频发布到社交媒体
```yaml
format: video/h264-mp4
quality: 85
# 自动使用 yuv420p, Mac/手机完美播放
```
**适用**: YouTube, Bilibili, 抖音, 朋友圈
---
##### 场景2: 高质量视频存档
```yaml
format: video/h264-mp4
quality: 95
# 或使用高级模式:
format: video/h264-advanced
advanced_crf: 18
advanced_preset: slow
advanced_pix_fmt: yuv420p # 保持兼容性
```
**适用**: 珍贵视频保存,原始素材备份
---
##### 场景3: 专业后期制作 (仅Windows/Linux)
```yaml
format: video/h264-high444
# 或使用高级模式:
format: video/h264-advanced
advanced_pix_fmt: yuv444p # 最高色彩保真度
advanced_crf: 16
advanced_preset: slow
```
**注意**:
- ⚠️ 生成的视频Mac无法播放
- 适合作为后期制作的中间格式
- 最终发布前需转换为yuv420p
---
##### 场景4: 绿幕抠像视频
```yaml
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.
Reference in New Issue View Git Blame Copy Permalink