Battles Record integrates with Jellyfin to automatically update your media library when recordings complete.
Overview
When a recording finishes:
- File is moved to output directory
- NFO metadata file is created
- Jellyfin library scan is triggered
- Recording appears in Jellyfin
Setup
Configure Jellyfin Connection
Navigate to Settings → Integrations → Jellyfin
Enter Server URL
Your Jellyfin server address (e.g., http://localhost:8096 or https://jellyfin.example.com)
Add API Key
Create an API key in Jellyfin: Dashboard → API Keys → New
Select Library
Choose which Jellyfin library should receive recordings
Test Connection
Click Test to verify the connection works
Library Configuration
Jellyfin Library Type
Create a dedicated library for stream recordings:
Open Jellyfin Dashboard
Go to Dashboard → Libraries → Add Media Library
Select Type
Choose Shows or Mixed Content
Add Folder
Point to your Battles Record output directory
Configure Metadata
Disable internet metadata fetchers (recordings use local NFO files)
Using Shows type organizes recordings as episodes under each channel (series).
Folder Structure for Jellyfin
Enable Jellyfin-compatible folder structure in Battles Record:
{library_dir}/
└── {platform}/
└── {channel}/
├── tvshow.nfo
├── poster.jpg
├── banner.jpg
├── logo.png
├── fanart.jpg
├── landscape.jpg
└── Season XX/
├── season.nfo
├── poster.jpg
├── {channel} - S01E001 - {title}.mp4
├── {channel} - S01E001 - {title}.nfo
└── {channel} - S01E001 - {title}-thumb.jpg
Episode NFO
<?xml version="1.0" encoding="UTF-8"?>
<episodedetails>
<title>Valorant Ranked</title>
<showtitle>Shroud</showtitle>
<season>2026</season>
<episode>0201</episode>
<aired>2026-02-01</aired>
<runtime>180</runtime>
<plot>Recorded from Twitch on February 1, 2026. Category: Valorant</plot>
<genre>Gaming</genre>
<studio>Twitch</studio>
</episodedetails>
Series NFO
Created once per channel:
<?xml version="1.0" encoding="UTF-8"?>
<tvshow>
<title>Shroud</title>
<plot>Stream recordings from Twitch channel Shroud</plot>
<genre>Gaming</genre>
<studio>Twitch</studio>
</tvshow>
Artwork & Rich Image Generation
When enabled, Battles Record generates a full set of artwork for each channel using platform profile and banner images.
Dominant colors are extracted from the channel’s profile image using k-means clustering. A 5-color palette is derived automatically:
| Color | Usage |
|---|
| Primary | Main accent color for headers and titles |
| Secondary | Supporting color for backgrounds |
| Accent | Highlight color for badges and indicators |
| Text | Primary text color |
| Muted Text | Secondary text and labels |
Show-Level Images
Generated once per channel:
| Image | Size | Description |
|---|
| poster.jpg | 680x1000 | Portrait poster with profile image, channel name, platform, and metadata |
| banner.jpg | 758x140 | Wide header with banner background, profile image, and channel name |
| logo.png | 800x310 | Horizontal logo with large channel name and platform text |
| fanart.jpg | 1920x1080 | Cinematic background with vignette overlay, profile image, and game category |
| landscape.jpg | 500x281 | Thumbnail card with diagonal gradient and profile image |
Season-Level Images
Generated once per month:
| Image | Size | Description |
|---|
| poster.jpg | 680x1000 | Season poster with prominent date display (month, day, year) and episode count |
Episode-Level Images
Generated per recording:
| Image | Size | Description |
|---|
| thumb.jpg | 3840x2160 | 4K thumbnail with stream screenshot background, title overlay, viewer count, game, duration, and episode number |
All images use embedded JetBrains Mono (Regular and Bold), matching the application’s
monospace design system.
Library Refresh
Automatic Refresh
After each recording completes, Battles Record triggers a library scan:
| Method | Description |
|---|
| Full Scan | Scan entire library (slower, more thorough) |
| Folder Scan | Scan only the recording’s folder (faster) |
Manual Refresh
Force a library refresh:
- Click Refresh Library in Settings → Integrations → Jellyfin
- Or use the API:
POST /api/jellyfin/refresh
Customize how recordings appear in Jellyfin:
Season/Episode Numbering
| Format | Example | Description |
|---|
| Monthly | S01E001 | Seasons by month (S01 = January, S12 = December), sequential episodes |
| Year | S2026E0201 | Year as season, date as episode |
| Date | 2026-02-01 | Date in filename (requires Jellyfin date parsing) |
| Format | Example |
|---|
| Stream Title | Valorant Ranked |
| Date + Title | 2026-02-01 - Valorant Ranked |
| Category + Title | Valorant - Ranked |
Multiple Jellyfin Servers
Configure multiple Jellyfin instances:
Add Server
Click Add Jellyfin Server in settings
Configure
Enter URL, API key, and library
Assign Channels
Choose which channels sync to which server
Troubleshooting
Recordings Don’t Appear
- Verify Jellyfin connection in settings
- Check API key has library write permissions
- Ensure output directory is accessible to Jellyfin
- Try manual library refresh
- Check NFO file was created alongside video
- Verify Jellyfin is using local metadata (not internet scrapers)
- Delete
.nfo and let Battles Record regenerate
Permission Errors
For Docker deployments, ensure user IDs match:
environment:
- PUID=1000
- PGID=1000
Duplicate Entries
If recordings appear twice:
- Disable duplicate metadata providers in Jellyfin
- Ensure only one folder structure format is enabled
- Run library scan with Replace all metadata option
