search

androidx / media

Jetpack Media3 support libraries for media use cases, including ExoPlayer, an extensible media player for Android
Apache License 2.0
1.34k stars 315 forks source link

Unstable Api Annotations #1495

Closed Faiyyaz closed 6 days ago

Faiyyaz commented 6 days ago

Hi,

Thank you for such a great library.

I have a question if you see the sample main most of the classes like DemoUtil, DownloadTracker, TrackSelectionDialog etc are using @UnstableApi annotations.

Can you let me know why it is like that?

Also if it is unstable, can you provide a stable example for the same since in our app we need to give quality control, download features etc which used to work fine in exoplayer2 without such annotations.

oceanjules commented 6 days ago

You can see what is meant by "stability" here in the README and UnstableAPI java doc.

In short: it doesn't have to do with quality or performance. You can assume the functions and classes behave as documented. However, the library is not ready to freeze these APIs and commit to long-term backwards compatibility. So use with caution to avoid breaking changes when upgrading the library version.

Faiyyaz commented 6 days ago

Okay so if you are saying those can be removed then can we have stable version of the same example if possible?

oceanjules commented 6 days ago

Stabilising the API is a lengthy process and the full ExoPlayer/media3 API (everything accessible by an application developer like you) is too large to guarantee this kind of stability. We want to be sure that everything we add to the stable API is worth the long-term investment of the team supporting it. There is a trade-off between freezing the APIs too early and allowing the flexible experimental setup like this to evolve over time to something better.

When ExoPlayer moved to the androidx.media3 package, it went through a stabilising stage. We became a part of AndroidX libraries and hence we now adhere to backward-compatibility guarantees between minor versions.

When we do promote APIs to stable, it is announced in the release notes.

If you think your particular use-case cannot be achieved using the stable API only, you could file an issue about stabilising those components. However, looking at the list of classes you pasted: DemoUtil is utility methods for the main demo, DownloadTracker and TrackSelectionDialog are also just examples of how to achieve certain functionality. You are free to copy it over to your project and customize according to your needs. The library as a whole does not rely on these classes.

Faiyyaz commented 6 days ago

Okay the list of features I am trying to achieve are download track, quality control, speed control etc. I copied it over since the same code was used in exoplayer2 to do the same and it used to work fine since many years and even the sample app has the same code as of now

icbaker commented 6 days ago

I copied it over since the same code was used in exoplayer2 to do the same and it used to work fine since many years and even the sample app has the same code as of now

To be clear, nothing has got 'less stable' than in exoplayer2. Just some bits of media3 are now marked as 'more stable' than anything ever was in exoplayer2. You can see more info here: https://developer.android.com/media/media3/exoplayer/migration-guide#background

So if you were happy using the symbols in the exoplayer2 package you should be fine to continue using the same symbols in the media3 package, regardless of whether they're annotated @UnstableApi, and adding @OptIn or suppressing the lint.