Initial commit — ComfyUI Discord bot + web UI
Full source for the-third-rev: Discord bot (discord.py), FastAPI web UI (React/TS/Vite/Tailwind), ComfyUI integration, generation history DB, preset manager, workflow inspector, and all supporting modules. Excluded from tracking: .env, invite_tokens.json, *.db (SQLite), current-workflow-changes.json, user_settings/, presets/, logs/, web-static/ (build output), frontend/node_modules/. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Khoa (Revenovich) Tran Gia
345
README.md
Normal file
345
README.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# Discord ComfyUI Bot
|
||||
|
||||
A Discord bot that integrates with ComfyUI to generate AI images and videos through Discord commands.
|
||||
|
||||
## Features
|
||||
|
||||
- 🎨 **Image Generation** - Generate images using simple prompts or complex workflows
|
||||
- 🎬 **Video Generation** - Support for video output workflows
|
||||
- 📝 **Workflow Management** - Load, modify, and execute ComfyUI workflows
|
||||
- 📤 **Image Upload** - Upload reference images directly through Discord
|
||||
- 📊 **Generation History** - Track and retrieve past generations
|
||||
- ⚙️ **Runtime Workflow Modification** - Change prompts, negative prompts, and input images on the fly
|
||||
- 🔄 **Job Queue System** - Sequential execution prevents server overload
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.9+
|
||||
- Discord Bot Token ([create one here](https://discord.com/developers/applications))
|
||||
- ComfyUI Server running and accessible
|
||||
- Required packages: `discord.py`, `aiohttp`, `websockets`, `python-dotenv`
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Clone or download this repository**
|
||||
|
||||
2. **Install dependencies**:
|
||||
```bash
|
||||
pip install discord.py aiohttp websockets python-dotenv
|
||||
```
|
||||
|
||||
3. **Create `.env` file** with your credentials:
|
||||
```bash
|
||||
DISCORD_BOT_TOKEN=your_discord_bot_token_here
|
||||
COMFY_SERVER=localhost:8188
|
||||
```
|
||||
|
||||
4. **Run the bot**:
|
||||
```bash
|
||||
python bot.py
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `.env` file in the project root:
|
||||
|
||||
```bash
|
||||
# Required
|
||||
DISCORD_BOT_TOKEN=your_discord_bot_token
|
||||
COMFY_SERVER=localhost:8188
|
||||
|
||||
# Optional
|
||||
WORKFLOW_FILE=wan2.2-fast.json
|
||||
COMFY_HISTORY_LIMIT=10
|
||||
COMFY_OUTPUT_PATH=C:\Users\YourName\Documents\ComfyUI\output
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|----------|----------|---------|-------------|
|
||||
| `DISCORD_BOT_TOKEN` | ✅ Yes | - | Discord bot authentication token |
|
||||
| `COMFY_SERVER` | ✅ Yes | - | ComfyUI server address (host:port) |
|
||||
| `WORKFLOW_FILE` | ❌ No | - | Path to workflow JSON to load at startup |
|
||||
| `COMFY_HISTORY_LIMIT` | ❌ No | `10` | Number of generations to keep in history |
|
||||
| `COMFY_OUTPUT_PATH` | ❌ No | `C:\Users\...\ComfyUI\output` | Path to ComfyUI output directory |
|
||||
|
||||
## Usage
|
||||
|
||||
All commands use the `ttr!` prefix.
|
||||
|
||||
### Basic Commands
|
||||
|
||||
```bash
|
||||
# Test if bot is working
|
||||
ttr!test
|
||||
|
||||
# Generate an image with a prompt
|
||||
ttr!generate prompt:a beautiful sunset over mountains
|
||||
|
||||
# Generate with negative prompt
|
||||
ttr!generate prompt:a cat negative_prompt:blurry, low quality
|
||||
|
||||
# Execute loaded workflow
|
||||
ttr!workflow-gen
|
||||
|
||||
# Queue multiple workflow runs
|
||||
ttr!workflow-gen queue:5
|
||||
```
|
||||
|
||||
### Workflow Management
|
||||
|
||||
```bash
|
||||
# Load a workflow from file
|
||||
ttr!workflow-load path/to/workflow.json
|
||||
|
||||
# Or attach a JSON file to the message:
|
||||
ttr!workflow-load
|
||||
[Attach: my_workflow.json]
|
||||
|
||||
# View current workflow changes
|
||||
ttr!get-current-workflow-changes type:all
|
||||
|
||||
# Set workflow parameters
|
||||
ttr!set-current-workflow-changes type:prompt A new prompt
|
||||
ttr!set-current-workflow-changes type:negative_prompt blurry
|
||||
ttr!set-current-workflow-changes type:input_image input/image.png
|
||||
```
|
||||
|
||||
### Image Upload
|
||||
|
||||
```bash
|
||||
# Upload images to ComfyUI
|
||||
ttr!upload
|
||||
[Attach: image1.png, image2.png]
|
||||
|
||||
# Upload to specific folder
|
||||
ttr!upload type:temp
|
||||
[Attach: reference.png]
|
||||
```
|
||||
|
||||
### History
|
||||
|
||||
```bash
|
||||
# View recent generations
|
||||
ttr!history
|
||||
|
||||
# Retrieve images from a past generation
|
||||
ttr!get-history <prompt_id>
|
||||
ttr!get-history 1 # By index
|
||||
```
|
||||
|
||||
### Command Aliases
|
||||
|
||||
Many commands have shorter aliases:
|
||||
|
||||
- `ttr!generate` → `ttr!gen`
|
||||
- `ttr!workflow-gen` → `ttr!wfg`
|
||||
- `ttr!workflow-load` → `ttr!wfl`
|
||||
- `ttr!get-history` → `ttr!gh`
|
||||
- `ttr!get-current-workflow-changes` → `ttr!gcwc`
|
||||
- `ttr!set-current-workflow-changes` → `ttr!scwc`
|
||||
|
||||
## Architecture
|
||||
|
||||
The bot is organized into focused, maintainable modules:
|
||||
|
||||
```
|
||||
the-third-rev/
|
||||
├── config.py # Configuration and constants
|
||||
├── job_queue.py # Job queue system
|
||||
├── workflow_manager.py # Workflow manipulation
|
||||
├── workflow_state.py # Runtime state management
|
||||
├── discord_utils.py # Discord utilities
|
||||
├── bot.py # Main entry point (~150 lines)
|
||||
├── comfy_client.py # ComfyUI API client (~650 lines)
|
||||
└── commands/ # Command handlers
|
||||
├── generation.py # Image/video generation
|
||||
├── workflow.py # Workflow management
|
||||
├── upload.py # File uploads
|
||||
├── history.py # History retrieval
|
||||
└── workflow_changes.py # State management
|
||||
```
|
||||
|
||||
### Key Design Principles
|
||||
|
||||
- **Dependency Injection** - Dependencies passed via constructor
|
||||
- **Single Responsibility** - Each module has one clear purpose
|
||||
- **Configuration Centralization** - All config in `config.py`
|
||||
- **Command Separation** - Commands grouped by functionality
|
||||
- **Type Safety** - Modern Python type hints throughout
|
||||
|
||||
## Development
|
||||
|
||||
### Adding a New Command
|
||||
|
||||
See `QUICK_START.md` for quick examples or `DEVELOPMENT.md` for comprehensive guide.
|
||||
|
||||
Basic example:
|
||||
|
||||
```python
|
||||
# commands/your_module.py
|
||||
|
||||
def setup_your_commands(bot, config):
|
||||
@bot.command(name="hello")
|
||||
async def hello(ctx):
|
||||
await ctx.reply("Hello!", mention_author=False)
|
||||
```
|
||||
|
||||
Register in `commands/__init__.py`:
|
||||
|
||||
```python
|
||||
from .your_module import setup_your_commands
|
||||
|
||||
def register_all_commands(bot, config):
|
||||
# ... existing ...
|
||||
setup_your_commands(bot, config)
|
||||
```
|
||||
|
||||
### Documentation
|
||||
|
||||
- **README.md** (this file) - Project overview and setup
|
||||
- **QUICK_START.md** - Quick reference for common tasks
|
||||
- **DEVELOPMENT.md** - Comprehensive development guide
|
||||
- **CLAUDE.md** - Architecture documentation for Claude Code
|
||||
|
||||
## Workflow System
|
||||
|
||||
The bot supports two generation modes:
|
||||
|
||||
### 1. Prompt Mode (Simple)
|
||||
|
||||
Uses a workflow template with a KSampler node:
|
||||
|
||||
```bash
|
||||
ttr!generate prompt:a cat negative_prompt:blurry
|
||||
```
|
||||
|
||||
The bot automatically finds and replaces:
|
||||
- Positive prompt in CLIPTextEncode node (title: "Positive Prompt")
|
||||
- Negative prompt in CLIPTextEncode node (title: "Negative Prompt")
|
||||
- Seed values (randomized each run)
|
||||
|
||||
### 2. Workflow Mode (Advanced)
|
||||
|
||||
Execute full workflow with runtime modifications:
|
||||
|
||||
```bash
|
||||
# Set workflow parameters
|
||||
ttr!set-current-workflow-changes type:prompt A beautiful landscape
|
||||
ttr!set-current-workflow-changes type:input_image input/reference.png
|
||||
|
||||
# Execute workflow
|
||||
ttr!workflow-gen
|
||||
```
|
||||
|
||||
The bot:
|
||||
1. Loads the workflow template
|
||||
2. Applies runtime changes from WorkflowStateManager
|
||||
3. Randomizes seeds
|
||||
4. Executes on ComfyUI server
|
||||
5. Returns images/videos
|
||||
|
||||
### Node Naming Conventions
|
||||
|
||||
For workflows to work with dynamic updates, nodes must follow naming conventions:
|
||||
|
||||
- **Positive Prompt**: CLIPTextEncode node with title containing "Positive Prompt"
|
||||
- **Negative Prompt**: CLIPTextEncode node with title containing "Negative Prompt"
|
||||
- **Input Image**: LoadImage node (any title)
|
||||
- **Seeds**: Any node with `inputs.seed` or `inputs.noise_seed`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot won't start
|
||||
|
||||
**Issue**: `AttributeError: module 'queue' has no attribute 'SimpleQueue'`
|
||||
|
||||
**Solution**: This was fixed by renaming `queue.py` to `job_queue.py`. Make sure you're using the latest version.
|
||||
|
||||
### ComfyUI connection issues
|
||||
|
||||
**Issue**: `ComfyUI client is not configured`
|
||||
|
||||
**Solution**:
|
||||
1. Check `.env` file has `DISCORD_BOT_TOKEN` and `COMFY_SERVER`
|
||||
2. Verify ComfyUI server is running
|
||||
3. Test connection: `curl http://localhost:8188`
|
||||
|
||||
### Commands not responding
|
||||
|
||||
**Issue**: Bot online but commands don't work
|
||||
|
||||
**Solution**:
|
||||
1. Check bot has Message Content Intent enabled in Discord Developer Portal
|
||||
2. Verify bot has permissions in Discord server
|
||||
3. Check console logs for errors
|
||||
|
||||
### Video files not found
|
||||
|
||||
**Issue**: `Failed to read video file`
|
||||
|
||||
**Solution**:
|
||||
1. Set `COMFY_OUTPUT_PATH` in `.env` to your ComfyUI output directory
|
||||
2. Check path uses correct format for your OS
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Batch Generation
|
||||
|
||||
Queue multiple workflow runs:
|
||||
|
||||
```bash
|
||||
ttr!workflow-gen queue:10
|
||||
```
|
||||
|
||||
Each run uses randomized seeds for variation.
|
||||
|
||||
### Custom Workflows
|
||||
|
||||
1. Design workflow in ComfyUI
|
||||
2. Export as API format (Save → API Format)
|
||||
3. Load in bot:
|
||||
```bash
|
||||
ttr!workflow-load path/to/workflow.json
|
||||
```
|
||||
4. Modify at runtime:
|
||||
```bash
|
||||
ttr!set-current-workflow-changes type:prompt My prompt
|
||||
ttr!workflow-gen
|
||||
```
|
||||
|
||||
### State Persistence
|
||||
|
||||
Workflow changes are automatically saved to `current-workflow-changes.json` and persist across bot restarts.
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! Please:
|
||||
|
||||
1. Read `DEVELOPMENT.md` for coding guidelines
|
||||
2. Follow existing code style and patterns
|
||||
3. Test your changes thoroughly
|
||||
4. Update documentation as needed
|
||||
|
||||
## License
|
||||
|
||||
[Your License Here]
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
- Check the troubleshooting section above
|
||||
- Review `DEVELOPMENT.md` for implementation details
|
||||
- Check ComfyUI documentation for workflow issues
|
||||
- Open an issue on GitHub
|
||||
|
||||
## Credits
|
||||
|
||||
Built with:
|
||||
- [discord.py](https://github.com/Rapptz/discord.py) - Discord API wrapper
|
||||
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - Stable Diffusion GUI
|
||||
- [aiohttp](https://github.com/aio-libs/aiohttp) - Async HTTP client
|
||||
- [websockets](https://github.com/python-websockets/websockets) - WebSocket implementation
|
||||
Reference in New Issue
Block a user