Version (Feb 15, 2020)
Jan 31, 2016
Feb 19, 2020
Nam Nguyen Hoai (eneim)
Nam Nguyen Hoai (eneim)
Arka Prava Basu (archie94)
Source code
APK file



Video list auto playback made simple, specially built for RecyclerView


Please grab latest demo APK and see release note here




  • Auto start/pause Media playback on user interaction: scroll, open/close App.
  • Optional playback position save/restore (default: disabled).
    • If enabled, Toro will also save/restore them on Configuration change (orientation change, multi-window mode ...).
  • Customizable playback component: either MediaPlayer or ExoPlayer will work. Toro comes with default helper classes to support these 2.
  • Customizable player selector: custom the selection of the player to start, among many other players.
    • Which in turn support single/multiple players.
  • Powerful default implementations, enough for various use cases.

Plus alpha:

  • First class support for ExoPlayer 2.

Demo (Youtube Video)

Getting start, basic implementation

1. Update module build.gradle.

Latest version:

ext {
  latest_release = '' // TODO check above for latest version

dependencies {
  implementation "im.ene.toro3:toro:${latest_release}"
  implementation "im.ene.toro3:toro-ext-exoplayer:${latest_release}"  // to get ExoPlayer support

Using snapshot:

Update this to root's build.gradle

allprojects {
  repositories {
    // Add url below to use snaphot
    maven { url '' }
  // TODO anything else

Application's build.gradle

ext {
  latest_snapshot = '' // TODO check above for latest version
  // below: other dependencies' versions maybe

dependencies {
  implementation "im.ene.toro3:toro:${latest_snapshot}"
  implementation "im.ene.toro3:toro-ext-exoplayer:${latest_snapshot}"  // to get ExoPlayer support

2. Using Container in place of Video list/RecyclerView.


3. Implement ToroPlayer to ViewHolder that should be a Video player.

Sample ToroPlayer implementation (click to expand)

public class SimpleExoPlayerViewHolder extends RecyclerView.ViewHolder implements ToroPlayer {

  static final int LAYOUT_RES = R.layout.vh_exoplayer_basic;

  @Nullable ExoPlayerViewHelper helper;
  @Nullable private Uri mediaUri;

  @BindView( PlayerView playerView;

  SimpleExoPlayerViewHolder(View itemView) {
    ButterKnife.bind(this, itemView);

  // called from Adapter to setup the media
  void bind(@NonNull RecyclerView.Adapter adapter, Uri item, List<Object> payloads) {
    if (item != null) {
      mediaUri = item;

  @NonNull @Override public View getPlayerView() {
    return playerView;

  @NonNull @Override public PlaybackInfo getCurrentPlaybackInfo() {
    return helper != null ? helper.getLatestPlaybackInfo() : new PlaybackInfo();

  public void initialize(@NonNull Container container, @Nullable PlaybackInfo playbackInfo) {
    if (helper == null) {
      helper = new ExoPlayerViewHelper(this, mediaUri);
    helper.initialize(container, playbackInfo);

  @Override public void release() {
    if (helper != null) {
      helper = null;

  @Override public void play() {
    if (helper != null);

  @Override public void pause() {
    if (helper != null) helper.pause();

  @Override public boolean isPlaying() {
    return helper != null && helper.isPlaying();

  @Override public boolean wantsToPlay() {
    return ToroUtil.visibleAreaOffset(this, itemView.getParent()) >= 0.85;

  @Override public int getPlayerOrder() {
    return getAdapterPosition();

More advanced View holder implementations can be found in

app, demo-xxx module.


3. Enable/Disable the auto-play on demand

To disable the auto play, simply use the PlayerSelector.NONE for the Container. To enable it again, just use a Selector that actually select the player. There is PlayerSelector.DEFAULT built-in.

4. Start playback with delay

It is expected that: when user scrolls so that the Player view is in playable state (maybe because it is fully visual), there should be a small delay before the Player starts playing. Toro supports this out of the box using PlayerDispatcher and via Container#setPlayerDispatcher(). Further more, the delay ca be flexibly configured by per-Player. The snippet below shows how to use PlayerDispatcher:

// ToroPlayer whose order is divisible by 3 will be delayed by 250 ms, others will be delayed by 1000 ms (1 second). 
container.setPlayerDispatcher(player -> player.getPlayerOrder() % 3 == 0 ? 250 : 1000);

5. Works with CoordinatorLayout

When using a Container in the following View hierarchy

  <AppBarLayout app:layout_behavior:AppBarLayout.Behavior.class>
  <Container app:layout_behavior:ScrollingViewBehavior.class>

In the layout above, when User 'scroll' the UI by flinging the CollapsingToolbarLayout (not the Container), neither CoordinatorLayout will not tell Container about the 'scroll', nor Container will trigger a call to Container#onScrollStateChanged(int). But in practice, an interaction like this will make the Player be visible, and User expects a playback to starts, which may not without some update in your codebase.

To support this use case, Toro adds a delegation Container.Behavior that can be used manually to catch the behavior like above.

The usage looks like below:

// Add following snippet in Activity#onCreate or Fragment#onViewCreated
// Only when you use Container inside a CoordinatorLayout and depends on Behavior.
// 1. Request Container's LayoutParams
ViewGroup.LayoutParams params = container.getLayoutParams();
// 2. Only continue if it is of type CoordinatorLayout.LayoutParams
if (params != null && params instanceof CoordinatorLayout.LayoutParams) {
  // 3. Check if there is an already set CoordinatorLayout.Behavior. If not, just ignore everything. 
  CoordinatorLayout.Behavior behavior = ((CoordinatorLayout.LayoutParams) params).getBehavior();
  if (behavior != null) {
    ((LayoutParams) params).setBehavior(new Container.Behavior(behavior,
        // 4. Container.Behavior requires a Container.BehaviorCallback to ask client what to do next. 
        new Container.BehaviorCallback() {
          @Override public void onFinishInteraction() {

Below is the behavior before and after we apply the code above:

Before After


  • For development:

    • Fork the repo, clone it to your machine and execute ./gradlew clean build to start.
    • Latest Toro repository is developed using Android Studio 3.3.
  • Issue report and Pull Requests are welcome. Please follow issue format for quick response.

  • For Pull Requests, this project uses 2-space indent and no Hungarian naming convention.


  • You can support the development of this library by buying me a cup of coffee (link below).

Hall of Fame

Email to with the description of your App using Toro to list it here.


Copyright 2017 eneim@Eneim Labs,

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

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.