# 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)