API Direction Discussion

[johanneslumpe]

Currently we control the whole video using props. I think it might be useful to only control basic things like source, autoplay etc via props. For everything else we should start creating a proper api, which can then be triggered like this inside a component:

someMethod() {
  this.refs.video.someApiMethod();
}

I propose that we implement the following as api:

• play
• pause
• togglePlay(?)
• setRate
• setVolume
• setMuted / toggleMuted
• setRepeat
• setResizeMode
• seek (already implemented in the feature/seeking branch)

Thoughts on this?

[johanneslumpe]

Ok, so I've thought a bit more about this and came up with this:

<Media
  source={{uri: 'http://example.com/example.mp4'}}
  autoplay={false}
  onLoadStart={() => console.log('media started loading');}
  onProgress={() => console.log('media loaded more chunks');}
  onLoad={() => console.log('media fully loaded');}
  onEnded={() => console.log('media playback complete');}
  onSeek={() => console.log('media seek performed');}
  onUpdateTime={() => console.log('media currenttime changed');}#
  style={style.media}
  poster="pathtocoverimage"
  videoResizeMode="cover"
/>

Props

source
The media source, with uri or local path + file type

autoplay
Whether the video should automatically start to play

onLoadStart
Callback to be called when loading of an item starts

onProgress
Callback to be called when more chunks of an item are loaded

onLoad
Callback to be called when loading of an item has completed

onEnded
Callback to be called when an item has finishe playing

onSeek
Callback to be called when a seek has been performed

onUpdateTime
Callback to be called in short intervals, when the item plays to notify
about the playing progress

style
The style to apply to the player node

poster
An image to display when:

• We are playing a video and the playback is stopped
• We are playing an audio file (poster is always displayed)

videoResizeMode
The resizemode to use when a video is being played

Optional/alternative props

tracks / playlist
Used instead of source, takes an array of sources which can be played in sequence

onPlaylistEnded
Callback which is triggered when the last item in the playlist has been played

onPlaylistProgress
Callback to be called when a new item in the playlist is being played. Should at
least provide the index of the next item as payload. Could be used to
update a custom playlist component (highlighting the current song etc)

playbackOrder
When using a playlist, we might want to change the playback type. It would be
specified using constants, like MediaPlaybackTypeShuffle and MediaPlaybackTypeNormal.

When working with a playlist having the option to decide between reapeat and repeatAll
would be nice too.

JS API

play()
Start the playback of the video, doesn't do anything if it's already playing

pause()
Pauses the playback of the video, doesn't do anything if it's already paused

setPlaybackRate(rate)
Updates the playback rate

setVolume(volume)
Updates the volume

setMuted(isMuted)
Updates the muted stats

setRepeat(shouldRepeat)
Updates the repeat flag

seek(timeToSeekTo)
Tries to seek to the specified time

Optional convenience apis

togglePlay()
Starts the player when it's paused and pauses the player when it's playing

toggleMuted()
Mutes the player when it's unmuted and unmutes the player when it's muted

[brentvatne]

@johanneslumpe - I think this api would be fantastic. One thing that we might want to do instead of a poster (perhaps I'm getting ahead of myself here) is supply React component that is responsible for displaying some information about it, that way you could pass in an Image component if you want to do a poster, or something more advanced if you wanted to provide some kind of visualization or fetch the image from the web through some api and render it.

The main thing I'm not entirely sure about yet is how to deal with playlists - should it be the responsibility of the component to do this? If we reuse an AVPlayer instance, it would be trivial to wrap a media component to create a playlist, and would simplify the core api for this. If we support playlists, our number of props/methods will get about twice as big - we need to support skipping tracks, going back, callbacks for item specific things (onReachLastItem, onNewItemStart maybe, along those lines). I'm very tempted to defer support for multiple tracks until we have everything else nailed down. What do you think?

[johanneslumpe]

I totally agree about having the ability to pass a component as value for poster! In regard to the playlist: that was my exact though earlier. I wasn't sure whether we should have it all in one component or break it out into different pieces. I probably should have gone with the latter. So yeah, for now let's skip the playlist stuff!

[johanneslumpe]

So what's our next step? Do you want to merge the seeking code first? And we can work from there?

[brentvatne]

@johanneslumpe - I'm away until tomorrow evening for a weekend trip 😄 if you add the seeking code into the example app and it works as you expect, I'm okay with merging it in and then we can discuss next steps tomorrow evening or on Monday! Thanks for pushing me forward with this 👍

[johanneslumpe]

@brentvatne 23 days have passed by, we need to make this happen ;)

[brentvatne]

Agreed @johanneslumpe, I think we can get back into this now, let's try to get this out this week

[johanneslumpe]

whoo, https://github.com/brentvatne/react-native-video/tree/new-api a basic start. Totally untested though - wip ;)

[brentvatne]

@johanneslumpe - it just occurred to me, what behaviour would we expect if we are manually setting paused through a prop but then call pause() directly on the component? I'm concerned now that by adding two different ways to do things we can create confusion for API consumers

Should we somehow enforce that only one of the two APIs is used?

[johanneslumpe]

There won't be a paused prop anymore. My proposed list of props is this:

<Media
  source={{uri: 'http://example.com/example.mp4'}}
  autoplay={false}
  onLoadStart={() => console.log('media started loading');}
  onProgress={() => console.log('media loaded more chunks');}
  onLoad={() => console.log('media fully loaded');}
  onEnded={() => console.log('media playback complete');}
  onSeek={() => console.log('media seek performed');}
  onUpdateTime={() => console.log('media currenttime changed');}#
  style={style.media}
  poster="pathtocoverimage"
  videoResizeMode="cover"
/>

Controlling the video should be done purely through the api.

[brentvatne]

Ah ok, I saw that in the code still so I was confused 👍