# TiviLux Native 0.4.49 — reliability and smoothness pass

Version code: **65** (baseline: 64 / 0.4.48). Package ID, SDK targets, Media3 version, and signing configuration are unchanged. Build your distribution APK with the same existing signing key. No screens or navigation workflows were redesigned. All original project files are retained.

## 1. HLS crash cause

The uploaded project included `media3-exoplayer:1.5.1` and `media3-ui:1.5.1`, but omitted `media3-exoplayer-hls`. Turning on Prefer HLS generated an `.m3u8` URL. DefaultMediaSourceFactory consequently lacked its HLS implementation. The existing VideoSurface invoked setMediaItem/prepare without catching synchronous media-source construction exceptions, which could escape the Compose effect and close the Activity. The live URL generator also returned only one URL, so there was no normal/TS fallback. These are confirmed source-level defects; the particular TV crash was not reproduced and no device crash log was supplied.

## 2. Exact HLS fix

- Added **only** `androidx.media3:media3-exoplayer-hls:1.5.1`. Other Media3 versions are unchanged.
- HLS ON tries m3u8, the original provider-reported extension, then TS, removing duplicates. HLS OFF retains the original first URL, with TS as a fallback candidate.
- One live playback controller catches synchronous source/preparation exceptions and listens for Media3 playback errors. Failed or prolonged-stalling HLS advances to the next normal/TS candidate within a bounded retry budget.
- Changing the preference regenerates live candidates and the primary live URL. The existing shared player stops the previous loader before preparing the replacement; it does not create another player. A saved VOD session is not overwritten by the transport preference.
- An HLS fallback survives preview/fullscreen handoffs rather than continually retrying HLS on recomposition. Startup/restored Guide previews resolve their own live fallback candidates even before a playingItem exists.
- Live reuse requires both matching content type and ID, preventing a movie/episode with the same provider ID from supplying a Live preview/fullscreen URL.

This contains the identified exception path; it is not a guarantee against every possible Android/codec/device crash.

## 3. Live freeze/stall detection and recovery

The watchdog runs **only** on the normal shared single-channel Live TV player. VOD and MultiView retain their existing playback implementations.

It samples once per second on the player thread, using monotonic elapsed time. It checks rendered video-buffer counts for video feeds; playback position is the fallback for audio-only feeds. READY alone never counts as progress. Counter resets, buffering, and seeks are not accepted as healthy video advancement.

A continuous lack of progress for approximately **20 seconds** starts recovery. Initial startup receives the same grace period. Ordinary short buffering does not trigger recovery. Explicit errors have shorter bounded backoff: 2, 5, then 10 seconds.

Recovery uses the **same channel and same ExoPlayer**:

1. Retry a failed/idle player, or flush by seeking to the current position when seekable. Unseekable progressive/TS feeds need a fresh loader immediately because prepare on a frozen READY player is a no-op.
2. Seek to the default live edge when the item is live and seekable; otherwise re-prepare a fresh media source.
3. Stop the stale loader and re-prepare the same channel URL again, issuing a fresh source request.

Failed/stalled HLS can advance to normal/TS during these steps. Stall stages wait 20, 30, then 45 seconds without progress. There are at most **three automatic recovery actions** per unhealthy episode. A transient READY state or one frame does not replenish the budget; it requires 60 seconds of sustained progress. An exhausted session stays bounded until healthy playback resumes or the viewer tunes another channel.

A small **Reconnecting...** message appears during recovery and disappears on genuine progress. After exhaustion and another 20 seconds, it changes to **Stream unavailable — change channel to retry**.

Recovery is suppressed when lifecycle is not RESUMED, playWhenReady is false, playback is suppressed, or the player is deliberately idle without an error. URL/player changes cancel the old coroutine; screen disposal cancels it as well. No replacement player is allocated. Existing HOME/ON_STOP cleanup remains intact.

## 4. Playback optimizations

Kept existing Media3 HTTP timeouts, decoder fallback, memory-sensitive buffer budgets, live/VOD profiles and shared TextureView. Added safe transport fallback, fresh-loader cleanup, error containment and video-progress recovery. Removed competing generic retries only for the managed live surface; existing VOD/MultiView recovery remains unchanged. No extra live connection or player is introduced by the watchdog.

## 5. UI/navigation performance

- Changed the Guide drawer offset argument from a value read during composition to a deferred lambda read by its graphics layer. Both Guide and native preview continue using the same animation state. Animation frames no longer directly invalidate the whole Guide composition through this argument.
- Retained resting preview-bounds protection and foreground Popup layering.
- Shortened the existing shared movement from 220 to 180 ms. Added a subtle 120 ms graphics-layer reveal for Categories and the main rail without delaying focus or changing their layout.
- Replaced fixed 45/80 ms focus handoff delays in Guide/rail with frame synchronization. Existing DPAD handlers, hold thresholds, channel keys and BACK semantics remain unchanged.
- Cached category ordering and visible-category filtering per content type, published list identity and visibility revision. Hide/unhide, ordering, profile changes and cache clearing invalidate these results. Cache hits avoid repeated preference reads, rank-map construction, sorting and filtering on recomposition.

Audit also found existing catalog visibility caches, background JSON/network processing, background/debounced search, artwork debounce, keyed catalog lists, staged Sports loading and memory budgets. These were preserved. **No Movies/Series catalog limits were added.** Device frame-rate or startup-time improvements have not been benchmarked.

## 6. Files changed

Existing files (Java/Kotlin paths are relative to `app/src/main/java/tv/tivilux/nativeplayer/`):

| File | Change |
| --- | --- |
| `app/build.gradle.kts` | Matching HLS module; version 0.4.49/code 65 |
| `data/XtreamRepository.kt` | Ordered live transport candidates |
| `AppViewModel.kt` | Transport preference refresh; category caches/invalidation |
| `ui/components/LuxComponents.kt` | Managed live session integration; reconnect text; panel reveal |
| `ui/TiviLuxApp.kt` | Shared live integration; deferred drawer state; rail focus/reveal |
| `ui/screens/LiveScreen.kt` | Deferred graphics translation; frame-synchronized focus; category reveal |
| `ui/screens/MultiViewScreen.kt` | Removed one invalid explicit Compose `weight` import; no behavior changes |
| `latest.json` | New version metadata and notes |
| `MainActivity.kt` | Scoped lint annotation for the existing public key override; remote/HOME logic unchanged |
| `ui/screens/PlayerScreen.kt` | Media3 opt-in annotations only; VOD/HUD logic unchanged |
| `data/AppUpdateManager.kt` | API-23-compatible Content-Length parsing |

New files: `data/LiveRecoveryPolicy.java`, `ui/components/LivePlaybackSession.kt`, `verification/LiveRecoveryPolicyCheck.java`, `verification/check_baseline.py`, `latest-v0.4.49.json`, `updates/latest.json`, and this report. Build evidence is in `verification/`.

## 7. Build result

**PASS:** `:app:assembleDebug`, `:app:assembleRelease` (including R8/resource shrinking), and `:app:lintDebug`. Final verification passed after the last source changes. Lint: **0 errors, 14 warnings**. Toolchain: Gradle 8.10.2, AGP 8.7.3, Kotlin 2.0.21, Java 17, compile SDK 35. The release verification APK is unsigned; distribution signing remains your existing builder/keystore workflow. The complete project ZIP contains source/assets and verification evidence, not a differently signed replacement APK.

R8 seed output confirms that the matching HLS factory and its DataSource.Factory constructor are retained in release builds.

The first compilation exposed an existing invalid `androidx.compose.foundation.layout.weight` import in MultiView. Removing that import lets its unchanged RowScope/ColumnScope weight calls resolve correctly. No MultiView layout/control logic was modified. Lint also identified existing missing Media3 opt-in annotations and the inherited key-dispatch restriction; scoped annotations preserve their existing behavior. The updater used API-24-only contentLengthLong despite a min SDK of 23; equivalent Content-Length header parsing now works on API 23.

## 8. Regression verification

Passed executable checks:

- Recovery policy: startup/buffering grace, 20-second stall, backoff stages, error debounce, bounded exhaustion, 60-second sustained recovery reset, transient-progress budget protection, background suppression and foreground grace.
- Existing catalog-cache checks: 50,000-item input, complete ordered results, repeated-cache reuse, source/revision invalidation, clear and immutable output.
- Existing memory-budget checks: live/VOD bounds across low-RAM and normal devices and multiple heap sizes.
- Baseline integrity: all 187 original files retained; 176 byte-identical. Sports screens and schedule repository, profiles, preference stores, catalog screens and detail screens are unchanged. MultiView differs only by its invalid import removal; Activity and VOD PlayerScreen have annotation-only changes; updater has the checked API-23 Content-Length compatibility fix.

**Not device-tested:** launch/login/profile/Home; actual Live playback; Guide↔Categories↔Menu visual smoothness and focus; preview/fullscreen placement; physical DPAD/OK/BACK/channel keys; HLS OFF/ON and failed-manifest TS playback; induced frozen-video/network reconnection; Favorites/hiding/ordering; **Sports game → feed list → feed playback**; Movies/Series/episode playback; Continue Watching/removal; Search; MultiView; Settings/Clear Cache; HOME audio shutdown; two-BACK exit; update download/install. These need provider credentials and an Android TV/Fire TV device. Source preservation and compilation do not prove these end-to-end paths pass.

Suggested first device checks: play a known TS channel, enable HLS, confirm one provider connection; test a channel with unsupported HLS; interrupt and restore its network; open/close Categories and rail repeatedly with held DPAD; switch preview↔fullscreen; test Sports game→feeds→play; finally test VOD, MultiView and HOME audio shutdown. Run a multi-hour Live soak on ONN/Mi Box plus a second device family.

`latest.json`, `latest-v0.4.49.json` and `updates/latest.json` contain matching version metadata and point to the future production 0.4.49 APK. The native APK-builder project ZIP uses one top-level `TiviLux-Native-v0.1/` folder, containing the Android app module and Gradle project. This work does not upload an APK or publish an update. Upload your normally signed APK before publishing the manifest; use the established builder/signing workflow.
