recloudstream / recloudstream/cloudstream

[Bug/Enhancement] Implement graceful fallback for Hardware Decoder failures (MediaTek compatibility)

Open
#2,472 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
Kotlin
Stars
10.7k
Forks
1.1k
Avg merge
1d 23h
Merged PRs (30d)
15

Description

Current Case

Currently, CloudStream appears to aggressively enforce Hardware Acceleration (MediaCodec). On certain devices (specifically MediaTek chipsets on Android 12+), if the Hardware Decoder fails to initialize or encounters a buffer error, the app does not catch the error. Instead, the Android OS triggers a secure lock (Keyguard) to protect the display surface.

The specific case:
On v4.6.0+ (ExoPlayer/Media3 1.8.0), playing network streams on MediaTek devices causes an immediate device lock due to c2.mtk.avc.decoder failures. This was not present in v4.5.4.

The Solution Proposal

Automatic Fallback Mechanism in the player initialization logic:

  1. Detect Decoder Failure: Listen for ion allocation errors or MediaCodec initialization failures (as seen in the logs below).
  2. Fallback: If the specific Hardware Decoder fails, automatically retry playback using the Software Decoder (or disable HW acceleration for that session) instead of letting the OS handle the crash/lock.
Alternatives
  • Sticking to v4.5.4 (works, but outdated).
  • Using external players (works, but loses watch history tracking).
Additional context / Logs

This improvement would prevent "Black Screen" or "Device Lock" issues on a wide range of budget devices using MediaTek drivers that are sensitive to newer ExoPlayer configurations.

Log evidence of the unhandled driver failure:

02-01 14:43:59.894 28134 I CCodec  : Created component [c2.mtk.avc.decoder]
02-01 14:43:59.939 28134 E ion     : ioctl c0044901 failed with code -1: Invalid argument
02-01 14:44:00.241 27658 I libPerfCtl: fbcNotifySbeRescue ret=-1
Steps to reproduce (On a Mediatek Chipset Device)
  1. Install CloudStream v4.6.0 or higher (Default settings).
  2. Open any network stream (movie/episode).
  3. Wait for the player to initialize.
  4. Observe: The device immediately locks and requires unlocking to continue.
Expected behavior

The video should play continuously without the device locking (verified working in v4.5.4).

https://github.com/user-attachments/assets/bd9df0bf-7694-4154-b606-3503ec9a79bc

Actual behavior

The device forces a secure lock immediately upon video load (recorded in 4.6.2-PRE, also happens in 4.6.0)

https://github.com/user-attachments/assets/9bf1ae93-3d5a-4346-9db9-c81d0730fa95

Cloudstream version and commit hash

4.6.2-PRE 4e2bfd3

Android version

Tecno Camon 18T
Android 12

Logcat

https://github.com/user-attachments/files/24991286/logcat_2026_02_01_14_44.txt

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in the player initialization logic and trace MediaCodec or ExoPlayer/Media3 decoder-error handling, reproducing the failure on the listed MediaTek Android 12 device with the provided logcat. The change is done when a hardware decoder initialization or buffer failure falls back to software decoding or disables hardware acceleration for the session, allowing network playback to continue without a black screen or device lock.

Written by the indexing model from the issue text.

Assessment

Tech stack
android, kotlin
Domain
mobile
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.