Document the fact that desugar_jdk_libs is required for media3 to work on old API levels

[MGaetan89]

Since 889f435, Media3 uses the desugar_jdk_libs library to use newer Java APIs on older API levels.
For example in Format:

media/libraries/common/src/main/java/androidx/media3/common/Format.java

Line 982 in d833d59

|| (builder.labels.stream().anyMatch(l -> l.value.equals(builder.label))));

This means that applications/libraries using Media3 also need to integrate desugar_jdk_libs. However, this is not documented in the Java 8 support section of the Readme:
https://github.com/androidx/media/tree/release?tab=readme-ov-file#2-turn-on-java-8-support

Would it be possible to add a note about it?

[MGaetan89]

By digging a bit more into this, here are all the newer API usages I could find in production code:

• List.stream()
  

  media/libraries/common/src/main/java/androidx/media3/common/Format.java

  Line 982 in 43d1fa9

  || (builder.labels.stream().anyMatch(l -> l.value.equals(builder.label))));

• Map.getOrDefault()
  

  media/libraries/transformer/src/main/java/androidx/media3/transformer/FrameworkMuxer.java

  Line 150 in 43d1fa9

  trackTokenToPresentationTimeOffsetUs.getOrDefault(trackToken, 0L);

• Map.getOrDefault()
  

  media/libraries/transformer/src/main/java/androidx/media3/transformer/FrameworkMuxer.java

  Line 154 in 43d1fa9

  trackTokenToLastPresentationTimeUs.getOrDefault(trackToken, 0L);

• LongConsumer.accept()
  

  media/libraries/common/src/main/java/androidx/media3/common/audio/SpeedChangingAudioProcessor.java

  Line 213 in 43d1fa9

  callback.accept(calculateSpeedAdjustedTime(inputTimeUs));

• LongConsumer.accept()
  

  media/libraries/common/src/main/java/androidx/media3/common/audio/SpeedChangingAudioProcessor.java

  Line 264 in 43d1fa9

  .accept(calculateSpeedAdjustedTime(pendingCallbackInputTimesUs.remove()));

Since there aren't that many usages, maybe removing desugar_jdk_libs from production could also be a solution?

[tonihei]

Thanks for highlighting this issue!

We added the additional Java8 desugaring before releasing 1.3.0. Our assumption was that this automatically propagates to apps similar to other dependencies. This was unfortunately not the case because of a tooling gap (see https://issuetracker.google.com/203113147).

The tooling gap is now fixed and upgrading our AGP version ensures this requirement automatically propagates to apps depending on our libraries. However, it just triggers a build error if the desugaring is not activated in the app. This means it's not fully automatic and still requires every app developer to add these flags manually to their gradle files.

Given this additional effort and the small number of current usage sites within our code, we decided not to depend on the enhanced desugaring for now to avoid this additional app config burden. Only once other core AndroidX libraries require this as well, we probably reintroduce it for our libraries too in the future.

[MGaetan89]

Given this additional effort and the small number of current usage sites within our code, we decided not to depend on the enhanced desugaring for now to avoid this additional app config burden. Only once other core AndroidX libraries require this as well, we probably reintroduce it for our libraries too in the future.

Will it be worked on internally, or are you open for contributions for this?

[tonihei]

Thanks for considering a contribution! We already have the internal code change in review though and it should appear here soon.

[tonihei]

Thanks for considering a contribution! We already have the internal code change in review though and it should appear here soon.

[MGaetan89]

Thanks @tonihei, I see the changes now.
Do you know if they'll land in 1.4.0-alpha02 (or any followup release)? Or will there be a 1.3.2 release?

[tonihei]

Most likely only in 1.4.0 pre-releases. So far we are not planning to do a 1.3.2.

(Closing the issue now as the original problem has been fixed/avoided)

[cadalt]

any advice/knowledge on what api level this affects back to? i see in the linked issue api 22. what's the latest api level that is affected?

[icbaker]

6ac60c6 removed the problematic usages. It looks like they were mostly introduced in API 24 (e.g. Collection.stream() and LongConsumer), so I think any API level before that is affected.

[cadalt]

@icbaker thank you!