142 lines
4.2 KiB
Markdown
142 lines
4.2 KiB
Markdown
|
# 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)
|
||
|
|
|