# Package com.brightcove.player.mediacontroller

Application developer level documentation for the Brightcove Android media controller.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  BrightcoveMediaControlRegistry | Defines the interface for managing a collection of controllers for media control buttons which use an icon fontset to present the button operation via a glyph defined by the font.
  MediaControllerKeyDispatcher | The key dispatcher interface for the Media Controller.
  PreviewLoader | The component responsible for loading `TimedThumbnail` from a given `ThumbnailDocument` and the playhead position, into the `ThumbnailView`.
  PreviewThumbnailFormatSelector | Selects a `PreviewThumbnailFormat` from a given list.
  PreviewThumbnailView | The representation for the Preview Thumbnail View which contains all the components needed for drawing thumbnail images according to the progress changes.
  PreviewThumbnailView.OnPreviewChangeListener | This `PreviewThumbnailView`'s listener
  ShowHideController | Defines the facilities for managing media controls visibility.
  ThumbnailDocument | The document containing an ordered list of `TimedThumbnail` for a particular `Video`
  ThumbnailDocumentCreator | Interface use to create an implementation of `ThumbnailDocument` given a list of `TimedThumbnail`
  TimedThumbnailFilter | The `TimedThumbnail` available for a video may be dependent on the duration of such a video, going from dozens to hundreds of images.

- Class Summary
  Class | Description
  --- | ---
  BrightcoveControlBar | Provides a control bar wrapper class.
  BrightcoveMediaController | The default Brightcove media controller patterned on the Brightcove Web Player.
  BrightcoveMediaControlRegistryImpl | Provides a button controller registry where collections of button controllers are managed.
  BrightcovePreviewSeekBar | The default `PreviewThumbnailView` in the Thumbnail plugin.
  BrightcoveSeekBar | Provides a seek bar object that also manages arbitrary markers for chapters, ads or some other purpose.
  BrightcoveSeekBarController | Abstracts the seekbar operations and provides a helper class for the seekbar in general.
  BrightcoveShowHideController | Abstracts the show/hide operations.
  DefaultPreviewLoader | The default `PreviewLoader` used in the Thumbnail plugin.
  DefaultPreviewLoader.Builder | The `DefaultPreviewLoader` Builder.
  DefaultThumbnailDocument | The default `ThumbnailDocument` used in the Thumbnail plugin.
  DefaultThumbnailDocument.StartTimeComparator | A `Comparator` used to sort `TimedThumbnail`s based on their start time
  DefaultThumbnailDocumentCreator | Creates a `DefaultThumbnailDocument` with a default `DefaultTimedThumbnailFilter`
  DefaultTimedThumbnailFilter | Filters a given `ThumbnailDocument` alowing a maximum number of `DefaultTimedThumbnailFilter.MAX_NUMBER_OF_TIMED_THUMBNAILS` `TimedThumbnail`.
  MediaControllerConfig | A configuration class that can be used to configure `BrightcoveMediaController`.
  MediaControllerConfig.Builder | The MediaControllerConfig Builder.
  ScreenSizeThumbnailFormatSelector | Selects the thumbnail format based on the screen size of the device.
  ThumbnailComponent | Thumbnail Component Plugin.
  ThumbnailEvent | An event class containing the `Event` property keys exclusively used in the Thumbnail plugin.
  ThumbnailEventType | Identifies SSAI event types used and emitted within the Thumbnail plugin.
  ThumbnailView | The View used by the `PreviewLoader` to draw the preview thumbnail image.
  TimedThumbnail |

## Package com.brightcove.player.mediacontroller Description

Application developer level documentation for the Brightcove Android media controller. The following describes how an application developer might use the Brightcove media controller to customize the media controls on an app using these media controls. Sample snippets are provided on GitHub Gists with links provided below.

# Modifying media controller colors.

App developers can override the default colors used in the Brightcove media controller by providing different colors values in their own colors resource file `.../res/values/colors.xml`. The color names and their default values are:

Color Name | Color Value | Description
--- | --- | ---
`bmc_seekbar_played` | #d52484 | The primary progress color. Indicates how much of the video has played.
`bmc_seekbar_buffered` | white_semi_trans | The secondary progress color. Indicates how much of the video has been buffered.
`bmc_seekbar_track` | white_semi_trans | The seekbar background color. Indicates how much of the video remains to be buffered and played.
`bmc_seekbar_thumb_center` | white | The seekbar thumb button view center color.
`bmc_seekbar_thumb_outside` | white_semi_trans | The seekbar thumb view outer color.
`bmc_seekbar_marker` | white_semi_trans | The seekbar marker color.
`bmc_button` | white_almost_opaque | The default media button foreground color.
`bmc_time_text` | white_almost_opaque | The default time text view foreground color.
`bmc_background` | black_semi_trans | The media controller background color.

This GitHub Gist shows a `colors.xml` file that modifies the sekbar progress colors to transparent magenta/black/blue.

# Changing a button face and hiding a button.

App developers can change the face of a media control button quite easily. The Brightcove media controller uses the Font Awesome toolkit. The rewind operation is a very good example of a button with many acceptable choices. There is the default text undo face (fa-undo), the video player backward (fa-backward) and step-backward (fa-step-backward) faces, as well as the directional arrow-left (fa-arrow-left) face. This Github Gist shows how to apply these three choices. The table below identifies the default button names. The buttons are standard Android Button widgets. To hide a button, an app developer can programmatically use the Button API to accomplish this as shown in this GitHub Gist.

Button Name/ID | Default Icon | Description
--- | --- | ---
`play` | fa-play | The play button. The button shows this face when the video is paused or stopped.
`pause` | fa-pause | The alternate face presented when the video is playing.
`rewind` | fa-undo | The rewind button. When clicked, causes the video to replay the last few seconds of the video. Defaults to three seconds.
`captions` | fa-cc | The captions button. Brings up a dialog for the User to select a closed captions option.
`enter_full_screen` | fa-expand | The enter full screen button. Causes the video to play using the entire screen.
`exit_full_screen` | fa-compress | The exit full screen button. Causes the video to return to it's default size.

# Customizing showing and hiding the control bar.

Applications can show the media controls by either emitting an SDK SHOW_MEDIA_CONTROLS event or calling the show() method from a class implementing the ShowHideController interface, such as the BrightcoveMediaController. Similarly to hide the media controls, applications can emit the SDK HIDE_MEDIA_CONTROLS event or call the hide() method. In either case, a payload can be used to specify either the timeout (an Integer property named SHOW_HIDE_TIMEOUT, a number of milliseconds) or the style (an integer property named SHOW_HIDE_ANIMATION_STYLE with values ANIMATION_STYLE_FADE or ANIMATION_STYLE_HIDE) to be used when showing or hiding the media controls. The new values take effect immediately. Also, either an animation style or a timeout value can be specified as attributes in the layout file using the Brightcove attributes bmc:animation_style (specifying one of "fade" or "slide") or bmc:timeout. The timeout value is an integer number of milliseconds specifying the amount of delay after showing the media controls until they are automatically hidden. A value of 0 will result in the media contrtrols being permanently visible. A number of gists have been provided on GitHub to illustrate how to customize the media controls show/hide operations. This Gist illustrates how to customize the application to always have the media controls displayed after setting a video. This Gist shows how to easily change the show/hide animation style to "slide". This Gist shows how to easily change the media controls show/hide timeout value to five seconds.