# Interface AsyncMedia

All Superinterfaces:
  `Media`

All Known Implementing Classes:
  `AbstractMedia`

public interface AsyncMedia extends Media

An interface for media elements that provides asynchronous pause and play functionality as well as support for state change events, so that interested parties can register to be notified when state changes between play and pause.

You can convert any `Media` object into an AsyncMedia object using `MediaManager#getAsyncMedia(com.codename1.media.Media)`. In most cases this just casts the object to AsyncMedia, since most media returned from `MediaManager` already implement this interface. In cases where the media doesn't already implement AsyncMedia, it will return an Async wrapper around the media.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `AsyncMedia.MediaErrorEvent`
  Encapsulates a media error event.
  `static enum`
  `AsyncMedia.MediaErrorType`
  Enum encapsulating the different types of media errors that can occur.
  `static class`
  `AsyncMedia.MediaException`
  Encapsulates a media exception.
  `static class`
  `AsyncMedia.MediaStateChangeEvent`
  Encapsulates a state-change event on a Media object.
  `static class`
  `AsyncMedia.PauseRequest`
  An async resource used to track the progress of a pauseAsync() request.
  `static class`
  `AsyncMedia.PlayRequest`
  An async resource used to track the progress of a playAsync() request.
  `static enum`
  `AsyncMedia.State`
  An enum to represent the state of a media object.

- ## Field Summary

  ### Fields inherited from interface Media

  `VARIABLE_ANDROID_SEEK_PREVIEW_WORKAROUND, VARIABLE_BACKGROUND_ALBUM_COVER, VARIABLE_BACKGROUND_ARTIST, VARIABLE_BACKGROUND_DURATION, VARIABLE_BACKGROUND_POSITION, VARIABLE_BACKGROUND_SUPPORTED, VARIABLE_BACKGROUND_TITLE, VARIABLE_NATIVE_CONTRLOLS_EMBEDDED`
  Modifier and Type
  Field
  Description
  `static final String`
  `VARIABLE_ANDROID_SEEK_PREVIEW_WORKAROUND`
  Optional boolean flag to enable an Android-specific workaround for flaky black-frame previews after `Media.setTime(int)` on paused video.
  `static final String`
  `VARIABLE_BACKGROUND_ALBUM_COVER`
  Write only variable that can be used with setVariable to pass the album cover Image to the native layer so the currently playing media title will be displayed in the lock screen where applicable
  `static final String`
  `VARIABLE_BACKGROUND_ARTIST`
  Write only variable that can be used with setVariable to pass the artist name to the native layer so the currently playing media title will be displayed in the lock screen where applicable
  `static final String`
  `VARIABLE_BACKGROUND_DURATION`
  Write only variable that can be used with setVariable to pass the duration for the media as a Long object to the native layer so the currently playing media title will be displayed in the lock screen where applicable
  `static final String`
  `VARIABLE_BACKGROUND_POSITION`
  Write only variable that can be used with setVariable to pass the position in the media (Long object) to the native layer so the currently playing media title will be displayed in the lock screen where applicable
  `static final String`
  `VARIABLE_BACKGROUND_SUPPORTED`
  Read only variable that can be used with getVariable to query whether the native layer supports displaying the currently playing media information in the lock screen.
  `static final String`
  `VARIABLE_BACKGROUND_TITLE`
  Write only variable that can be used with setVariable to pass a title for the native layer so the currently playing media title will be displayed in the lock screen where applicable
  `static final String`
  `VARIABLE_NATIVE_CONTRLOLS_EMBEDDED`
  Write-only variable that can be used with getVariable() to set whether this video should include embedded native controls.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addMediaCompletionHandler(Runnable onComplete)`
  Adds a callback to be run when the media has played to completion.
  `void`
  `addMediaErrorListener(ActionListener<AsyncMedia.MediaErrorEvent> l)`
  Adds a listener to be notified when an error occurs in the media.
  `void`
  `addMediaStateChangeListener(ActionListener<AsyncMedia.MediaStateChangeEvent> l)`
  Adds a listener to be notified when the state of the media changes.
  `AsyncMedia.State`
  `getState()`
  Gets the current state of the media object.
  `AsyncMedia.PauseRequest`
  `pauseAsync()`
  Initiates a pause request.
  `AsyncMedia.PlayRequest`
  `playAsync()`
  Initiates a play request.
  `void`
  `removeMediaErrorListener(ActionListener<AsyncMedia.MediaErrorEvent> l)`
  Removes a listener so that it will no longer be notified of errors.
  `void`
  `removeMediaStateChangeListener(ActionListener<AsyncMedia.MediaStateChangeEvent> l)`
  Removes a listener so that it will no longer be notified of state changes.

  ### Methods inherited from interface Media

  `cleanup, getDuration, getTime, getVariable, getVideoComponent, getVolume, isFullScreen, isNativePlayerMode, isPlaying, isVideo, pause, play, prepare, setFullScreen, setNativePlayerMode, setTime, setVariable, setVolume`
  Modifier and Type
  Method
  Description
  `void`
  `cleanup()`
  Stops the audio playback and cleans up the resources related to it immediately.
  `int`
  `getDuration()`
  Returns the length in milliseconds of the audio file or -1 if not known
  `int`
  `getTime()`
  Returns the time in milliseconds in the audio file or -1 if not known
  `Object`
  `getVariable(String key)`
  Allows querying platform specific information from the media object
  `Component`
  `getVideoComponent()`
  Gets the VideoComponent of this Video.
  `int`
  `getVolume()`
  Returns the media playback volume in percentage
  `boolean`
  `isFullScreen()`
  This method returns true if this video is in full screen mode.
  `boolean`
  `isNativePlayerMode()`
  Returns true if this Video Media is in Native player mode.
  `boolean`
  `isPlaying()`
  Returns true if the media is currently playing or recording
  `boolean`
  `isVideo()`
  This method returns true if this is a Video Media
  `void`
  `pause()`
  Pauses (actually stops) the playback or the recording of the media file
  `void`
  `play()`
  Starts playing or recording the media file
  `void`
  `prepare()`
  Optional call that allows the caller to prepare the upcoming media player.
  `void`
  `setFullScreen(boolean fullScreen)`
  Sets the Media to be displayed full screen, make sure the getVideoComponent() is called on the Video Component is added to the current Form
  `void`
  `setNativePlayerMode(boolean nativePlayer)`
  By calling this the Media (if it's a Video) will be played full screen on the native Player of the device.
  `void`
  `setTime(int time)`
  Sets the position in the audio file or doesn't effect if not supported
  `void`
  `setVariable(String key, Object value)`
  Allows for platform specific enhancements for media playback
  `void`
  `setVolume(int vol)`
  Sets the media playback volume in percentage

- ## Method Details

  - ### getState

    AsyncMedia.State getState()

    Gets the current state of the media object.

    ###### Returns

    The state of the media object.

  - ### addMediaStateChangeListener

    void addMediaStateChangeListener(ActionListener<AsyncMedia.MediaStateChangeEvent> l)

    Adds a listener to be notified when the state of the media changes.

    ###### Parameters

    - `l`: Listener

  - ### removeMediaStateChangeListener

    void removeMediaStateChangeListener(ActionListener<AsyncMedia.MediaStateChangeEvent> l)

    Removes a listener so that it will no longer be notified of state changes.

    ###### Parameters

    - `l`: Listener

  - ### addMediaErrorListener

    void addMediaErrorListener(ActionListener<AsyncMedia.MediaErrorEvent> l)

    Adds a listener to be notified when an error occurs in the media.

    ###### Parameters

    - `l`: Listener

  - ### removeMediaErrorListener

    void removeMediaErrorListener(ActionListener<AsyncMedia.MediaErrorEvent> l)

    Removes a listener so that it will no longer be notified of errors.

    ###### Parameters

    - `l`: Listener

  - ### addMediaCompletionHandler

    void addMediaCompletionHandler(Runnable onComplete)

    Adds a callback to be run when the media has played to completion.

    ###### Parameters

    - `onComplete`

  - ### playAsync

    AsyncMedia.PlayRequest playAsync()
    Initiates a play request. Returns immediately without blocking. Caller can use the returned PlayRequest object to be notified when playing has actually started.

  - ### pauseAsync

    AsyncMedia.PauseRequest pauseAsync()
    Initiates a pause request. Returns immediately without blocking. Caller can use the returned PauseRequest object to be notified when media has actually paused.