/*
 * 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.IntDef;
import android.annotation.NonNull;
import android.annotation.Nullable;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.List;
import java.util.concurrent.Executor;

@hide

Base class for all media players that want media session./**
 * @hide
 * Base class for all media players that want media session.
 */
public abstract class MediaPlayerBase implements AutoCloseable {
    
@hide
/**
     * @hide
     */
    @IntDef({
        PLAYER_STATE_IDLE,
        PLAYER_STATE_PAUSED,
        PLAYER_STATE_PLAYING,
        PLAYER_STATE_ERROR })
    @Retention(RetentionPolicy.SOURCE)
    public @interface PlayerState {}

    
@hide
/**
     * @hide
     */
    @IntDef({
        BUFFERING_STATE_UNKNOWN,
        BUFFERING_STATE_BUFFERING_AND_PLAYABLE,
        BUFFERING_STATE_BUFFERING_AND_STARVED,
        BUFFERING_STATE_BUFFERING_COMPLETE })
    @Retention(RetentionPolicy.SOURCE)
    public @interface BuffState {}

    
State when the player is idle, and needs configuration to start playback.
/**
     * State when the player is idle, and needs configuration to start playback.
     */
    public static final int PLAYER_STATE_IDLE = 0;

    
State when the player's playback is paused
/**
     * State when the player's playback is paused
     */
    public static final int PLAYER_STATE_PAUSED = 1;

    
State when the player's playback is ongoing
/**
     * State when the player's playback is ongoing
     */
    public static final int PLAYER_STATE_PLAYING = 2;

    
State when the player is in error state and cannot be recovered self.
/**
     * State when the player is in error state and cannot be recovered self.
     */
    public static final int PLAYER_STATE_ERROR = 3;

    
Buffering state is unknown.
/**
     * Buffering state is unknown.
     */
    public static final int BUFFERING_STATE_UNKNOWN = 0;

    
Buffering state indicating the player is buffering but enough has been buffered for this player to be able to play the content. See getBufferedPosition() for how far is buffered already. /**
     * Buffering state indicating the player is buffering but enough has been buffered
     * for this player to be able to play the content.
     * See {@link #getBufferedPosition()} for how far is buffered already.
     */
    public static final int BUFFERING_STATE_BUFFERING_AND_PLAYABLE = 1;

    
Buffering state indicating the player is buffering, but the player is currently starved
for data, and cannot play.
/**
     * Buffering state indicating the player is buffering, but the player is currently starved
     * for data, and cannot play.
     */
    public static final int BUFFERING_STATE_BUFFERING_AND_STARVED = 2;

    
Buffering state indicating the player is done buffering, and the remainder of the content is
available for playback.
/**
     * Buffering state indicating the player is done buffering, and the remainder of the content is
     * available for playback.
     */
    public static final int BUFFERING_STATE_BUFFERING_COMPLETE = 3;

    
Starts or resumes playback.
/**
     * Starts or resumes playback.
     */
    public abstract void play();

    
Prepares the player for playback. See PlayerEventCallback.onMediaPrepared(MediaPlayerBase, DataSourceDesc) for being notified when the preparation phase completed. During this time, the player may allocate resources required to play, such as audio and video decoders. /**
     * Prepares the player for playback.
     * See {@link PlayerEventCallback#onMediaPrepared(MediaPlayerBase, DataSourceDesc)} for being
     * notified when the preparation phase completed. During this time, the player may allocate
     * resources required to play, such as audio and video decoders.
     */
    public abstract void prepare();

    
Pauses playback.
/**
     * Pauses playback.
     */
    public abstract void pause();

    
Resets the MediaPlayerBase to its uninitialized state.
/**
     * Resets the MediaPlayerBase to its uninitialized state.
     */
    public abstract void reset();

    /**
     *
     */
    public abstract void skipToNext();

    
Moves the playback head to the specified position
Params:
pos – the new playback position expressed in ms./**
     * Moves the playback head to the specified position
     * @param pos the new playback position expressed in ms.
     */
    public abstract void seekTo(long pos);

    public static final long UNKNOWN_TIME = -1;

    
Gets the current playback head position.
Returns:
the current playback position in ms, or UNKNOWN_TIME if unknown./**
     * Gets the current playback head position.
     * @return the current playback position in ms, or {@link #UNKNOWN_TIME} if unknown.
     */
    public long getCurrentPosition() { return UNKNOWN_TIME; }

    
Returns the duration of the current data source, or UNKNOWN_TIME if unknown. 
Returns:
the duration in ms, or UNKNOWN_TIME./**
     * Returns the duration of the current data source, or {@link #UNKNOWN_TIME} if unknown.
     * @return the duration in ms, or {@link #UNKNOWN_TIME}.
     */
    public long getDuration() { return UNKNOWN_TIME; }

    
Gets the buffered position of current playback, or UNKNOWN_TIME if unknown. 
Returns:
the buffered position in ms, or UNKNOWN_TIME./**
     * Gets the buffered position of current playback, or {@link #UNKNOWN_TIME} if unknown.
     * @return the buffered position in ms, or {@link #UNKNOWN_TIME}.
     */
    public long getBufferedPosition() { return UNKNOWN_TIME; }

    
Returns the current player state. See also PlayerEventCallback.onPlayerStateChanged(MediaPlayerBase, int) for notification of changes. 
Returns:
the current player state/**
     * Returns the current player state.
     * See also {@link PlayerEventCallback#onPlayerStateChanged(MediaPlayerBase, int)} for
     * notification of changes.
     * @return the current player state
     */
    public abstract @PlayerState int getPlayerState();

    
Returns the current buffering state of the player. During buffering, see getBufferedPosition() for the quantifying the amount already buffered. 
Returns:
the buffering state./**
     * Returns the current buffering state of the player.
     * During buffering, see {@link #getBufferedPosition()} for the quantifying the amount already
     * buffered.
     * @return the buffering state.
     */
    public abstract @BuffState int getBufferingState();

    
Sets the AudioAttributes to be used during the playback of the media. 
Params:
attributes – non-null AudioAttributes./**
     * Sets the {@link AudioAttributes} to be used during the playback of the media.
     *
     * @param attributes non-null <code>AudioAttributes</code>.
     */
    public abstract void setAudioAttributes(@NonNull AudioAttributes attributes);

    
Returns AudioAttributes that media player has.
/**
     * Returns AudioAttributes that media player has.
     */
    public abstract @Nullable AudioAttributes getAudioAttributes();

    
Sets the data source to be played.
Params:
dsd – /**
     * Sets the data source to be played.
     * @param dsd
     */
    public abstract void setDataSource(@NonNull DataSourceDesc dsd);

    
Sets the data source that will be played immediately after the current one is done playing.
Params:
dsd – /**
     * Sets the data source that will be played immediately after the current one is done playing.
     * @param dsd
     */
    public abstract void setNextDataSource(@NonNull DataSourceDesc dsd);

    
Sets the list of data sources that will be sequentially played after the current one. Each
data source is played immediately after the previous one is done playing.
Params:
dsds – /**
     * Sets the list of data sources that will be sequentially played after the current one. Each
     * data source is played immediately after the previous one is done playing.
     * @param dsds
     */
    public abstract void setNextDataSources(@NonNull List<DataSourceDesc> dsds);

    
Returns the current data source.
Returns:
the current data source, or null if none is set, or none available to play./**
     * Returns the current data source.
     * @return the current data source, or null if none is set, or none available to play.
     */
    public abstract @Nullable DataSourceDesc getCurrentDataSource();

    
Configures the player to loop on the current data source.
Params:
loop – true if the current data source is meant to loop./**
     * Configures the player to loop on the current data source.
     * @param loop true if the current data source is meant to loop.
     */
    public abstract void loopCurrent(boolean loop);

    
Sets the playback speed. A value of 1.0f is the default playback value. A negative value indicates reverse playback, check isReversePlaybackSupported() before using negative values.
 After changing the playback speed, it is recommended to query the actual speed supported by the player, see getPlaybackSpeed(). 
Params:
speed – /**
     * Sets the playback speed.
     * A value of 1.0f is the default playback value.
     * A negative value indicates reverse playback, check {@link #isReversePlaybackSupported()}
     * before using negative values.<br>
     * After changing the playback speed, it is recommended to query the actual speed supported
     * by the player, see {@link #getPlaybackSpeed()}.
     * @param speed
     */
    public abstract void setPlaybackSpeed(float speed);

    
Returns the actual playback speed to be used by the player when playing. Note that it may differ from the speed set in setPlaybackSpeed(float). 
Returns:
the actual playback speed/**
     * Returns the actual playback speed to be used by the player when playing.
     * Note that it may differ from the speed set in {@link #setPlaybackSpeed(float)}.
     * @return the actual playback speed
     */
    public float getPlaybackSpeed() { return 1.0f; }

    
Indicates whether reverse playback is supported. Reverse playback is indicated by negative playback speeds, see setPlaybackSpeed(float). 
Returns:
true if reverse playback is supported./**
     * Indicates whether reverse playback is supported.
     * Reverse playback is indicated by negative playback speeds, see
     * {@link #setPlaybackSpeed(float)}.
     * @return true if reverse playback is supported.
     */
    public boolean isReversePlaybackSupported() { return false; }

    
Sets the volume of the audio of the media to play, expressed as a linear multiplier
on the audio samples.
Note that this volume is specific to the player, and is separate from stream volume
used across the platform.
 A value of 0.0f indicates muting, a value of 1.0f is the nominal unattenuated and unamplified gain. See getMaxPlayerVolume() for the volume range supported by this player. 
Params:
volume – a value between 0.0f and getMaxPlayerVolume()./**
     * Sets the volume of the audio of the media to play, expressed as a linear multiplier
     * on the audio samples.
     * Note that this volume is specific to the player, and is separate from stream volume
     * used across the platform.<br>
     * A value of 0.0f indicates muting, a value of 1.0f is the nominal unattenuated and unamplified
     * gain. See {@link #getMaxPlayerVolume()} for the volume range supported by this player.
     * @param volume a value between 0.0f and {@link #getMaxPlayerVolume()}.
     */
    public abstract void setPlayerVolume(float volume);

    
Returns the current volume of this player to this player.
Note that it does not take into account the associated stream volume.
Returns:
the player volume./**
     * Returns the current volume of this player to this player.
     * Note that it does not take into account the associated stream volume.
     * @return the player volume.
     */
    public abstract float getPlayerVolume();

    
Returns:
the maximum volume that can be used in setPlayerVolume(float)./**
     * @return the maximum volume that can be used in {@link #setPlayerVolume(float)}.
     */
    public float getMaxPlayerVolume() { return 1.0f; }

    
Adds a callback to be notified of events for this player.
Params:
e – the Executor to be used for the events.
cb – the callback to receive the events./**
     * Adds a callback to be notified of events for this player.
     * @param e the {@link Executor} to be used for the events.
     * @param cb the callback to receive the events.
     */
    public abstract void registerPlayerEventCallback(@NonNull Executor e,
            @NonNull PlayerEventCallback cb);

    
Removes a previously registered callback for player events
Params:
cb – the callback to remove/**
     * Removes a previously registered callback for player events
     * @param cb the callback to remove
     */
    public abstract void unregisterPlayerEventCallback(@NonNull PlayerEventCallback cb);

    
A callback class to receive notifications for events on the media player. See MediaPlayerBase.registerPlayerEventCallback(Executor, PlayerEventCallback) to register this callback. /**
     * A callback class to receive notifications for events on the media player.
     * See {@link MediaPlayerBase#registerPlayerEventCallback(Executor, PlayerEventCallback)} to
     * register this callback.
     */
    public static abstract class PlayerEventCallback {
        
Called when the player's current data source has changed.
Params:
mpb – the player whose data source changed.
dsd – the new current data source. null, if no more data sources available./**
         * Called when the player's current data source has changed.
         *
         * @param mpb the player whose data source changed.
         * @param dsd the new current data source. null, if no more data sources available.
         */
        public void onCurrentDataSourceChanged(@NonNull MediaPlayerBase mpb,
                @Nullable DataSourceDesc dsd) { }
        
Called when the player is prepared, i.e. it is ready to play the content
referenced by the given data source.
Params:
mpb – the player that is prepared.
dsd – the data source that the player is prepared to play./**
         * Called when the player is <i>prepared</i>, i.e. it is ready to play the content
         * referenced by the given data source.
         * @param mpb the player that is prepared.
         * @param dsd the data source that the player is prepared to play.
         */
        public void onMediaPrepared(@NonNull MediaPlayerBase mpb, @NonNull DataSourceDesc dsd) { }

        
Called to indicate that the state of the player has changed. See MediaPlayerBase.getPlayerState() for polling the player state. 
Params:
mpb – the player whose state has changed.
state – the new state of the player./**
         * Called to indicate that the state of the player has changed.
         * See {@link MediaPlayerBase#getPlayerState()} for polling the player state.
         * @param mpb the player whose state has changed.
         * @param state the new state of the player.
         */
        public void onPlayerStateChanged(@NonNull MediaPlayerBase mpb, @PlayerState int state) { }

        
Called to report buffering events for a data source.
Params:
mpb – the player that is buffering
dsd – the data source for which buffering is happening.
state – the new buffering state./**
         * Called to report buffering events for a data source.
         * @param mpb the player that is buffering
         * @param dsd the data source for which buffering is happening.
         * @param state the new buffering state.
         */
        public void onBufferingStateChanged(@NonNull MediaPlayerBase mpb,
                @NonNull DataSourceDesc dsd, @BuffState int state) { }

        
Called to indicate that the playback speed has changed.
Params:
mpb – the player that has changed the playback speed.
speed – the new playback speed./**
         * Called to indicate that the playback speed has changed.
         * @param mpb the player that has changed the playback speed.
         * @param speed the new playback speed.
         */
        public void onPlaybackSpeedChanged(@NonNull MediaPlayerBase mpb, float speed) { }

        
Called to indicate that MediaPlayerBase.seekTo(long) is completed. 
Params:
mpb – the player that has completed seeking.
position – the previous seeking request.
See Also:
MediaPlayerBase.seekTo(long)/**
         * Called to indicate that {@link #seekTo(long)} is completed.
         *
         * @param mpb the player that has completed seeking.
         * @param position the previous seeking request.
         * @see #seekTo(long)
         */
        public void onSeekCompleted(@NonNull MediaPlayerBase mpb, long position) { }
    }

}