Toro

General

Category
Free
Tag
Video
License
N/A
Min SDK
16 (Android 4.1 Jelly Bean)
Registered
Feb 6, 2016
Favorites
13
Link
https://github.com/eneim/Toro
See also
mp4parser
Fenster
FFmpegCmdSdk
VideoChatHeads
Youtube-Android-Player-Helper

Additional

Language
Java
Version
3.6.2.2903 (Jan 18, 2019)
Created
Jan 31, 2016
Updated
Jan 18, 2019
Owner
Nam Nguyen Hoai (eneim)
Contributors
Nam Nguyen Hoai (eneim)
thiagoricieri
fossabot
3
Activity
Badge
Generate
Download
Source code
APK file

Show card

Toro

Video list auto playback made simple, specially built for RecyclerView

Releases

Please grab latest demo APK and see release note here

Menu

Features

Core:

  • 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 = '3.6.2.2804' // 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 {
    google()
    jcenter()
    // Add url below to use snaphot
    maven { url 'https://oss.jfrog.org/artifactory/oss-snapshot-local' }
  }
  
  // TODO anything else
}

Application's build.gradle

ext {
  latest_snapshot = '3.7.0.2901-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.

<im.ene.toro.widget.Container
  android:id="@+id/my_fancy_videos"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
/>

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(R.id.player) PlayerView playerView;

  SimpleExoPlayerViewHolder(View itemView) {
    super(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();
  }

  @Override
  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.release();
      helper = null;
    }
  }

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

  @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.



Behaviour:

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

<CoordinatorLayout>
  <AppBarLayout app:layout_behavior:AppBarLayout.Behavior.class>
    <CollapsingToolbarLayout>
    </CollapsingToolbarLayout>
  </AppBarLayout>
  <Container app:layout_behavior:ScrollingViewBehavior.class>
  </Container>
</CoordinatorLayout>

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() {
            container.onScrollStateChanged(RecyclerView.SCROLL_STATE_IDLE);
          }
        }));
  }
}

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

Before After

Contribution

  • 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.

Support

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

Hall of Fame

Email to nam@ene.im with the description of your App using Toro to list it here.

License

Copyright 2017 eneim@Eneim Labs, nam@ene.im

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.