IRC-kosmi-relay/ROOM_CODE_IMAGE_FEATURE.md

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:

[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

./test-roomcode-image
# Generates: roomcode_ABCD.png, roomcode_TEST.png, etc.

Test Image Upload

./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
• IRC Formatting Codes
• Go image package
• Jackbox Integration