public abstract class

VolumeProviderCompat

extends java.lang.Object

 java.lang.Object

↳androidx.media3.session.legacy.VolumeProviderCompat

Gradle dependencies

compile group: 'androidx.media3', name: 'media3-session', version: '1.5.0-alpha01'

  • groupId: androidx.media3
  • artifactId: media3-session
  • version: 1.5.0-alpha01

Artifact androidx.media3:media3-session:1.5.0-alpha01 it located at Google repository (https://maven.google.com/)

Overview

Handles requests to adjust or set the volume on a session. This is also used to push volume updates back to the session after a request has been handled. You can set a volume provider on a session by calling MediaSessionCompat.setPlaybackToRemote(VolumeProviderCompat).

Summary

Fields
public static final intVOLUME_CONTROL_ABSOLUTE

The volume control uses an absolute value.

public static final intVOLUME_CONTROL_FIXED

The volume is fixed and can not be modified.

public static final intVOLUME_CONTROL_RELATIVE

The volume control uses relative adjustment via VolumeProviderCompat.onAdjustVolume(int).

Constructors
publicVolumeProviderCompat(int volumeControl, int maxVolume, int currentVolume)

Create a new volume provider for handling volume events.

publicVolumeProviderCompat(int volumeControl, int maxVolume, int currentVolume, java.lang.String volumeControlId)

Create a new volume provider for handling volume events.

Methods
public final intgetCurrentVolume()

Get the current volume of the provider.

public final intgetMaxVolume()

Get the maximum volume this provider allows.

public final intgetVolumeControl()

Get the volume control type that this volume provider uses.

public final java.lang.StringgetVolumeControlId()

Gets the volume control ID.

public java.lang.ObjectgetVolumeProvider()

Gets the underlying framework object.

public voidonAdjustVolume(int direction)

Override to handle requests to adjust the volume of the current output.

public voidonSetVolumeTo(int volume)

Override to handle requests to set the volume of the current output.

public voidsetCallback(VolumeProviderCompat.Callback callback)

Sets a callback to receive volume changes.

public final voidsetCurrentVolume(int currentVolume)

Set the current volume and notify the system that the volume has been changed.

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Fields

public static final int VOLUME_CONTROL_FIXED

The volume is fixed and can not be modified. Requests to change volume should be ignored.

public static final int VOLUME_CONTROL_RELATIVE

The volume control uses relative adjustment via VolumeProviderCompat.onAdjustVolume(int). Attempts to set the volume to a specific value should be ignored.

public static final int VOLUME_CONTROL_ABSOLUTE

The volume control uses an absolute value. It may be adjusted using VolumeProviderCompat.onAdjustVolume(int) or set directly using VolumeProviderCompat.onSetVolumeTo(int).

Constructors

public VolumeProviderCompat(int volumeControl, int maxVolume, int currentVolume)

Create a new volume provider for handling volume events. You must specify the type of volume control and the maximum volume that can be used.

Parameters:

volumeControl: The method for controlling volume that is used by this provider.
maxVolume: The maximum allowed volume.
currentVolume: The current volume.

public VolumeProviderCompat(int volumeControl, int maxVolume, int currentVolume, java.lang.String volumeControlId)

Create a new volume provider for handling volume events. You must specify the type of volume control and the maximum volume that can be used.

Parameters:

volumeControl: The method for controlling volume that is used by this provider.
maxVolume: The maximum allowed volume.
currentVolume: The current volume.
volumeControlId: The volume control ID of this provider.

Methods

public final int getCurrentVolume()

Get the current volume of the provider.

Returns:

The current volume.

public final int getVolumeControl()

Get the volume control type that this volume provider uses.

Returns:

The volume control type for this volume provider

public final int getMaxVolume()

Get the maximum volume this provider allows.

Returns:

The max allowed volume.

public final void setCurrentVolume(int currentVolume)

Set the current volume and notify the system that the volume has been changed.

Parameters:

currentVolume: The current volume of the output.

public final java.lang.String getVolumeControlId()

Gets the volume control ID. It can be used to identify which volume provider is used by the session.

Returns:

the volume control ID or null if it isn't set.

public void onSetVolumeTo(int volume)

Override to handle requests to set the volume of the current output.

Parameters:

volume: The volume to set the output to.

public void onAdjustVolume(int direction)

Override to handle requests to adjust the volume of the current output.

Parameters:

direction: The direction to adjust the volume in.

public void setCallback(VolumeProviderCompat.Callback callback)

Sets a callback to receive volume changes.

Used internally by the support library.

public java.lang.Object getVolumeProvider()

Gets the underlying framework object.

This method is only supported on API 21+.

Returns:

An equivalent object, or null if none.

Source

/*
 * Copyright 2024 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package androidx.media3.session.legacy;

import static androidx.annotation.RestrictTo.Scope.LIBRARY;

import android.media.VolumeProvider;
import android.os.Build;
import androidx.annotation.DoNotInline;
import androidx.annotation.IntDef;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;
import androidx.annotation.RestrictTo;
import androidx.media3.common.util.UnstableApi;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

/**
 * Handles requests to adjust or set the volume on a session. This is also used to push volume
 * updates back to the session after a request has been handled. You can set a volume provider on a
 * session by calling {@link MediaSessionCompat#setPlaybackToRemote}.
 */
@UnstableApi
@RestrictTo(LIBRARY)
public abstract class VolumeProviderCompat {

  /** */
  @IntDef({VOLUME_CONTROL_FIXED, VOLUME_CONTROL_RELATIVE, VOLUME_CONTROL_ABSOLUTE})
  @Retention(RetentionPolicy.SOURCE)
  public @interface ControlType {}

  /** The volume is fixed and can not be modified. Requests to change volume should be ignored. */
  public static final int VOLUME_CONTROL_FIXED = 0;

  /**
   * The volume control uses relative adjustment via {@link #onAdjustVolume(int)}. Attempts to set
   * the volume to a specific value should be ignored.
   */
  public static final int VOLUME_CONTROL_RELATIVE = 1;

  /**
   * The volume control uses an absolute value. It may be adjusted using {@link
   * #onAdjustVolume(int)} or set directly using {@link #onSetVolumeTo(int)}.
   */
  public static final int VOLUME_CONTROL_ABSOLUTE = 2;

  private final int mControlType;
  private final int mMaxVolume;
  @Nullable private final String mControlId;
  private int mCurrentVolume;
  @Nullable private Callback mCallback;

  @Nullable private VolumeProvider mVolumeProviderFwk;

  /**
   * Create a new volume provider for handling volume events. You must specify the type of volume
   * control and the maximum volume that can be used.
   *
   * @param volumeControl The method for controlling volume that is used by this provider.
   * @param maxVolume The maximum allowed volume.
   * @param currentVolume The current volume.
   */
  public VolumeProviderCompat(@ControlType int volumeControl, int maxVolume, int currentVolume) {
    this(volumeControl, maxVolume, currentVolume, null);
  }

  /**
   * Create a new volume provider for handling volume events. You must specify the type of volume
   * control and the maximum volume that can be used.
   *
   * @param volumeControl The method for controlling volume that is used by this provider.
   * @param maxVolume The maximum allowed volume.
   * @param currentVolume The current volume.
   * @param volumeControlId The volume control ID of this provider.
   */
  public VolumeProviderCompat(
      @ControlType int volumeControl,
      int maxVolume,
      int currentVolume,
      @Nullable String volumeControlId) {
    mControlType = volumeControl;
    mMaxVolume = maxVolume;
    mCurrentVolume = currentVolume;
    mControlId = volumeControlId;
  }

  /**
   * Get the current volume of the provider.
   *
   * @return The current volume.
   */
  public final int getCurrentVolume() {
    return mCurrentVolume;
  }

  /**
   * Get the volume control type that this volume provider uses.
   *
   * @return The volume control type for this volume provider
   */
  @ControlType
  public final int getVolumeControl() {
    return mControlType;
  }

  /**
   * Get the maximum volume this provider allows.
   *
   * @return The max allowed volume.
   */
  public final int getMaxVolume() {
    return mMaxVolume;
  }

  /**
   * Set the current volume and notify the system that the volume has been changed.
   *
   * @param currentVolume The current volume of the output.
   */
  public final void setCurrentVolume(int currentVolume) {
    mCurrentVolume = currentVolume;
    if (Build.VERSION.SDK_INT >= 21) {
      VolumeProvider volumeProviderFwk = (VolumeProvider) getVolumeProvider();
      Api21Impl.setCurrentVolume(volumeProviderFwk, currentVolume);
    }
    if (mCallback != null) {
      mCallback.onVolumeChanged(this);
    }
  }

  /**
   * Gets the volume control ID. It can be used to identify which volume provider is used by the
   * session.
   *
   * @return the volume control ID or {@code null} if it isn't set.
   */
  @Nullable
  public final String getVolumeControlId() {
    return mControlId;
  }

  /**
   * Override to handle requests to set the volume of the current output.
   *
   * @param volume The volume to set the output to.
   */
  public void onSetVolumeTo(int volume) {}

  /**
   * Override to handle requests to adjust the volume of the current output.
   *
   * @param direction The direction to adjust the volume in.
   */
  public void onAdjustVolume(int direction) {}

  /**
   * Sets a callback to receive volume changes.
   *
   * <p>Used internally by the support library.
   */
  public void setCallback(@Nullable Callback callback) {
    mCallback = callback;
  }

  /**
   * Gets the underlying framework {@link android.media.VolumeProvider} object.
   *
   * <p>This method is only supported on API 21+.
   *
   * @return An equivalent {@link android.media.VolumeProvider} object, or null if none.
   */
  @RequiresApi(21)
  public Object getVolumeProvider() {
    if (mVolumeProviderFwk == null) {
      if (Build.VERSION.SDK_INT >= 30) {
        mVolumeProviderFwk =
            new VolumeProvider(mControlType, mMaxVolume, mCurrentVolume, mControlId) {
              @Override
              public void onSetVolumeTo(int volume) {
                VolumeProviderCompat.this.onSetVolumeTo(volume);
              }

              @Override
              public void onAdjustVolume(int direction) {
                VolumeProviderCompat.this.onAdjustVolume(direction);
              }
            };
      } else {
        mVolumeProviderFwk =
            new VolumeProvider(mControlType, mMaxVolume, mCurrentVolume) {
              @Override
              public void onSetVolumeTo(int volume) {
                VolumeProviderCompat.this.onSetVolumeTo(volume);
              }

              @Override
              public void onAdjustVolume(int direction) {
                VolumeProviderCompat.this.onAdjustVolume(direction);
              }
            };
      }
    }
    return mVolumeProviderFwk;
  }

  /** Listens for changes to the volume. */
  public abstract static class Callback {
    public abstract void onVolumeChanged(VolumeProviderCompat volumeProvider);
  }

  @RequiresApi(21)
  private static class Api21Impl {
    private Api21Impl() {}

    @DoNotInline
    static void setCurrentVolume(VolumeProvider volumeProvider, int currentVolume) {
      volumeProvider.setCurrentVolume(currentVolume);
    }
  }
}