jellyflood/RELEASE-ALPHA1.md

jellypig tvOS Alpha 1 Release

Release Date: October 17, 2025 Base Version: Swiftfin 1.3 Branch: jellypig-1.3 License: MPL-2.0

---

Overview

jellypig is a personal fork of Jellyfin/Swiftfin optimized for tvOS with specialized support for Jellyfin.Xtream plugin content. This alpha1 release represents a stable, working build that plays everything upstream Swiftfin on tvOS plays and more, with an elegant native UI maintained by the Swiftfin development team.

Key Features

✅ What Works

• Full Jellyfin Playback: All standard Jellyfin content (movies, series, live TV) plays correctly
• Xtream Content Support: Properly displays and plays Xtream VOD and Series content from Jellyfin.Xtream plugin
• Channel Navigation: Fixed channel browsing with proper grid view for categories and content
• Full-Screen Navigation: All views display full-screen (no modal popups)
• Video Playback Controls: ESC key properly shows controls and allows exit with confirmation
• Native UI: Maintains the elegant, native tvOS interface from upstream Swiftfin

🎯 Major Improvements Over Upstream

1. Xtream Content Listing: Fixed channel folder navigation to use proper Jellyfin Channel API endpoints

   • Xtream VOD and Xtream Series channels now display correct, distinct content
   • Channel folders display in grid view matching library behavior

2. tvOS Navigation Architecture: Restructured routing to fix modal popup issues

   • Channels, items, and content display full-screen using .push navigation
   • MediaCoordinator uses .fullScreen to prevent navigation stack corruption
   • Video player properly stops on dismiss (no background playback)

3. Leaner Codebase: Removed entire iOS build and code (28,370+ deletions)

   • tvOS-only focus reduces complexity
   • Faster build times and easier maintenance
   • Single target: jellypig tvOS

Technical Changes

Core Fixes

• ItemLibraryViewModel.swift: Implements proper channel API routing (/Channels/{channelID}/Items)
• PagingLibraryView.swift: Added .channelFolderItem support for grid view display
• MainCoordinator.swift: Restructured MediaCoordinator routing with .fullScreen navigation
• ItemView.swift: Removed .channelFolderItem handling (delegates to library view)

Project Configuration

• Bundle ID: org.ashik.jellypig
• Project Name: jellypig (renamed from Swiftfin)
• Targets: tvOS only (iOS removed)
• CI/CD: Updated GitHub Actions workflows for jellypig tvOS builds
• Dependencies: Properly configured VLCKit (TVVLCKit.xcframework v3.5.0)

Known Limitations

Acceptable Trade-offs

• Error Dismissal: Errors in deeply nested views (e.g., failed episode playback) dismiss all the way to Media tab instead of one level back

  • This is a limitation of .fullScreen presentation architecture
  • Prevents worse issue of returning to Home screen

• Video Player Back Button: Slightly "buggy" behavior but functional

  • ESC key works properly (shows controls → confirm → exit)
  • Playback stops correctly on dismiss

Development Environment

Requirements

• Platform: macOS with Xcode 16+
• Build Method: Must use Xcode GUI (Command+B)
  • Command-line xcodebuild fails due to Swift macro issues in swift-case-paths dependency
  • All other operations (git, editing) work via command line
• Simulator: Any tvOS 16.0+ simulator or device

Repository

• Fork: ashikslab/jellypig
• Upstream: jellyfin/swiftfin
• Plugin: ashikslab/Jellyfin.Xtream

Companion Plugin

jellypig works best with the reverted Jellyfin.Xtream plugin (v0.7.2.0001) which uses pure upstream logic:

• Repository: https://ashikslab.github.io/Jellyfin.Xtream/repository.json
• Download: https://github.com/ashikslab/Jellyfin.Xtream/releases/download/v0.7.2.0001/jellyfin-xtream-for-jellypig_0.7.2.1.zip

The plugin provides standard Jellyfin Channel API endpoints for Xtream content, and jellypig handles the display and navigation correctly.

What's Next

Short Term (Until Upstream Stabilizes)

• Bug fixes as discovered
• UI adjustments and polish
• Stay on Swiftfin 1.3 base

Long Term

• Major Intake: When upstream Swiftfin releases their next stable major version, jellypig will merge those changes
• iOS Support: May consider re-adding iOS support with Xtream fixes as a separate project
• Upstream Contributions: Channel navigation fixes could potentially be contributed back to Swiftfin

Credits

• Original Project: Jellyfin Swiftfin - MPL-2.0 License
• Plugin: Kevinjil/Jellyfin.Xtream - GPL-3.0 License
• jellypig Fork: Personal modifications for Xtream content support and tvOS optimization

---

This is an alpha release: Suitable for personal use and testing. Report issues at https://github.com/ashikslab/jellypig/issues