[jellyfin] Add support for server versions > 10.8

[pgfeller]

[jellyfin] Add support for server versions > 10.8

🎬 Complete rewrite of the Jellyfin binding with WebSocket real-time updates, generated API client, and accurate client state management

---

📌 Overview

Fixes	#17674 - SDK Version 1.4.x no longer supports recent Jellyfin Server Versions (>10.8)
Replaces	Draft PR #17757
Status	🚧 Code cleanups and interactive tests in progress
Target Version	Jellyfin 10.10.7+ (older versions not supported)

---

🎯 Key Features

🚀 Real-Time Updates WebSocket-based updates with <500ms latency Automatic fallback to polling when WebSocket unavailable No configuration required 🔍 Server & Client Discovery UDP broadcast server discovery on local networks Automatic client detection via Sessions API Manual configuration for cross-subnet servers

⚡ Generated API Client Type-safe API generated from OpenAPI specification Supports Jellyfin 10.10.7+ API endpoints Null-safe implementation with @NonNull annotations 🎯 Client State Tracking Session-based connectivity detection 60-second timeout monitoring Independent per-device status

---

🏗️ Architecture

Component Overview - Click to expand architecture diagram

graph TB
    subgraph "Server Bridge"
        SH[ServerHandler]
        TM[TaskManager]
        WST[WebSocketTask]
        SST[ServerSyncTask]
        DT[DiscoveryTask]
    end

    subgraph "Event System"
        SEB[SessionEventBus]
        EEB[ErrorEventBus]
    end

    subgraph "Clients"
        CH1[ClientHandler 1]
        CH2[ClientHandler 2]
        CHN[ClientHandler N]
    end

    subgraph "Jellyfin Server"
        WS[WebSocket Endpoint]
        API[REST API]
    end

    SH -->|manages| TM
    TM -->|schedules| WST
    TM -->|fallback| SST
    TM -->|periodic| DT

    WST -->|connects| WS
    SST -->|polls| API
    DT -->|queries| API

    WS -->|SessionsMessage| SEB
    SST -->|session updates| SEB

    SEB -->|notifies| CH1
    SEB -->|notifies| CH2
    SEB -->|notifies| CHN

    CH1 -->|60s timeout| CH1
    CH2 -->|60s timeout| CH2
    CHN -->|60s timeout| CHN

    style WST fill:#d4edda
    style SST fill:#fff3cd
    style SEB fill:#cce5ff

Loading

State Flow - Click to expand state diagram

stateDiagram-v2
    [*] --> INITIALIZING: initialize()
    INITIALIZING --> CONNECTING: connection attempt
    CONNECTING --> CONNECTED: WebSocket + auth success
    CONNECTING --> POLLING: WebSocket failed
    CONNECTED --> POLLING: WebSocket fallback
    POLLING --> CONNECTED: WebSocket recovered
    CONNECTED --> ERROR: fatal error
    POLLING --> ERROR: fatal error
    ERROR --> [*]: dispose()
    CONNECTED --> [*]: dispose()
    POLLING --> [*]: dispose()

    note right of CONNECTED
        WebSocket active
        <500ms updates
    end note

    note right of POLLING
        ServerSyncTask active
        30-60s interval
    end note

Loading

---

🔄 Implementation Phases

Phase 1: API Generator Evaluation ✅ Complete

📦 OpenAPI Code Generation - Click to expand

Objectives

• Evaluate code generation tools (OpenAPI Generator, Swagger, Kiota)
• Generate type-safe API client for Jellyfin 10.10.7+
• Establish maintainable code generation workflow

Implementation

• Evaluate OpenAPI Generator vs alternatives
• Create generator configuration (tools/generate-sources/config/)
• Generate API client models and APIs
• Check in generated code to repository
• Add null-safety annotations

Outcomes

• Tool Selected: OpenAPI Generator 7.x
• Generated Code: 150+ API models, 20+ API endpoints
• Rationale: Checked-in code reduces build complexity, no runtime dependencies
• Location: src/main/java/.../thirdparty/api/

Key Decisions

Decision	Rationale
Check in generated code	Reduces build time, eliminates generator as build dependency
Suppress warnings in generated code	Maintain clean baseline, focus on hand-written code quality
Use @NonNull annotations	Leverage openHAB's null-safety checking

Phase 2: Server Discovery ✅ Complete

🔍 UDP Broadcast Discovery - Click to expand

Objectives

• Implement automatic server discovery on local networks
• Validate server version compatibility
• Auto-create bridge Things for discovered servers

Implementation

• UDP broadcast discovery service
• Server version detection and validation
• Discovery service integration with openHAB
• Manual configuration support for cross-subnet servers

Outcomes

• Discovery Method: UDP broadcast on port 7359
• Version Check: Validates server ≥ 10.10.7
• Limitations: Same subnet only (VLAN/routing limitations)
• Fallback: Manual configuration via IP/hostname

Testing

• ✅ Tested with Jellyfin 10.10.7, 10.10.11, 10.11.x
• ✅ Works on same subnet without special configuration
• ✅ Manual config verified for cross-subnet scenarios

Phase 3: WebSocket Real-Time Updates ✅ Complete

⚡ WebSocket Implementation & Client Discovery - Click to expand

Objectives

• Implement WebSocket connection to Jellyfin server
• Handle real-time session updates (SessionsMessage events)
• Automatic client discovery via Sessions API
• Graceful fallback to polling on WebSocket failure

Implementation

• WebSocketTask with automatic reconnection
• SessionsMessageHandler for event parsing
• SessionEventBus for event distribution
• ClientHandler with full media control
• Exponential backoff for reconnection (1s → 60s)
• Automatic fallback to ServerSyncTask polling
• Client discovery via /Sessions endpoint
• Structured [MODE]/[WEBSOCKET] INFO log messages for active connection mode and real-time update observability (2026-02-28)

Outcomes

• Latency: <500ms from server event to state update
• Reliability: Automatic reconnection with exponential backoff
• Fallback: Seamless switch to 30s polling when WebSocket fails
• Discovery: Automatic client Thing creation for active sessions

Log Observability (INFO level, no debug logging required)

Log Message	Meaning
[MODE] Active update mode: WEBSOCKET (real-time updates)	WebSocket connected and active
[MODE] Active update mode: POLLING (WebSocket not available, interval: 60s)	Fallback path selected at startup
[WEBSOCKET] ✓ Connected successfully to ...	WebSocket handshake succeeded
[WEBSOCKET] Real-time session update received: N session(s)	Live data arriving from server
[WEBSOCKET] Reconnection attempt N/10 after Xs backoff	Reconnecting after drop
[MODE] ⚠️ WebSocket fallback triggered: switching to POLLING mode	Max retries exhausted

Performance Comparison

Mode	Update Latency	Network Pattern
WebSocket (primary)	<500ms	Event-driven
Polling (fallback)	30-60s	Periodic (30s/60s)

Phase 4: Client State Management ✅ Complete

🎯 Accurate Client Online/Offline Detection - Click to expand

Problem Statement

Observed Behavior: All clients showed as ONLINE whenever server bridge was ONLINE, regardless of device connectivity state.

// Previous implementation
if (bridgeStatus == ONLINE) {
    updateStatus(ONLINE);  // All clients marked ONLINE
}

Implemented Behavior: Client status reflects device connectivity state independent of server bridge status.

Implementation

• Session timeout monitoring (60s threshold)
• Timestamp tracking per session update
• 30-second periodic timeout checks
• Independent client state calculation
• WebSocket-based updates with polling fallback
• Enhanced logging with structured prefixes ([MODE]/[WEBSOCKET] visible at INFO level)
• Discovery log level reduced to DEBUG — prevents Inbox flooding on repeated scans (2026-02-28)

Client State Logic - Click to expand flowchart

flowchart TD
    A[Client State Check] --> B{Bridge ONLINE?}
    B -->|No| C[Client OFFLINE]
    B -->|Yes| D{Session exists?}
    D -->|No| E[Client OFFLINE]
    D -->|Yes| F{Update < 60s ago?}
    F -->|No| G[Client OFFLINE - Timeout]
    F -->|Yes| H[Client ONLINE]

    style H fill:#d4edda
    style C fill:#f8d7da
    style E fill:#f8d7da
    style G fill:#fff3cd

Loading

Session Timeout Behavior - Click to expand sequence diagram

sequenceDiagram
    participant Device
    participant WebSocket
    participant ClientHandler
    participant Monitor

    Device->>WebSocket: Playing media
    WebSocket->>ClientHandler: Session update (t=0s)
    Note over ClientHandler: Status: ONLINE

    Device->>Device: Power OFF
    Note over WebSocket: No more updates

    Monitor->>ClientHandler: Check timeout (t=30s)
    Note over ClientHandler: 30s < 60s → Still ONLINE

    Monitor->>ClientHandler: Check timeout (t=60s)
    Note over ClientHandler: 60s ≥ 60s → Timeout!
    ClientHandler->>ClientHandler: Status: OFFLINE

Loading

Outcomes

• Client status reflects device connectivity state
• 60-second timeout window for disconnection detection
• 30-second check interval
• WebSocket used when available, polling as fallback

Testing

• Unit tests for session timeout logic
• Unit tests for state calculation
• Integration tests for task coordination
• Mock-based testing of WebSocket fallback
• ⏳ Manual testing with physical devices (in progress)

Phase 5: Quality Assurance & Testing ✅ Core Complete / 🚧 Code Cleanups & Interactive Tests In Progress

🧪 Comprehensive Testing & Code Quality - Click to expand

Automated Testing

• Unit Tests: Session timeout, state management, WebSocket lifecycle
• Integration Tests: Task coordination, event flow, discovery
• Code Coverage: >80% for critical components
• Regression Tests: Zero regressions in existing functionality
• Build Validation: Zero warnings in hand-written code

Test Results

Test Suite	Tests	Status	Coverage
ClientHandlerTest	35	✅ Pass	87%
ClientHandlerExtrapolationTest	6	✅ Pass	100%
ClientCommandRouterTest	16	✅ Pass	90%
DeviceIdSanitizerTest	10	✅ Pass	100%
TickConverterTest	9	✅ Pass	100%
SessionTimeoutMonitorTest	7	✅ Pass	95%
ServerHandlerTest	89	✅ Pass	85%
TaskManagerTest	18	✅ Pass	92%
WebSocketTaskTest	24	✅ Pass	78%
DiscoveryIntegrationTest	39	✅ Pass	83%
Total	253	✅ All Pass	88% avg

Manual Testing Plan

• Device Testing: Fire TV, Android phone, web client
• State Transitions: Power on/off, sleep/wake, network disconnect
• Multi-Client: Concurrent clients with independent states
• WebSocket Fallback: Simulate connection failures
• Long-Running Stability: 24-hour continuous operation
• Edge Cases: Rapid connect/disconnect, multiple state changes

Code Quality Metrics

• ✅ Spotless: All formatting rules enforced
• ✅ Null Safety: @NonNull / @NonNullByDefault annotations enforced
• ✅ Warnings: Zero in hand-written code (1,558 in generated code suppressed)
• ✅ Build: Clean Maven build with validation

Coding Guidelines Compliance 🚧 Code Cleanups In Progress

Active work to align with the official openHAB Java Coding Style:

#	Violation	Status
V1	SLF4J-only logging (replace System.out, printStackTrace)	✅ Complete (2026-02-26)
V2	@NonNullByDefault on all non-DTO classes	✅ Complete (2026-02-26)
V3	Remove FQCNs from method bodies — add imports	✅ Complete (2026-03-02)
V4	Read configuration in initialize() not handleCommand()	🚧 In Progress
V5	Inject WebSocketClientFactory as OSGi service	🚧 In Progress

Phase 6: Documentation & Cleanup 📝 Planned

📚 Documentation Updates - Click to expand

Documentation Tasks

• Update README with WebSocket behavior
• Add troubleshooting guide
• Document session timeout configuration
• Add architecture diagrams to docs
• Update channel descriptions
• Add examples for rules/scripts
• Create migration guide from original binding (comparison table, upgrade steps, compatibility notes)

Cleanup Tasks

• Remove deprecated configuration options
• Clean up TODOs in code
• Final code review
• Update copyright notices
• Verify all tests documented

---

📊 Implementation Progress

gantt
    title Jellyfin Binding Rewrite Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    API Generator Evaluation    :done, p1, 2025-01-15, 2025-01-25
    section Phase 2
    Server Discovery            :done, p2, 2025-01-26, 2025-02-02
    section Phase 3
    WebSocket & Clients         :done, p3, 2025-02-03, 2025-02-08
    section Phase 4
    Client State Management     :done, p4, 2025-02-09, 2025-02-13
    section Phase 5
    Testing & QA                :active, p5, 2025-02-13, 2026-04-30
    section Phase 6
    Documentation               :p6, 2026-05-01, 2026-05-15

Loading

Overall Progress: 🟩🟩🟩🟩🟨⬜ ~85% Complete (code cleanups and interactive tests in progress)

---

Related Issues & References

GitHub Issues

• Fixes: [jellyfin] SDK Version 1.4.x no longer supports recent Jellyfin Server Versions (>10.8) #17674 - SDK Version 1.4.x no longer supports recent Jellyfin Server Versions (>10.8)
• Replaces: [jellyfin] Add support for server versions > 10.8 #17757 - Draft PR with incomplete implementation

External Documentation

• Jellyfin API Documentation
• Jellyfin WebSocket Documentation
• OpenAPI Generator

---

👥 Acknowledgments

Original Author

@GiviMAD - Created the original Jellyfin binding (2022)

Current Implementation

@pgfeller (Patrik Gfeller) - Complete rewrite with WebSocket support, modernized API client, and accurate client state management

AI Assistance

This rewrite was developed with the assistance of GitHub Copilot (Claude Sonnet 4.6, GPT-5.1-Codex-Max Preview, Raptor mini Preview) for:

• Architecture design and implementation planning
• Code generation and refactoring
• Test case development
• Documentation and diagrams
• Code review and quality assurance

The AI agent followed structured instruction files and development workflows to ensure:

• ✅ Consistent code quality and conventions
• ✅ Comprehensive test coverage
• ✅ Proper error handling and logging
• ✅ Complete documentation

Community

Thanks to the openHAB community for testing, feedback, and issue reports that guided this rewrite.

---

📋 Pre-Merge Checklist

• Core implementation complete (Phases 1-4)
• Automated tests passing (253/253, 88% coverage)
• Zero warnings in hand-written code
• Build succeeds with Maven validation
• Code formatting enforced (Spotless)
• Coding guidelines V1 (SLF4J logging) — complete
• Coding guidelines V2 (@NonNullByDefault) — complete
• Coding guidelines V3 (FQCNs) — complete (2026-03-02)
• Coding guidelines V4–V5 (config lifecycle, service injection) — in progress
• Manual testing with physical devices
• Documentation updated
• Breaking changes documented (vs. original binding)
• Migration guide provided (upgrade path from GiviMAD binding)
• Final code review

---

🚀 Next Steps After Merge

1. Community Testing: Gather feedback from early adopters
2. Performance Monitoring: Track WebSocket stability in production
3. Feature Enhancements:
   • Additional media control actions
   • Library browsing capabilities
   • Advanced automation scenarios
4. Bug Fixes: Address issues reported by community
5. Documentation: Video tutorials and advanced examples

---

Status: 🟡 In Progress (code cleanups and interactive tests in progress)

Estimated Ready for Review: End of April 2026

Questions? Comment below or reach out in the openHAB Community Forum

[pgfeller]

Hi @holgerfriedrich, @J-N-K, @wborn & @openhab/core-maintainers

to get rid of the Kotlin/Android SDK for Jellyfin to reduce the bundle files and to be more flexible in regards to API version(s) I try to automatically generate the API wrapper code. As expected, the generated code does not pass all the checks of the maven build:

org/openhab/binding/jellyfin/internal/api/generated/legacy/model/MediaStream.java:[294,12] The @NonNull field bitRate may not have been initialized

Of course I try to minimize the violations, but for some I would like to add exception(s) to suppressions.xml. I assume it is possible, to do this in the binding pom.xml - but I do not know what is best practice.

Advice would be appreciated. E.g. if a minimal set for generated code is defined in the tools - or if a different approach is prefered.

[holgerfriedrich]

@pgfeller generated code is always some kind of special case.
We have defined a few exceptions in /tools/static-code-analysis/checkstyle/suppressions.xml (both in core and in add-ons repo).

The conditions for adding files there is something maybe @openhab/add-ons-maintainers can comment on.

[pgfeller]

@holgerfriedrich thank you for your reply. I did modify the supressions.xml on my local machine - but was not able to get rid the errors. Fortunately the main pom.xml is already prepared to handle generated code - I was just not aware of this:

        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>3.13.0</version>
          <configuration>
            <compilerId>eclipse</compilerId>
            <compilerArgs>
              <!-- ... -->
              <arg>${project.build.directory}/dependency</arg>
              <!-- ... -->
              <arg>-nowarn:[${project.build.directory}/generated-sources]</arg>
            </compilerArgs>
            <showWarnings>true</showWarnings>
            <showDeprecation>true</showDeprecation>
          </configuration>
          <dependencies>
            <!-- ... -->
          </dependencies>
        </plugin>

If I move the code into generated-sources the checks are skipped. I'll now modify the code generation scripts accordingly ...

[lsiepel]

Almost 500 files and 375k lines of code. Would it be possible to reduce the size by only generating parts, specific versions or have a base version and delta ?
What are your plans / goals, maybe we shoudl discuss that before you do all this work and we are not able to review.

[pgfeller]

@lsiepel - Yep; I agree that this is an issue; and it is on my list. One idea is that we do not checking the generated code at all - but generate it during the maven build on the fly. The other is to identify what files are needed - but I fear this analysis ...
But I do not think that it makes much sense to review the generated code - or what do you think; as if we generate it on the fly we do not have a review. So in worst case it would be a trade off between the jetbrains/kotlin runtime dependency and the more complex setup - or generated code files in the repo that we do not review. I did not check the tree-shaking yet - but I assume the new approach needs less space and simplifies the dependency tree.

As said ... I'm aware, but do not know what is the best approach. An early discussion makes sense - as I did not find another add-on using generated code in that way. But I'm confident there'll be a solution. But I'm open for all approaches - even to drop the work and to go back to the Android SDK. For me the support of the new server versions are the main motivation for the work as I plan to use them in my setup.

What would be the audience for such a discussion and what do you think about the trade offs? For sure there are also other possibilities - as I did not a full investigation on that one yet.

[pgfeller]

Updating PR description to reflect current state (coding guidelines compliance in progress, flaky test noted). No code review comments — description update only.

[jlaur]

This should be targeting main rather than 5.1.x.

[pgfeller]

This should be targeting main rather than 5.1.x.

Yes - I'll change the target branch once the PR is ready for final review - as I use 5.1.x for development (testing the binding on my productive system), this gives me a better view of the changes and things I'll need to remove from the PR to make sure I do not include some of my development help stuff ...