---

@Documented
@Retention(value = CLASS)
@Target(value = )
@UnstableApi
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation UnstableApi

---

Signifies that a public API (class, method or field) is subject to incompatible changes, or even removal, in a future release.

The presence of this annotation implies nothing about the quality or performance of the API in question, only the fact that it is not "API-frozen."

This library follows semantic versioning and the stable API forms the 'public' API for the purposes of the versioning rules. Therefore an API bearing this annotation is exempt from any compatibility guarantees implied by the semantic versioning rules.

It is generally safe for applications to depend on unstable APIs, at the cost of some extra work during upgrades. However it is generally inadvisable for libraries (which get included on users' CLASSPATHs, outside the library developers' control) to do so.

Requesting additions to the stable API

The Media3 stable API (i.e. those public API symbols that are not annotated with this annotation) is designed to allow developers to achieve common media-related tasks. If you have a use-case that you are unable to achieve using the stable API, and think you should be able to, please file an issue on our GitHub issue tracker with the full context of what you're doing, and what symbols you would need to be part of the stable API. We will consider each request on a case-by-case basis.

Opting in to use unstable APIs

By default usages of APIs annotated with this annotation generate lint errors in Gradle and Android Studio, in order to alert developers to the risk of breaking changes.

Individual usage sites or whole packages can be opted-in to suppress the lint error by using the androidx.annotation.OptIn annotation.

In a Java class:

import androidx.annotation.OptIn;
import androidx.media3.common.util.UnstableApi;
...
= UnstableApi.class)
private void methodUsingUnstableApis() { ... }

In a package-info.java file, to opt-in a whole package:

= UnstableApi.class)
package name.of.your.package;

import androidx.annotation.OptIn;
import androidx.media3.common.util.UnstableApi;

In Kotlin:

import androidx.annotation.OptIn
import androidx.media3.common.util.UnstableApi
...

private fun methodUsingUnstableApis() { ... }

Whole projects can be opted-in by suppressing the specific lint error in their lint.xml file:

<?xml version="1.0" encoding="utf-8"?>
<lint>
  <issue id="UnsafeOptInUsageError">
    <option name="opt-in" value="androidx.media3.common.util.UnstableApi" />
  </issue>
</lint>