gelatinarm

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 16 Open GitHub ↗

A native Xbox media client for Jellyfin servers; this is unofficial and has no affiliation with the Jellyfin project in any way

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🚨 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.

**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** - Play compatible formats without transcoding
- **Hardware acceleration** - Optimized decoding for smooth playback
- **HDR support** - HDR10 (all Xbox models), HDR10+, HLG, and Dolby Vision Profile 8.1 (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 between languages and subtitles on the fly
- **Adaptive streaming** - HLS/DASH support with automatic bitrate adjustment
- **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** - Persistent playback controls
- **Queue management** - Play next, add to queue, shuffle, repeat (no reordering/editing at the moment...)
- **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

## Codec Support

### Video Codec Comparison

| Codec | Gelatinarm Support | Xbox Hardware Support | Notes |
|-------|-------------------|----------------------|-------|
| **H.264/AVC** | ✅ Direct Play | ✅ Full | Hardware accelerated, all profiles |
| **H.265/HEVC** | ✅ Direct Play* | ✅ Full | *Xbox One S/X and Series S/X only |
| **VP9** | ✅ Direct Play | ✅ Full | Hardware accelerated |
| **VP8** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **AV1** | ✅ Direct Play* | ✅ Limited | *Xbox Series S/X only, up to 4K@60fps |
| **MPEG-1** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **MPEG-2** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **MPEG-4 Part 2** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **VC-1** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **Motion JPEG** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **H.263** | ✅ Direct Play | ✅ Supported | All Xbox models |
| **DV** | ✅ Direct Play | ✅ Supported | All Xbox models |

### HDR Format Support

| Format | Xbox One S/X | Xbox Series S/X | Notes |
|--------|--------------|-----------------|-------|
| **HDR10** | ✅ Supported | ✅ Supported | Hardware accelerated on all models |
| **HDR10+** | ✅ Supported* | ✅ Supported* | *Display must support HDR10+ |
| **HLG** | ✅ Supported* | ✅ Supported* | *Display must support HLG |
| **Dolby Vision** | ❌ Not Supported | ✅ Profile 8.1 Only | Profile 5 and 7 not supported, will transcode |

### Audio Codec Comparison

**Audio Direct Stream**: Enable in Settings → Playback to allow audio stream copy to compatible receivers

| Codec | Gelatinarm Support | Xbox Hardware Support | Notes |
|-------|-------------------|----------------------|-------|
| **AAC/HE-AAC** | ✅ Direct Play | ✅ Full | All profiles supported |
| **MP3** | ✅ Direct Play | ✅ Full | All bitrates supported |
| **FLAC** | ✅ Direct Play | ✅ Full | See artwork limitation below |
| **ALAC** | ✅ Direct Play | ✅ Full | Apple Lossless |
| **PCM/LPCM** | ✅ Direct Play | ✅ Full | Uncompressed audio |
| **WMA/WMA Pro** | ✅ Direct Play | ✅ Full | All variants |
| **WMA Voice** | ✅ Direct Play | ✅ Full | Voice codecs |
| **G.711 (A-law/µ-law)** | ✅ Direct Play | ✅ Full | Telephony PCM |
| **GSM 6.10** | ✅ Direct Play | ✅ Full | Telephony codec |
| **IMA ADPCM** | ✅ Direct Play | ✅ Full | Adaptive differential PCM |
| **MS ADPCM** | ✅ Direct Play | ✅ Full | Microsoft ADPCM |
| **AMR-NB** | ✅ Direct Play | ✅ Full | Adaptive Multi-Rate (narrowband) |
| **AC3 (DD)** | ✅ Direct Play | ✅ Full | Dolby Digital |
| **MPEG-1/2 Audio** | ✅ Direct Play | ✅ Full | MP2 in MPEG containers |

## 4K Playback on Xbox

Gelatinarm runs in standard app mode on Xbox, which means it prioritizes **background music playback** over expanded video resources. This is a deliberate design choice with the following implications:

### What this means for you:
- ✅ **Background music works perfectly** - Continue listening while playing games or using other apps
- ✅ **4K video playback is supported** - Within the standard memory constraints
- ✅ **HDR content works** - HDR10 on all models, Dolby Vision Profile 8.1 on Series S/X
- ⚠️ **Some 4K content may transcode** - If it exceeds memory limits, Jellyfin will automatically adjust

### Technical Background
Xbox apps must choose between two modes:
1. **Standard mode** (what Gelatinarm uses): Allows background audio but limits memory to ~1GB
2. **Expanded mode**: Provides 5GB+ memory for 4K video but disables all background functionality

We chose standard mode because background music is a core feature for most users. The app handles 4K content well within these constraints, and any content that needs more resources will be seamlessly transcoded by your Jellyfin server.

For more technical details about this Xbox limitation, see [Microsoft's documentation on HEVC video on Xbox](https://learn.microsoft.com/en-us/windows/uwp/audio-video-camera/hevc-xbox).

### Supported Container Formats
Direct play support for all common containers:
- **MPEG-4**: MP4, M4V, MOV, M4A
- **Matroska**: MKV, WebM
- **Windows Media**: WMV, ASF, WMA
- **MPEG**: TS, M2TS, MTS, MPG, MPEG, VOB
- **Legacy**: AVI, FLV
- **Mobile**: 3GP, 3G2
- **Audio**: MP3, AAC, FLAC, WAV, ALAC, WMA, AMR

### Supported Subtitle Formats
- **SRT** - Most compatible, external and embedded
- **ASS/SSA** - Advanced styling preserved
- **VTT** - WebVTT format
- **PGS** - Blu-ray subtitles
- **VOBSUB** - Requires server-side burn-in

## Known Limitations

### Audio Playback with Embedded Artwork
- **Issue**: FLAC files with embedded artwork larger than ~1500×1500 pixels may fail to play directly
- **Cause**: Xbox MediaPlayer limitation with large embedded images
- **Solution**: The app automatically falls back to transcoding when this occurs
- **Workaround**: Ensure your Jellyfin server has separate album artwork

### Platform Limitations
- **External subtitles** - Only embedded subtitles are supported due to UWP MediaPlaybackItem architecture. External subtitle tracks must be added when creating the MediaPlaybackItem and cannot be dynamically changed during playback. Since we initialize playback in MediaPlayerPage, we cannot pre-load external subtitles. The app will automatically request the server to embed all subtitles in the stream.

## 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 |
| **LB/RB** | Switch tabs (where applicable) |

### 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 recommended)
- Xbox configured to Developer Mode for sideloading (or install from Microsoft Store when available)

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

### Prerequisites
- Windows 10/11
- Visual Studio 2022 with UWP development workload
- Windows 11 SDK (10.0.22621.0)

### Build Steps
1. Clone the repository
2. Open `Gelatinarm.sln` in Visual Studio 2022
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)

**Note**: This method is ONLY needed if you cannot sign the package due to cross-architecture limitations (e.g., building x64 packages on ARM machines). If you can sign normally in Visual Studio, use the standard publishing workflow instead.

#### When to Use This Method
- Building x64 packages on ARM development machines
- Cross-architecture builds where signing fails
- When Visual Studio's built-in Store publishing fails due to signing errors

#### 1. Update Version Number
- Open `Package.appxmanifest` in Visual Studio
- Go to the **Packaging** tab
- Increment the **Version** number (e.g., 1.0.1.0 → 1.0.2.0)
- Save the file

#### 2. Build Store Upload Package (PowerShell)
Run the following command from the project root:

```powershell
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\"
```

#### 3. Upload to Store
- The build creates an `.msixupload` or `.appxupload` file in `.\AppPackages\`
- Upload this file to Microsoft Partner Center
- Microsoft will sign the package with their certificate during publication

**Why Unsigned?** The `/p:AppxPackageSigningEnabled=false` parameter bypasses the signing step that fails when building for a different architecture than your development machine. Microsoft Store handles the final signing, so unsigned packages are acceptable for Store submission.

## Contributing

Contributions are welcome! Please:
1. Check existing issues before creating new ones
2. Follow the existing code style and patterns
3. Test on actual Xbox hardware when possible
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.*

gelatinarm

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README