🚨 DISCLAIMER 🚨

This was almost entirely generated by AI with guidance and oversight by someone extremely new to C# development. I welcome anyone with more experience and knowledge to correct whatever you find and improve it! It was created to fill my needs for a native Xbox client and my only hope for it is to be used (in any way, as a whole application or bits and pieces of code) by others :)

Gelatinarm for Xbox

A native Jellyfin client for Xbox One and Xbox Series X|S consoles, built with UWP (Universal Windows Platform) and optimized for controller navigation and TV viewing.

Gelatinarm	Gelatinarm 4K

Note: This app requires a Jellyfin media server to connect to. Gelatinarm is the client application that provides an Xbox-optimized interface for your Jellyfin content.

Features

🎮 Xbox-Optimized Experience

• Full controller support - Navigate entirely with your Xbox controller
• TV-optimized UI - Large text and controls designed for 10-foot viewing
• Xbox accent colors - UI respects your system theme preferences

📺 Media Playback

• Movies & TV Shows - Stream your entire video library
• Direct Play - Compatible files play as-is, straight from your server, with no transcoding
• Playback statistics (Y) - Shows whether you're direct playing, remuxing or transcoding, and the server's reasons
• Hardware acceleration - Optimized decoding for smooth playback
• HDR support - HDR10 (all Xbox models), HDR10+, HLG, and Dolby Vision profiles 8.1 and 8.4 (Xbox Series S/X only)
• Auto-Play Next Episode - Seamlessly continue to the next episode
• Episode Shuffle Mode - Random episode playback for your favorite shows
• Multiple Audio & Subtitle Tracks - Switch languages and subtitles during playback (a direct-played file switches audio inside the player; otherwise the stream restarts from the server at the same position)
• Server streaming fallback - Anything the Xbox can't play directly is remuxed or transcoded by your server over HLS
• Buffering optimization - Smart buffering for smooth playback
• Profile Switching - Switch between different users on the same server, keeping settings, playback history, etc. separate

🎵 Music & Audio

• Background playback - Keep music playing while using other apps
• Mini player - Play/pause, previous/next, shuffle and repeat, from anywhere in the app
• Queue management - Play next, add to queue, shuffle, repeat
• Instant Mix - Create automatic playlists from any song

📚 Library Management

• Library browsing - Browse Movies, TV Shows, Music, and more
• Smart sorting & Filters - By name, date added, release date, rating; filter by several tags/metadata
• Search - Find content quickly across all libraries
• Collections - Browse curated collections
• Favorites - Quick access to your favorite content

🎯 Smart Features

• Unwatched indicators - See what's new at a glance
• Progress tracking - Visual progress bars for partially watched content
• Skip intro/outro/credits - Auto-skip or manual buttons (configurable) *Requires intro detection plugin on server
• Quick Connect - Easy pairing with your Jellyfin server using a simple code
• Memory optimization - Smart caching and resource management
• SSL certificate support - Optional self-signed certificate acceptance

Format Support

✅ plays directly from the file. Anything else is remuxed or transcoded by your Jellyfin server: the cell says what the console does with the file as it is, or ❌. Press Y during playback to see which, and why. A direct play that fails to open is retried as a server stream. Test method: Docs/CODEC_TESTING.md.

Video

Codec	MP4, M4V, MOV, 3GP	MKV, WebM	TS, M2TS	MPG, VOB	AVI	WMV, ASF	Direct play requires
H.264	✅	✅	✅	No picture	✅	❌	8-bit 4:2:0 (10-bit, 4:2:2, 4:4:4: decoder error); Baseline, Main or High; level 5.2 or lower
HEVC	✅	✅	✅	No picture	❌	❌	8- or 10-bit 4:2:0 (12-bit crashes the decoder; 4:2:2, 4:4:4: decoder error); level 6.1 or lower; Xbox One S or later
VP9	✅	✅	❌	❌	❌	❌	8- or 10-bit 4:2:0 (4:4:4: green picture)
VP8	❌	✅	❌	❌	❌	❌
MPEG-2	❌	✅	✅	✅	❌	❌
MPEG-1	❌	❌	✅	✅	❌	❌
MPEG-4 Part 2 (DivX, Xvid)	✅	✅	❌	❌	✅	❌	Simple Profile (B-frames stall or crash the video driver)
H.263	✅	❌	❌	❌	❌	❌
MS-MPEG4 v2, v3 (DivX 3)	❌	❌	❌	❌	✅	❌
WMV 7, WMV 8	❌	❌	❌	❌	❌	✅
VC-1 (WMV 9)	✅	No picture	No picture	❌	❌	✅
AV1	No picture	No picture	❌	❌	❌	❌
VVC, ProRes	No picture	❌	❌	❌	❌	❌
DV	❌	❌	❌	❌	Jittery	❌
Others	❌	❌	❌	❌	❌	❌

• All video: 60 fps or lower, within the picture size limit.
• FLV and OGV files (Sorenson, Theora): refused.
• Motion JPEG: Jellyfin serves the audio only.
• Transcoded video is HEVC when the server allows HEVC encoding and the console decodes it, otherwise H.264.

Audio in video files

When only the audio is not ✅, the server converts the audio and copies the video.

Codec	MP4, M4V, 3GP	MOV	MKV, WebM	TS, M2TS	MPG, VOB	AVI	WMV, ASF	Channels
AAC (LC, HE-AAC)	✅	✅	✅	✅	❌	✅	❌	up to 5.1; 7.1 is silent
AC3 (Dolby Digital)	✅	Refused	✅	✅	✅	✅	Stutters
E-AC3 (Dolby Digital Plus, Atmos)	✅	Refused	✅	✅	❌	❌	❌	up to 7.1
MP3	✅	✅	✅	✅	❌	✅	❌
MP2	❌	❌	✅	✅	✅	❌	❌
FLAC	✅	–	✅	❌	❌	❌	❌	up to 7.1, 24-bit; 32-bit is silent
ALAC	Silent	✅	✅	❌	❌	❌	❌
PCM	Silent	✅	Silent	✅ Blu-ray LPCM in M2TS	Silent	✅	❌	up to 7.1
Opus	Silent	❌	✅	❌	❌	❌	❌	stereo; 5.1 and 7.1 are silent
WMA	❌	❌	❌	❌	❌	❌	✅
AMR	✅	✅	❌	❌	❌	❌	❌
DTS, DTS-HD	❌	❌	Silent	Silent	❌	❌	❌
TrueHD, Vorbis	❌	❌	Silent	❌	❌	❌	❌
Others	❌	❌	❌	❌	❌	❌	❌

• MOV: a file named .mov or .qt.
• Settings → Playback → Audio Direct Stream lets a server stream pass AAC, AC3 and E-AC3 through unconverted.

Music

Codec	Direct play in	Limit
MP3	.mp3, .m4a
MP2	.mp2
AAC (LC, HE-AAC)	.aac, .m4a, .m4b	up to 5.1; 7.1 is refused
ALAC	.m4a	up to 7.1
FLAC	.flac, .m4a, .mka	up to 7.1, 24-bit 192 kHz; refused with more than about 4 MB of embedded cover art
PCM (integer and float), A-law, µ-law, ADPCM, GSM	.wav	up to 7.1
WMA (Standard, Pro, Lossless)	.wma
AC3	.ac3, .m4a
E-AC3	.eac3	up to 5.1; 7.1 is refused
Opus	.mka
AMR	.amr, .3gp, .m4a
Ogg (Vorbis, Opus), AIFF, WavPack, APE	Refused
DTS	A burst of noise, then stops
True Audio, audio in .webm	Jellyfin does not import the file
Others	❌

A track the console refuses is streamed by the server: lossless sources as FLAC, others as MP3.

HDR

Format	Direct play
HDR10, HDR10+	✅
HLG	✅ Xbox Series X|S
Dolby Vision over an HDR10 or HLG layer (profiles 8.1, 8.4), also with HDR10+	✅ Xbox Series X|S
Dolby Vision alone (profile 5)	Tried on Xbox Series X|S. Without a Dolby Vision display it fails to decode and the server converts it

The standard edition has no HDR output: Xbox offers HDR display modes only to the 4K edition. In the standard edition the console shows HDR video converted to standard range.

The 4K edition has three settings for it under Settings → Playback:

• HDR Display Mode (on by default) switches the display to HDR when an HDR video starts and back when you leave the player. Turned off, the console converts HDR to standard range.
• HDR on Any Display (on by default) direct plays HDR even when the console offers no HDR mode for the display. Turned off, the server converts those files instead.
• Match Frame Rate (off by default) switches the display to the video's frame rate, 24 or 50 Hz, and back when you leave the player. Turned off, the display stays at 60 Hz and the console converts.

Subtitles

The Xbox player draws no subtitles. A selected subtitle (SRT, ASS/SSA, VTT, PGS, VobSub, DVB) is burned in by the server, which transcodes the video.

Video Resolution

Edition	Largest picture	HDR output, frame rate matching	Background music
Standard	1920x1080 (portrait 1080x1920)	❌	✅
4K ("Gelatinarm 4K", Release4K)	No limit	✅	❌ Xbox closes the app when a game starts

The server scales larger video down. Xbox gives 4K video memory and HDR display modes only to an app with the hevcPlayback capability, which rules out background playback (Microsoft: 4K video playback on Xbox). The two editions install side by side; see Docs/DEV_SETUP.md.

Known Limitations

• Subtitles - Burned in by the server; choosing or changing one restarts the stream as a transcode.
• Audio track switching - A direct-played file switches audio track inside the player when the console can decode the new track. Otherwise, and on a server stream, playback restarts with the server supplying that track.
• Remote connections - If your server sees the Xbox as a remote client, its internet streaming bitrate limit applies and high-bitrate files are transcoded. Configure your server's LAN networks if the Xbox is on your home network.

Xbox Controller Mapping

Global Controls (All Screens)

Button	Action
A	Select/Confirm
B	Back/Cancel
D-Pad/Left Stick	Navigate UI
Right Trigger (Hold 0.5s)	Jump to MiniPlayer

Video Playback Controls

Controls Hidden

Button	Action	Parameter
A	Play/Pause	-
B	Exit playback	-
Y	Toggle statistics overlay	-
D-Pad Up	Show playback controls	-
D-Pad Down	Show playback controls	-
D-Pad Left	Rewind	10 seconds
D-Pad Right	Fast forward	30 seconds
Left Trigger	Rewind	10 minutes (600 seconds)
Right Trigger	Fast forward	10 minutes (600 seconds)

Controls Visible

Button	Action	Notes
D-Pad	Navigate control buttons	Focus moves between buttons
A	Activate focused button	-
B	Exit playback	Always works
Y	Toggle statistics	Works even with controls visible
Up	Hide controls	Returns to full-screen video
Left Trigger	Rewind 10 minutes	Works even with controls visible
Right Trigger	Fast forward 10 minutes	Works even with controls visible

Unmapped Buttons

The following buttons have no assigned functions during playback:

• X Button - Not used
• Left/Right Shoulder (LB/RB) - Not used during playback
• View Button - Not used
• Menu Button - Not used
• Left/Right Thumbstick Click - Not used

Music Playback

Music playback uses standard system media controls. Use the Xbox Guide button to access media controls while music plays in the background.

System Requirements

• Xbox One, Xbox One S, Xbox One X, Xbox Series S, or Xbox Series X
• Internet connection
• Jellyfin server (version 10.8.0 or later; 12.0 or later recommended)
• Developer Mode only for sideloading; not needed when installing from the Microsoft Store

Installation

From Microsoft Store

Install directly from the Microsoft Store - search for "Gelatinarm" or use the link at the top of this page.

Sideloading (Developer Mode)

1. Enable Developer Mode on your Xbox
2. Download the latest release package
3. Use the Xbox Device Portal to install the package
4. Launch Gelatinarm from your Apps list

Building from Source

See Docs/DEV_SETUP.md for the full setup, command-line builds and testing.

Prerequisites

• Windows 10/11
• Visual Studio with the UWP development workload (releases are built with Visual Studio 2026)
• Windows 11 SDK (10.0.22621.0)

Build Steps

1. Clone the repository
2. Open Gelatinarm.sln in Visual Studio
3. Set configuration to Release and platform to x64
4. Build the solution
5. Deploy to your Xbox in Developer Mode

Generating Store Release (Unsigned)

The Store signs the package at publication, so the upload package is built unsigned.

1. Update Version Number

• Open Package.appxmanifest in Visual Studio, Packaging tab
• Increment the Version number (e.g., 1.0.1.0 → 1.0.2.0) and save

2. Build Store Upload Package (PowerShell)

From the project root:

Gelatinarm	Gelatinarm 4K
cd C:\gelatinarm & 'C:\Program Files\Microsoft Visual Studio\18\Community\MSBuild\Current\Bin\MSBuild.exe' ` Gelatinarm.csproj ` /p:Configuration=Release ` /p:Platform=x64 ` /p:UapAppxPackageBuildMode=StoreUpload ` /p:AppxBundle=Always ` /p:AppxPackageSigningEnabled=false ` /p:AppxPackageDir=".\AppPackages\"	cd C:\gelatinarm & 'C:\Program Files\Microsoft Visual Studio\18\Community\MSBuild\Current\Bin\MSBuild.exe' ` Gelatinarm.csproj ` /p:Configuration=Release4K ` /p:Platform=x64 ` /p:UapAppxPackageBuildMode=StoreUpload ` /p:AppxBundle=Always ` /p:AppxPackageSigningEnabled=false ` /p:AppxPackageDir=".\AppPackages\4K\"

3. Upload to Store

• The build creates an .msixupload or .appxupload file in the package directory
• Upload it to Microsoft Partner Center, each edition to its own app

Contributing

Contributions are welcome! Please:

1. Check existing issues before creating new ones
2. Read Docs/ARCHITECTURE.md and follow Docs/CONVENTIONS.md
3. Test on actual Xbox hardware when possible (see Docs/DEV_SETUP.md)
4. Update documentation for new features

Acknowledgments

• The Jellyfin team for the excellent media server
• Microsoft for the UWP platform and Xbox development tools
• Claude (Anthropic) for extensive development assistance
• All contributors and testers who helped improve the app

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Gelatinarm is not affiliated with Jellyfin or Microsoft. Xbox is a trademark of Microsoft Corporation.