wow that took awhile
This commit is contained in:
cottongin
141
ROOM_CODE_IMAGE_FEATURE.md
Normal file
141
ROOM_CODE_IMAGE_FEATURE.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Room Code Image Feature
|
||||
|
||||
## Overview
|
||||
|
||||
The bot now supports displaying Jackbox room codes as images in Kosmi chat (with fallback to IRC text formatting for IRC chat).
|
||||
|
||||
## How It Works
|
||||
|
||||
### For Kosmi Chat (with `EnableRoomCodeImage=true`)
|
||||
|
||||
1. **Generate**: When a new game is added, the bot generates a PNG image of the room code using a monospace font (black background, white text)
|
||||
2. **Upload**: The image is uploaded to Kosmi's CDN at `https://img.kosmi.io/`
|
||||
3. **Broadcast**: The bot sends two messages:
|
||||
- First: The game announcement (e.g., "🎮 Coming up next: Drawful 2!")
|
||||
- Second: The image URL (Kosmi automatically displays it as a thumbnail)
|
||||
|
||||
### For IRC Chat (always)
|
||||
|
||||
Room codes are displayed with IRC formatting:
|
||||
- **Bold** (`\x02`)
|
||||
- **Monospace** (`\x11`)
|
||||
- **Reset** (`\x0F`)
|
||||
|
||||
Example: `\x02\x11ROOM42\x0F` displays as **`ROOM42`** in IRC clients
|
||||
|
||||
### Fallback Behavior
|
||||
|
||||
If image generation or upload fails:
|
||||
- The bot falls back to IRC text formatting for all chats
|
||||
- An error is logged but the announcement still goes through
|
||||
|
||||
## Configuration
|
||||
|
||||
In `matterbridge.toml`:
|
||||
|
||||
```toml
|
||||
[jackbox]
|
||||
Enabled=true
|
||||
APIURL="https://your-jackbox-api.com"
|
||||
AdminPassword="your-password"
|
||||
UseWebSocket=true
|
||||
EnableRoomCodeImage=false # Set to true to enable image uploads
|
||||
```
|
||||
|
||||
## Files Involved
|
||||
|
||||
### New Files
|
||||
- `bridge/jackbox/roomcode_image.go` - PNG image generation
|
||||
- `bridge/jackbox/image_upload.go` - HTTP upload to Kosmi CDN
|
||||
- `bridge/irc/formatting.go` - IRC formatting helpers
|
||||
- `bridge/kosmi/image_upload.go` - (Duplicate, can be removed)
|
||||
- `KOSMI_IMAGE_UPLOAD.md` - Protocol documentation
|
||||
|
||||
### Modified Files
|
||||
- `bridge/jackbox/websocket_client.go` - Image upload integration
|
||||
- `bridge/jackbox/manager.go` - Config passing
|
||||
- `matterbridge.toml` - Added `EnableRoomCodeImage` setting
|
||||
|
||||
### Test Files
|
||||
- `cmd/test-roomcode-image/main.go` - Test image generation
|
||||
- `cmd/test-image-upload/main.go` - Test full upload flow
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Image Generation
|
||||
```bash
|
||||
./test-roomcode-image
|
||||
# Generates: roomcode_ABCD.png, roomcode_TEST.png, etc.
|
||||
```
|
||||
|
||||
### Test Image Upload
|
||||
```bash
|
||||
./test-image-upload
|
||||
# Generates image, uploads to Kosmi CDN, displays URL
|
||||
```
|
||||
|
||||
### Test Full Integration
|
||||
1. Set `EnableRoomCodeImage=true` in `matterbridge.toml`
|
||||
2. Start the bot: `./matterbridge -conf matterbridge.toml`
|
||||
3. Add a game in the Jackbox Picker with a room code
|
||||
4. Verify:
|
||||
- Kosmi chat shows the game announcement + image thumbnail
|
||||
- IRC chat shows the game announcement + formatted room code text
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Image Specifications
|
||||
- Format: PNG
|
||||
- Size: 200x80 pixels
|
||||
- Background: Black (`#000000`)
|
||||
- Text: White (`#FFFFFF`)
|
||||
- Font: `basicfont.Face7x13` (monospace)
|
||||
- Typical file size: ~400-500 bytes
|
||||
|
||||
### Upload Endpoint
|
||||
- URL: `https://img.kosmi.io/`
|
||||
- Method: `POST`
|
||||
- Content-Type: `multipart/form-data`
|
||||
- Authentication: None required (CORS-protected)
|
||||
- Response: `{"filename": "uuid.webp"}`
|
||||
- Full URL: `https://img.kosmi.io/{filename}`
|
||||
|
||||
### Performance
|
||||
- Image generation: <1ms
|
||||
- Image upload: ~300-600ms (network dependent)
|
||||
- Total delay: Minimal, upload happens asynchronously
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
1. **Custom fonts**: Use a better monospace font (requires embedding TTF)
|
||||
2. **Styling**: Add Jackbox branding, colors, or borders
|
||||
3. **Caching**: Cache uploaded images to avoid re-uploading identical room codes
|
||||
4. **Retry logic**: Add retry mechanism for failed uploads
|
||||
5. **Compression**: Optimize PNG compression for smaller file sizes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Images not appearing in Kosmi
|
||||
- Check that `EnableRoomCodeImage=true` in config
|
||||
- Check logs for upload errors
|
||||
- Verify network connectivity to `https://img.kosmi.io/`
|
||||
- Test manually with `./test-image-upload`
|
||||
|
||||
### IRC formatting not working
|
||||
- Ensure your IRC client supports formatting codes
|
||||
- Some clients require enabling "Show colors/formatting"
|
||||
- Fallback: The room code is still readable without formatting
|
||||
|
||||
### Build errors
|
||||
- Ensure all dependencies are installed: `go mod tidy`
|
||||
- Check Go version: Requires Go 1.19+
|
||||
- Verify `golang.org/x/image` is available
|
||||
|
||||
## References
|
||||
|
||||
- [Kosmi Image Upload Protocol](KOSMI_IMAGE_UPLOAD.md)
|
||||
- [IRC Formatting Codes](https://modern.ircdocs.horse/formatting.html)
|
||||
- [Go image package](https://pkg.go.dev/image)
|
||||
- [Jackbox Integration](JACKBOX_INTEGRATION.md)
|
||||
|
||||
Reference in New Issue
Block a user