Merge pull request #270 from androidx/release-1.0.0

1.0.0

.github/ISSUE_TEMPLATE/bug.yml

@@ -5,18 +5,22 @@ body:
   - type: markdown
     attributes:
       value: |
-        We can only process bug reports that are actionable. Unclear bug reports or reports with insufficient information may not get attention.
+        We can only process bug reports that are actionable. Unclear bug reports or reports with
+        insufficient information may not get attention.
 
         Before filing a bug:
         -------------------------
 
-        - Search existing issues, including issues that are closed: https://github.com/androidx/media/issues?q=is%3Aissue
-        - For ExoPlayer-related bugs, please also check the ExoPlayer tracker: https://github.com/google/ExoPlayer/issues?q=is%3Aissue
+        - Search existing issues, including issues that are closed:
+          https://github.com/androidx/media/issues?q=is%3Aissue
+        - For ExoPlayer-related bugs, please also check for existing issues on the ExoPlayer
+          tracker: https://github.com/google/ExoPlayer/issues?q=is%3Aissue
   - type: dropdown
     attributes:
       label: Media3 Version
       description: What version of Media3 are you using?
       options:
+        - 1.0.0
         - 1.0.0-rc02
         - 1.0.0-rc01
         - 1.0.0-beta03

.github/ISSUE_TEMPLATE/feature_request.md

@@ -10,11 +10,12 @@ Before filing a feature request:
 -----------------------
 - Search existing open issues, specifically with the label ‘enhancement’:
   https://github.com/androidx/media/labels/enhancement
-- For ExoPlayer-related feature requests, please also check the ExoPlayer
-  tracker:
+- For ExoPlayer-related feature requests, please also check for existing feature
+  requests on the ExoPlayer tracker:
   https://github.com/google/ExoPlayer/labels/enhancement
-- Search existing pull requests: https://github.com/androidx/media/pulls,
-  https://github.com/google/ExoPlayer/pulls
+- Search existing pull requests:
+    - On this tracker: https://github.com/androidx/media/pulls,
+    - On the ExoPlayer tracker: https://github.com/google/ExoPlayer/pulls
 
 When filing a feature request:
 -----------------------

.github/ISSUE_TEMPLATE/question.md

@@ -15,7 +15,8 @@ Before filing a question:
 - Ask general Android development questions on Stack Overflow
 - Search existing issues, including issues that are closed
   https://github.com/androidx/media/issues?q=is%3Aissue
-- For ExoPlayer-related questions, please also check the ExoPlayer tracker:
+- For ExoPlayer-related questions, please also check for existing questions on
+  the ExoPlayer tracker:
   https://github.com/google/ExoPlayer/issues?q=is%3Aissue
 
 When filing a question:

CONTRIBUTING.md

@@ -5,12 +5,10 @@
 We use the [AndroidX Media issue tracker][] to track bugs, feature requests and
 questions.
 
-We are still handling ExoPlayer issues on the [ExoPlayer GitHub issue tracker][]
-while the ExoPlayer and AndroidX Media projects coexist.
-
 Before filing a new issue, please search the trackers to check if it's already
 covered by an existing report. Avoiding duplicates helps us maximize the time we
-can spend fixing bugs and adding new features.
+can spend fixing bugs and adding new features. You will also find older issues
+on our [ExoPlayer GitHub issue tracker][].
 
 When filing an issue, be sure to provide enough information for us to
 efficiently diagnose and reproduce the problem. In particular, please include

README.md

@@ -3,36 +3,35 @@
 AndroidX Media is a collection of libraries for implementing media use cases on
 Android, including local playback (via ExoPlayer) and media sessions.
 
-## Current status
+## Documentation
 
-AndroidX Media is currently in release candidate and we welcome your feedback
-via the [issue tracker][]. Please consult the [release notes][] for more details
-about the current release.
+*   The [developer guide][] provides a wealth of information.
+*   The [class reference][] documents the classes and methods.
+*   The [release notes][] document the major changes in each release.
+*   Follow our [developer blog][] to keep up to date with the latest
+    developments!
 
-ExoPlayer's new home will be in AndroidX Media, but for now we are publishing it
-both in AndroidX Media and via the existing [ExoPlayer project][] and we are
-still handling ExoPlayer issues on the [ExoPlayer issue tracker][].
+[developer guide]: https://developer.android.com/guide/topics/media/media3
+[class reference]: https://developer.android.com/reference/androidx/media3/common/package-summary
+[release notes]: RELEASENOTES.md
+[developer blog]: https://medium.com/google-exoplayer
+
+## Migration for existing ExoPlayer and MediaSession projects
+
+You'll find a [migration guide for existing ExoPlayer and MediaSession users][]
+on developer.android.com.
+
+[migration guide for existing ExoPlayer and MediaSession users]: https://developer.android.com/guide/topics/media/media3/getting-started/migration-guide
 
-You'll find some [Media3 documentation on developer.android.com][], including a
-[migration guide for existing ExoPlayer and MediaSession users][].
+## API stability
 
 AndroidX Media releases provide API stability guarantees, ensuring that the API
 surface remains backwards compatible for the most commonly used APIs. APIs
 intended for more advanced use cases are marked as unstable. To use an unstable
 method or class without lint warnings, you’ll need to add the OptIn annotation
 before using it. For more information see the [UnstableApi][] documentation.
 
-For a high level overview of the initial version of AndroidX Media please see
-the Android Dev Summit talk [What's next for AndroidX Media and ExoPlayer][].
-
-[release notes]: RELEASENOTES.md
-[issue tracker]: https://github.com/androidx/media/issues/new
-[ExoPlayer project]: https://github.com/google/ExoPlayer
-[ExoPlayer issue tracker]: https://github.com/google/ExoPlayer/issues
 [UnstableApi]: https://github.com/androidx/media/blob/main/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
-[What's next for AndroidX Media and ExoPlayer]: https://youtu.be/sTIBDcyCmCg
-[Media3 documentation on developer.android.com]: https://developer.android.com/guide/topics/media/media3
-[migration guide for existing ExoPlayer and MediaSession users]: https://developer.android.com/guide/topics/media/media3/getting-started/migration-guide
 
 ## Using the libraries
 

RELEASENOTES.md

@@ -1,5 +1,12 @@
 # Release notes
 
+### 1.0.0 (2023-03-22)
+
+This release corresponds to the
+[ExoPlayer 2.18.5 release](https://github.com/google/ExoPlayer/releases/tag/r2.18.5).
+
+There are no changes since 1.0.0-rc02.
+
 ### 1.0.0-rc02 (2023-03-02)
 
 This release corresponds to the

constants.gradle

@@ -12,8 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 project.ext {
-    releaseVersion = '1.0.0-rc02'
-    releaseVersionCode = 1_000_000_2_02
+    releaseVersion = '1.0.0'
+    releaseVersionCode = 1_000_000_3_00
     minSdkVersion = 16
     appTargetSdkVersion = 33
     // API version before restricting local file access.

libraries/common/src/main/java/androidx/media3/common/MediaLibraryInfo.java

@@ -29,11 +29,11 @@ public final class MediaLibraryInfo {
 
   /** The version of the library expressed as a string, for example "1.2.3" or "1.2.3-beta01". */
   // Intentionally hardcoded. Do not derive from other constants (e.g. VERSION_INT) or vice versa.
-  public static final String VERSION = "1.0.0-rc02";
+  public static final String VERSION = "1.0.0";
 
   /** The version of the library expressed as {@code TAG + "/" + VERSION}. */
   // Intentionally hardcoded. Do not derive from other constants (e.g. VERSION) or vice versa.
-  public static final String VERSION_SLASHY = "AndroidXMedia3/1.0.0-rc02";
+  public static final String VERSION_SLASHY = "AndroidXMedia3/1.0.0";
 
   /**
    * The version of the library expressed as an integer, for example 1002003300.
@@ -47,7 +47,7 @@ public final class MediaLibraryInfo {
    * (123-045-006-3-00).
    */
   // Intentionally hardcoded. Do not derive from other constants (e.g. VERSION) or vice versa.
-  public static final int VERSION_INT = 1_000_000_2_02;
+  public static final int VERSION_INT = 1_000_000_3_00;
 
   /** Whether the library was compiled with {@link Assertions} checks enabled. */
   public static final boolean ASSERTIONS_ENABLED = true;

libraries/common/src/main/java/androidx/media3/common/Timeline.java

@@ -813,6 +813,7 @@ public long getAdDurationUs(int adGroupIndex, int adIndexInAdGroup) {
      * adGroupIndex}, or {@link AdPlaybackState#AD_STATE_UNAVAILABLE} if not yet known.
      *
      * @param adGroupIndex The ad group index.
+     * @param adIndexInAdGroup The index of the ad in the ad group.
      * @return The state of the ad, or {@link AdPlaybackState#AD_STATE_UNAVAILABLE} if not yet
      *     known.
      */

libraries/common/src/main/java/androidx/media3/common/Tracks.java

@@ -297,6 +297,7 @@ public boolean isTypeSupported(@C.TrackType int trackType) {
    * Returns true if at least one track of type {@code trackType} is {@link
    * Group#isTrackSupported(int, boolean) supported}.
    *
+   * @param trackType The track type to query support for.
    * @param allowExceedsCapabilities Whether to consider the track as supported if it has a
    *     supported {@link Format#sampleMimeType MIME type}, but otherwise exceeds the advertised
    *     capabilities of the device. For example, a video track for which there's a corresponding

libraries/common/src/main/java/androidx/media3/common/util/Util.java

@@ -1555,6 +1555,7 @@ public static long getMediaDurationForPlayoutDuration(long playoutDuration, floa
    * Returns the playout duration of {@code mediaDuration} of media.
    *
    * @param mediaDuration The duration to scale.
+   * @param speed The factor by which playback is sped up.
    * @return The scaled duration, in the same units as {@code mediaDuration}.
    */
   @UnstableApi

libraries/datasource/src/main/java/androidx/media3/datasource/DataSourceUtil.java

@@ -56,6 +56,7 @@ public static byte[] readToEnd(DataSource dataSource) throws IOException {
    * array containing the read data.
    *
    * @param dataSource The source from which to read.
+   * @param length The number of bytes to read.
    * @return The read data.
    * @throws IOException If an error occurs reading from the source.
    * @throws IllegalStateException If the end of the source was reached before {@code length} bytes

libraries/datasource/src/main/java/androidx/media3/datasource/DefaultDataSource.java

@@ -148,6 +148,7 @@ public DefaultDataSource createDataSource() {
    * Constructs a new instance, optionally configured to follow cross-protocol redirects.
    *
    * @param context A context.
+   * @param allowCrossProtocolRedirects Whether to allow cross-protocol redirects.
    */
   @UnstableApi
   public DefaultDataSource(Context context, boolean allowCrossProtocolRedirects) {

libraries/effect/src/androidTest/java/androidx/media3/effect/BitmapTestUtil.java

@@ -106,6 +106,8 @@ public static Bitmap createArgb8888BitmapFromRgba8888Image(Image image) {
   /**
    * Returns a solid {@link Bitmap} with every pixel having the same color.
    *
+   * @param width The width of image to create, in pixels.
+   * @param height The height of image to create, in pixels.
    * @param color An RGBA color created by {@link Color}.
    */
   public static Bitmap createArgb8888BitmapWithSolidColor(int width, int height, int color) {

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlaybackException.java

@@ -131,6 +131,8 @@ public static ExoPlaybackException createForSource(IOException cause, int errorC
    * Creates an instance of type {@link #TYPE_RENDERER}.
    *
    * @param cause The cause of the failure.
+   * @param rendererName The {@linkplain Renderer#getName() name} of the renderer in which the
+   *     failure occurred.
    * @param rendererIndex The index of the renderer in which the failure occurred.
    * @param rendererFormat The {@link Format} the renderer was using at the time of the exception,
    *     or null if the renderer wasn't using a {@link Format}.

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/drm/OfflineLicenseHelper.java

@@ -100,6 +100,7 @@ public static OfflineLicenseHelper newWidevineInstance(
    *     their own license URL.
    * @param forceDefaultLicenseUrl Whether to use {@code defaultLicenseUrl} for key requests that
    *     include their own license URL.
+   * @param dataSourceFactory A factory from which to obtain {@link DataSource} instances.
    * @param optionalKeyRequestParameters An optional map of parameters to pass as the last argument
    *     to {@link MediaDrm#getKeyRequest}. May be null.
    * @param eventDispatcher A {@link DrmSessionEventListener.EventDispatcher} used to distribute

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/mediacodec/MediaCodecRenderer.java

@@ -362,6 +362,7 @@ private static String buildCustomDiagnosticInfo(int errorCode) {
 
   /**
    * @param trackType The {@link C.TrackType track type} that the renderer handles.
+   * @param codecAdapterFactory A factory for {@link MediaCodecAdapter} instances.
    * @param mediaCodecSelector A decoder selector.
    * @param enableDecoderFallback Whether to enable fallback to lower-priority decoders if decoder
    *     initialization fails. This may result in using a decoder that is less efficient or slower

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/offline/SegmentDownloader.java

@@ -326,6 +326,7 @@ public final void remove() {
   /**
    * Loads and parses a manifest.
    *
+   * @param dataSource The source to use when loading the manifest.
    * @param dataSpec The manifest {@link DataSpec}.
    * @param removing Whether the manifest is being loaded as part of the download being removed.
    * @return The loaded manifest.

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java

@@ -2446,6 +2446,7 @@ private void setParametersInternal(Parameters parameters) {
    *     renderer, track group and track (in that order).
    * @param rendererMixedMimeTypeAdaptationSupports The {@link AdaptiveSupport} for mixed MIME type
    *     adaptation for the renderer.
+   * @param params The parameters to use for the track selection.
    * @return The {@link ExoTrackSelection.Definition}s for the renderers. A null entry indicates no
    *     selection was made.
    * @throws ExoPlaybackException If an error occurs while selecting the tracks.

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/MappingTrackSelector.java

@@ -289,6 +289,7 @@ public TrackGroupArray getTrackGroups(int rendererIndex) {
      *
      * @param rendererIndex The renderer index.
      * @param groupIndex The index of the track group.
+     * @param trackIndices The indices of the tracks in the track group for which to query support.
      * @return The {@link AdaptiveSupport}.
      */
     public @AdaptiveSupport int getAdaptiveSupport(

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/RandomTrackSelection.java

@@ -68,12 +68,15 @@ public Factory(int seed) {
   private int selectedIndex;
 
   /**
+   * Creates a new instance.
+   *
    * @param group The {@link TrackGroup}. Must not be null.
    * @param tracks The indices of the selected tracks within the {@link TrackGroup}. Must not be
    *     null or empty. May be in any order.
+   * @param type The {@link Type} of this track selection.
    * @param random A source of random numbers.
    */
-  public RandomTrackSelection(TrackGroup group, int[] tracks, int type, Random random) {
+  public RandomTrackSelection(TrackGroup group, int[] tracks, @Type int type, Random random) {
     super(group, tracks, type);
     this.random = random;
     selectedIndex = random.nextInt(length);

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/video/DecoderVideoRenderer.java

@@ -651,6 +651,7 @@ protected final void setOutput(@Nullable Object output) {
    *
    * <p>The default implementation does not allow decoder reuse.
    *
+   * @param decoderName The name of the decoder.
    * @param oldFormat The previous format.
    * @param newFormat The new format.
    * @return The result of the evaluation.

libraries/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DashChunkSource.java

@@ -50,6 +50,8 @@ interface Factory {
      *     if unknown.
      * @param enableEventMessageTrack Whether to output an event message track.
      * @param closedCaptionFormats The {@link Format Formats} of closed caption tracks to be output.
+     * @param playerEmsgHandler The track output to write emsg messages to, or null if emsgs
+     *     shouldn't be written.
      * @param transferListener The transfer listener which should be informed of any data transfers.
      *     May be null if no listener is available.
      * @param playerId The {@link PlayerId} of the player using this chunk source.
@@ -75,8 +77,9 @@ DashChunkSource createDashChunkSource(
    * Updates the manifest.
    *
    * @param newManifest The new manifest.
+   * @param newPeriodIndex The index of the period covered by {@code newManifest}.
    */
-  void updateManifest(DashManifest newManifest, int periodIndex);
+  void updateManifest(DashManifest newManifest, int newPeriodIndex);
 
   /**
    * Updates the track selection.

libraries/exoplayer_hls/src/main/java/androidx/media3/exoplayer/hls/HlsMediaPeriod.java

@@ -104,13 +104,17 @@ public final class HlsMediaPeriod implements MediaPeriod, HlsPlaylistTracker.Pla
    *     be null if no listener is available.
    * @param drmSessionManager The {@link DrmSessionManager} to acquire {@link DrmSession
    *     DrmSessions} with.
+   * @param drmEventDispatcher A {@link DrmSessionEventListener.EventDispatcher} used to distribute
+   *     DRM-related events.
    * @param loadErrorHandlingPolicy A {@link LoadErrorHandlingPolicy}.
    * @param eventDispatcher A dispatcher to notify of events.
    * @param allocator An {@link Allocator} from which to obtain media buffer allocations.
    * @param compositeSequenceableLoaderFactory A factory to create composite {@link
    *     SequenceableLoader}s for when this media source loads data from multiple streams.
    * @param allowChunklessPreparation Whether chunkless preparation is allowed.
+   * @param metadataType The type of metadata to extract from the period.
    * @param useSessionKeys Whether to use #EXT-X-SESSION-KEY tags.
+   * @param playerId The ID of the current player.
    */
   public HlsMediaPeriod(
       HlsExtractorFactory extractorFactory,

libraries/exoplayer_hls/src/main/java/androidx/media3/exoplayer/hls/playlist/HlsMediaPlaylist.java

@@ -462,16 +462,20 @@ public RenditionReport(Uri playlistUri, long lastMediaSequence, int lastPartInde
   public final ServerControl serverControl;
 
   /**
+   * Constructs an instance.
+   *
    * @param playlistType See {@link #playlistType}.
    * @param baseUri See {@link #baseUri}.
    * @param tags See {@link #tags}.
    * @param startOffsetUs See {@link #startOffsetUs}.
+   * @param preciseStart See {@link #preciseStart}.
    * @param startTimeUs See {@link #startTimeUs}.
    * @param hasDiscontinuitySequence See {@link #hasDiscontinuitySequence}.
    * @param discontinuitySequence See {@link #discontinuitySequence}.
    * @param mediaSequence See {@link #mediaSequence}.
    * @param version See {@link #version}.
    * @param targetDurationUs See {@link #targetDurationUs}.
+   * @param partTargetDurationUs See {@link #partTargetDurationUs}.
    * @param hasIndependentSegments See {@link #hasIndependentSegments}.
    * @param hasEndTag See {@link #hasEndTag}.
    * @param hasProgramDateTime See {@link #hasProgramDateTime}.

libraries/extractor/src/main/java/androidx/media3/extractor/FlacFrameReader.java

@@ -132,6 +132,7 @@ public static boolean checkFrameHeaderFromPeek(
    * there is no guarantee on the peek position.
    *
    * @param input Input stream to get the sample number from (starting from the read position).
+   * @param flacStreamMetadata The FLAC metadata of the stream.
    * @return The frame first sample number.
    * @throws ParserException If an error occurs parsing the sample number.
    * @throws IOException If peeking from the input fails.

libraries/extractor/src/main/java/androidx/media3/extractor/text/webvtt/WebvttCssStyle.java

@@ -152,12 +152,13 @@ public void setTargetVoice(String targetVoice) {
    *   <li>Universal selector matching scores 1.
    * </ul>
    *
+   * <p>See also <a href="https://www.w3.org/TR/CSS2/cascade.html">CSS Cascading</a>.
+   *
    * @param id The id of the cue if present, {@code null} otherwise.
    * @param tag Name of the tag, {@code null} if it refers to the entire cue.
    * @param classes An array containing the classes the tag belongs to. Must not be null.
    * @param voice Annotated voice if present, {@code null} otherwise.
    * @return The score of the match, zero if there is no match.
-   * @see <a href="https://www.w3.org/TR/CSS2/cascade.html">CSS Cascading</a>
    */
   public int getSpecificityScore(
       @Nullable String id, @Nullable String tag, Set<String> classes, @Nullable String voice) {

libraries/session/src/main/java/androidx/media3/session/MediaController.java

@@ -905,13 +905,14 @@ public ListenableFuture<SessionResult> setRating(Rating rating) {
   /**
    * Sends a custom command to the session.
    *
+   * <p>A command is not accepted if it is not a custom command or the command is not in the list of
+   * {@linkplain #getAvailableSessionCommands() available session commands}.
+   *
    * <p>Interoperability: When connected to {@link
    * android.support.v4.media.session.MediaSessionCompat}, {@link SessionResult#resultCode} will
    * return the custom result code from the {@code android.os.ResultReceiver#onReceiveResult(int,
    * Bundle)} instead of the standard result codes defined in the {@link SessionResult}.
    *
-   * <p>A command is not accepted if it is not a custom command.
-   *
    * @param command The custom command.
    * @param args The additional arguments. May be empty.
    * @return A {@link ListenableFuture} of {@link SessionResult} representing the pending