/* * Copyright 2018 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 android.media; import android.annotation.CallbackExecutor; import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; import android.media.update.ApiLoader; import android.media.update.MediaPlaylistAgentProvider; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.util.List; import java.util.concurrent.Executor; /** * @hide * MediaPlaylistAgent is the abstract class an application needs to derive from to pass an object * to a MediaSession2 that will override default playlist handling behaviors. It contains a set of * notify methods to signal MediaSession2 that playlist-related state has changed. *
* Playlists are composed of one or multiple {@link MediaItem2} instances, which combine metadata
* and data sources (as {@link DataSourceDesc})
* Used by {@link MediaSession2} and {@link MediaController2}.
*/
// This class only includes methods that contain {@link MediaItem2}.
public abstract class MediaPlaylistAgent {
/**
* @hide
*/
@IntDef({REPEAT_MODE_NONE, REPEAT_MODE_ONE, REPEAT_MODE_ALL,
REPEAT_MODE_GROUP})
@Retention(RetentionPolicy.SOURCE)
public @interface RepeatMode {}
/**
* Playback will be stopped at the end of the playing media list.
*/
public static final int REPEAT_MODE_NONE = 0;
/**
* Playback of the current playing media item will be repeated.
*/
public static final int REPEAT_MODE_ONE = 1;
/**
* Playing media list will be repeated.
*/
public static final int REPEAT_MODE_ALL = 2;
/**
* Playback of the playing media group will be repeated.
* A group is a logical block of media items which is specified in the section 5.7 of the
* Bluetooth AVRCP 1.6. An example of a group is the playlist.
*/
public static final int REPEAT_MODE_GROUP = 3;
/**
* @hide
*/
@IntDef({SHUFFLE_MODE_NONE, SHUFFLE_MODE_ALL, SHUFFLE_MODE_GROUP})
@Retention(RetentionPolicy.SOURCE)
public @interface ShuffleMode {}
/**
* Media list will be played in order.
*/
public static final int SHUFFLE_MODE_NONE = 0;
/**
* Media list will be played in shuffled order.
*/
public static final int SHUFFLE_MODE_ALL = 1;
/**
* Media group will be played in shuffled order.
* A group is a logical block of media items which is specified in the section 5.7 of the
* Bluetooth AVRCP 1.6. An example of a group is the playlist.
*/
public static final int SHUFFLE_MODE_GROUP = 2;
private final MediaPlaylistAgentProvider mProvider;
/**
* A callback class to receive notifications for events on the media player. See
* {@link MediaPlaylistAgent#registerPlaylistEventCallback(Executor, PlaylistEventCallback)}
* to register this callback.
*/
public static abstract class PlaylistEventCallback {
/**
* Called when a playlist is changed.
*
* @param playlistAgent playlist agent for this event
* @param list new playlist
* @param metadata new metadata
*/
public void onPlaylistChanged(@NonNull MediaPlaylistAgent playlistAgent,
@NonNull List
* This will not change the currently playing media item.
* If index is less than or equal to the current index of the playlist,
* the current index of the playlist will be incremented correspondingly.
*
* @param index the index you want to add
* @param item the media item you want to add
*/
public void addPlaylistItem(int index, @NonNull MediaItem2 item) {
mProvider.addPlaylistItem_impl(index, item);
}
/**
* Removes the media item from the playlist
*
* @param item media item to remove
*/
public void removePlaylistItem(@NonNull MediaItem2 item) {
mProvider.removePlaylistItem_impl(item);
}
/**
* Replace the media item at index in the playlist. This can be also used to update metadata of
* an item.
*
* @param index the index of the item to replace
* @param item the new item
*/
public void replacePlaylistItem(int index, @NonNull MediaItem2 item) {
mProvider.replacePlaylistItem_impl(index, item);
}
/**
* Skips to the the media item, and plays from it.
*
* @param item media item to start playing from
*/
public void skipToPlaylistItem(@NonNull MediaItem2 item) {
mProvider.skipToPlaylistItem_impl(item);
}
/**
* Skips to the previous item in the playlist.
*/
public void skipToPreviousItem() {
mProvider.skipToPreviousItem_impl();
}
/**
* Skips to the next item in the playlist.
*/
public void skipToNextItem() {
mProvider.skipToNextItem_impl();
}
/**
* Gets the repeat mode
*
* @return repeat mode
* @see #REPEAT_MODE_NONE
* @see #REPEAT_MODE_ONE
* @see #REPEAT_MODE_ALL
* @see #REPEAT_MODE_GROUP
*/
public @RepeatMode int getRepeatMode() {
return mProvider.getRepeatMode_impl();
}
/**
* Sets the repeat mode
*
* @param repeatMode repeat mode
* @see #REPEAT_MODE_NONE
* @see #REPEAT_MODE_ONE
* @see #REPEAT_MODE_ALL
* @see #REPEAT_MODE_GROUP
*/
public void setRepeatMode(@RepeatMode int repeatMode) {
mProvider.setRepeatMode_impl(repeatMode);
}
/**
* Gets the shuffle mode
*
* @return The shuffle mode
* @see #SHUFFLE_MODE_NONE
* @see #SHUFFLE_MODE_ALL
* @see #SHUFFLE_MODE_GROUP
*/
public @ShuffleMode int getShuffleMode() {
return mProvider.getShuffleMode_impl();
}
/**
* Sets the shuffle mode
*
* @param shuffleMode The shuffle mode
* @see #SHUFFLE_MODE_NONE
* @see #SHUFFLE_MODE_ALL
* @see #SHUFFLE_MODE_GROUP
*/
public void setShuffleMode(@ShuffleMode int shuffleMode) {
mProvider.setShuffleMode_impl(shuffleMode);
}
/**
* Called by {@link MediaSession2} when it wants to translate {@link DataSourceDesc} from the
* {@link MediaPlayerBase.PlayerEventCallback} to the {@link MediaItem2}. Override this method
* if you want to create {@link DataSourceDesc}s dynamically, instead of specifying them with
* {@link #setPlaylist(List, MediaMetadata2)}.
*
* Session would throw an exception if this returns {@code null} for {@param dsd} from the
* {@link MediaPlayerBase.PlayerEventCallback}.
*
* Default implementation calls the {@link #getPlaylist()} and searches the {@link MediaItem2}
* with the {@param dsd}.
*
* @param dsd The dsd to query.
* @return A {@link MediaItem2} object in the playlist that matches given {@code dsd}.
* @throws IllegalArgumentException if {@code dsd} is null
*/
public @Nullable MediaItem2 getMediaItem(@NonNull DataSourceDesc dsd) {
return mProvider.getMediaItem_impl(dsd);
}
}