Thoughts for a v4.0.0 #881
Comments
peaBerberian
added
API
|
Hey. Do you have any ETA for v4 release? I see a lot of movement on linked branch recently, but no announcement yet. Additionally, what is your plan for maintaining v3? |
|
Hi @tykus160, The first beta version is very imminent, we could have released it today but we saw some missed opportunity which has postponed it at either tomorrow or next week. We plan to stay as a beta for many months, giving time to applications to make remarks and suggestions. In the meantime, we'll continue to update the v3 as usual. A The v3 should still be maintained for a long time though I have no real timeline to give you here. It will depend on if it appears to be still used (we know even of an application at Canal+ which may not have the resources to make the v4 switch for the foreseeable future, so even only for them we may need to continue making some evolution to it), on issues open relative to the v3, and so on. In any case, the v3 stays the main version as long as we're still in a v4 beta phase and even after, we don't want to alienate our user base so we'll still maintain it, though of course we prefer if applications made the switch when the first stable v4.0,0 is released. |
|
The first v4 beta release has now been done: Don't hesitate to open issues if you have remarks or questions about it |
This is an issue to discuss about what we could do in a v4.0.0 and how to do it.
Why?
A new major version will let us "break" the API in its current state, this can allow much larger modifications than regular releases.
The main downside being that an API overhaul might be a chore to developers wanting to do the switch.
That's the reason why we refrained from doing that since the end of 2017, which is a relatively long period.
So this is mainly to help us maintain and make evolution to the code. A user might expect shiny new features from a new major version in return for the hassle but I think that even in the case where we find nothing really attractive to provide here, we should still go on with a v4.
Objectives of a v4
To me, the main objectives of a v4.0.0 for now would be:
Allow us to make much bigger changes to the RxPlayer's code.
I'm thinking about methods that handicap us like
getManifest,getCurrentAdaptationsandgetCurrentRepresentationsas they reveal too much the player's internal data (which forces us to do ugly things like manifest: a segment's timescale is now always set to1#860).Allow us to provide a sane behavior by default.
By default, the RxPlayer stops automatically (and unloads the content) when it reaches the
ENDEDstate.To disable that strange behavior, we added the
stopAtEndplayer option, which is set totrueby default to maintain API compatibility. Here setting it tofalseby default, or even just removing it (the application can replicates the same behavior through simple events) might be less surprising to someone using the API.I'm also thinking about the fact that we avoid switching to the
RELOADINGstate unless if an option explicitly documenting that new state was enabled.With a new major version, we could add that state to the "regular" received states (which breaks both
playerStateChangeandgetPlayerState). This could allow to avoid decoding errors and infinite stalling issues without the need to rely on an option.Simplify the API.
There's a lot of deprecated methods, events and options we could either do without (e.g.
hideNativeSubtitlesloadVideooption) or even some we do not want developers to use at all (likesetFullScreen, because it does not take into account HTML subtitles into full-screen). This would have the double advantage of removing a lot of code and of making the API more digestible.Also I find like some DASH-inspired terms like "Representation" and "Adaptation" are less intelligible than the more common "Rendition"/"Profile"/"Quality" and "Track". An API change might be the occasion to update method name so they can be discovered more easily.
Provide a simpler API for rendition/profile selection.
As exposed in [proposal] APIs to choose a specific Representation #877, we miss in the RxPlayer simple APIs to select a specific rendition. From recent discussions, we realized that it may makes sense to remove the
set{Audio,Video}Bitratemethods (but keeping the min/max ones) in profit of aset{Video,Audio}Representationone.Facilitate HLS support.
Supporting HLS is in our mind since several years, although it was always kept at low priority.
A v4.0.0 could allow us to facilitate that task, for example by defining new ways to approach some APIs.
Also, it would nice to have such a big feature introducing a
v4.0.0, though we would have to provide much more work to arrive to that point.Facilitate MSE-in-worker support
That's all I'm thinking of for now, do not hesitate to bring other points in there.
How to begin
As we're still in the very early phases and as we plan to do a big overhaul, it is difficult to know how to start.
RxPlayer episode 4: A new branch
Because we still need to start somewhere, I chose to create a new branch, named
next-v4(which is rebased onnext) which will add every commits we are confident that we want to add to a v4.0.0.This is not definitive however, and we may create other similar branches in the future.
Having a supplementary branch running in parallel makes maintenance harder as new developments have to also be added to the
next-v4branch. For the moment, I don't think that this is a huge problem because we're such in an early phase that we will mostly be bringing reflexions, not complex refactos.For now, I think that we will keep
next-v4up-to-date withnext(itself up-to-date withmaster) but if it becomes too much of a burden, we could be led to re-create another branch on top ofnext. Time will tell if a more inflexible strategy has to be taken in the future.I already began removing fullscreen APIs in that branch, as we're pretty sure we want to include it in the next major version.
Current ideas
I will list here the ideas we currently have and check the boxes for things which are already included in the
next-v4branch.Those put in bold will be ideas that have been approved by every maintainers (@PaulRosset and I).
One of the main role of this issue would be to discuss those and decide which other ideas we put in there.
BREAKING CHANGES
"FREEZING"state for cases where the playback position is currently not advancing due to an unknown reasonisFullscreen,setFullscreen,exitFullscreen, event:fullscreenChange).as a a UI is much more adapted to that task and can also bring with it things like a progress bar or HTML text tracksstopAtEndloadVideooption and never automatically stop at the end by default.This behavior can be counter-intuitive and can be very easily implemented by the UI
decipherabilityUpdateevent as it appeared to be not easily exploitable and exposed internal logic too muchinitialAudioBitrateandinitialVideoBitrateconstructor options with a singlebaseBandwidthoption, which better translates what this option is actually doing and allows for future optimizations on our side.RELOADINGplayer state (gettable through thegetPlayerStateandplayerStateChangeAPI) to happen at any time.networkConfigintorequestConfigand re-organize its inner properties to pave the way for future request-related APIs.networkConfigloadVideooption?getNativeTextTrackmethod.If advanced features are wanted, it's better to just use the HTML text track API
nativeTextTracksChangeevent.Same reason than for
getNativeTextTrackhideNativeSubtitlesfromloadVideooptionsSame reason than for
getNativeTextTrackxhrproperty from aNetworkError.Doing so stop us from using the fetch API
defaultAudioTrackanddefaultTextTrackin profit of new track APIsgetUrlmethod in profit of the more powerfulgetContentUrlsISupplementaryTextTrackOptionandISupplementaryImageTrackOption.Those are the types respectively for
supplementaryTextTracksandsupplementaryImageTrackswhich have been removedIBitrateEstimateas no API depend on it anymore.IManifest,IPeriod,IAdaptation,IRepresentation,IRepresentationInfos,IBifThumbnail,IBifObjectandIExposedSegmentas no API depend on them anymore.IDefaultAudioTrackOptionandIDefaultTextTrackOption.Those are the types respectively for
defaultAudioTrackanddefaultTextTrackloadVideooptions which have been removedgetManifest,getCurrentAdaptationsandgetCurrentRepresentations, as they reveal the RxPlayer's internals too muchresolvestep from HSS pipelines (legacy features which allowed to fetch an URL which itself gives the URL of the Manifest. Needed for some Canal+-specific usages).supplementaryTextTracksloadVideo optionmaximumBufferTimeinpositionUpdateevents tomaximumPositiongetVideoPlayedTimeAPI.Its name was very confusing and can be re-implemented relatively easily using the media element's buffered property
getVideoLoadedTimeAPI.Exact same reason than for
getVideoPlayedTimegetVideoDurationtogetMediaDurationgetVideoBufferGaptogetCurrentBufferGapsupplementaryImageTracksloadVideooption,imageTrackUpdateevent,getImageTrackDatamethod)keySystems[].licenseStoragekeySystemsoption (for aloadVideocall) by the better-namedpersistentLicenseConfig. ThepersistentLicenseboolean (also akeySystemsoption) has also been removed because it was redundant with the former option)throttleWhenHiddenplayer option in profit ofthrottleVideoBitrateWhenHiddenperiodChangeevents don't emit the fullPeriodstructure but a small subset of it.transportOptions.segmentLoaderloadVideooptions don't give the fullManifest,Period,Adaptation,RepresentationandISegmentstructures in arguments but a small subset of it.manifestLoaderadded to theloadVideo'stransportOptionsnow set an object as argument (with anurlproperty), to let us bring improvements on it in the futureframeRateis now always a number - in terms of frame per seconds - instead of a stringRepresentations(in methods:getAvailableVideoTracks,getVideoTrack,representationFilter,getAvailableAudioTracks,getAudioTrackand events:audioTrackChangeandvideoTrackChange) can have anundefinedbitrateaggressiveModefrom thetransportOptions(theloadVideooption)bitrateEstimationChangeeventIt is poorly understood (it's not always close to the expected bandwidth) and has a very complex relationship with the chosen quality. It is also an event that is today very often triggered (some application might rely on that) and that may not always be simple to bubble up to the API
-> Rename event as undocumented
__priv_bitrateEstimateChangeevent for specialized usage at Canal+ without guaranteeing API stabilityaudioTrackSwitchingModeloadVideo option intodefaultAudioTrackSwitchingModemanualBitrateSwitchingModeloadVideo option as it is not clear how it would interact at eachswitchingModeproperty at eachlockVideoRepresentationsandlockAudioRepresentations.getManualVideoBitrateandgetManualAudioBitratein profit of the Representations lock APIsgetAvailableVideoBitrates,getAvailableAudioBitrates,setAudioBitrate,setVideoBitrate,getAudioBitrate,getVideoBitratein profit of the Representations lock APIsgetPreferredAudioTracks,getPreferredVideoTracks,setPreferredAudioTracksandsetPreferredVideoTracks, types:IAudioTrackPreference,ITextTrackPreferenceandIVideoTrackPreference)in profit of the new tracks API
audioBitrateChangeandvideoBitrateChangeAPI in profit ofaudioRepresenIDtationChangeandvideoRepresentationChangeeventsavailableAudioBitratesChangeandavailableVideoBitratesChangeevents. Those are less needed with the new Representations lock API and can be more or less replicated through theaudioTrackChangeandvideoTrackChangeeventsIPersistentSessionStoragetype toIPersistentLicenseConfigdistinctiveIdentifierRequiredAPI, in profit of the more powerfuldistinctiveIdentifierAPIpersistentStateRequiredAPI, in profit of the more powerfulpersistentStateAPIkeySystems[].onKeyStatusesChangeAPI as it seems to never be usedaudioRobustnessesandvideoRobustnessesproperties of thekeySystemsoption ofloadVideocalls, as more powerful solutions now exist: respectivelyaudioCapabilitiesConfigandvideoCapabilitiesConfigtransportOptionsloadVideo options by putting all its inner properties directly at the top levelFeatures
setAudioTrack,setVideoTrackandsetTextTracknow may take an object in argument, with the track's id set as atrackIdproperty, to allow new featuresswitchingModeoptional property tosetVideoTrackandsetAudioTrackperiodIdproperty tosetAudioTrack,setVideoTrackandsetTextTrackgetAvailableAudioTracks,getAvailableTextTracks,getAvailableVideoTracks,getAudioTrack,getTextTrackandgetVideoTrackcan now optionally take aperiodIdargument to retrieve track information on a specific PerioddisableTextTrack, anddisableVideoTrackcan now optionally take aperiodIdargument to disable a track for a specific PeriodlockedRepresentationsproperty tosetAudioTrackandsetVideoTrackgetCurrentPeriodmethod to retrieve information on the Period currently playedgetAvailablePeriodsmethod to retrieve information on all Periods on which a track or Representation choice can be madelockVideoRepresentations,lockAudioRepresentations,getLockedVideoRepresentations,getLockedAudioRepresentations,unlockVideoRepresentationsandunlockAudioRepresentationsmethods to allow a complex selection of RepresentationgetVideoRepresentationandgetAudioRepresentationmethod to retrieve information on the currently loaded representationsgetContentUrlsallowing to retrieve the one or several known URLs through which the current Manifest or content is reachable.newAvailablePeriodsevent to signal new Period on which a track and/or Representation choice can be madebrokenRepresentationsLockevent for when a Representations lock could not be respected anymoreautoTrackSwitchevent for when a chosen track could not be kept by the RxPlayerISegmentLoaderContextpublic type for the first argument of thesegmentLoaderAPIIRepresentationFilterRepresentationpublic type for the first argument of therepresentationFilterAPIIRepresentationContextpublic type for the second argument of therepresentationFilterAPIIManifestLoaderInfopublic type for the first argument of themanifestLoaderAPIIPeriodChangeEventpublic type to define the properties send through aperiodChangeeventIPeriodpublic type to define a Period object returned by methods likegetAvailablePeriodsorgetCurrentPeriodIVideoTrackSwitchingModepublic type to define the type of theswitchingModeproperty optionally given tosetAudioTrackIAudioRepresentationsSwitchingModepublic type to define the type of theswitchingModeproperty optionally given tolockAudioRepresentationsIVideoRepresentationsSwitchingModepublic type to define the type of theswitchingModeproperty optionally given tolockAudioRepresentationsIBrokenRepresentationsLockContextpublic type to define the type sent as a payload of thebrokenRepresentationsLockeventIAutoTrackSwitchEventPayloadpublic type to define the type sent as a payload of theautoTrackSwitcheventILockedVideoRepresentationsSettingspublic type to define the object that should be given to the newlockVideoRepresentationmethodILockedAudioRepresentationsSettingspublic type to define the object that should be given to the newlockAudioRepresentationmethodIAudioTrackSettingpublic type to define the object that may be given to thesetAudioTrackmethodIVideoTrackSettingpublic type to define the object that may be given to thesetVideoTrackmethodITextTrackSettingpublic type to define the object that may be given to thesetTextTrackmethoddistinctiveIdentifierproperty in thekeySystemsoption (given to theloadVideomethod) to have full control over the MediaKeySystemConfiguration of the same name in the chosen key systempersistentStateproperty in thekeySystemsoption (given to theloadVideomethod) to have full control over the MediaKeySystemConfiguration of the same name in the chosen key systemaudioCapabilitiesConfigandvideoCapabilitiesConfigproperties in thekeySystemsoption (given to theloadVideomethod) to allow advanced configuration of respectively the "audioCapabilities" and "videoCapabilities" in the asked MediaKeySystemConfigurationPending
keySystems[].fallbackOnloadVideooption in profit of more configurablekeySystems[].onKeyOutputRestrictedandkeySystems[].onKeyInternalErroroptions?"rx-player/log"?manifestLoaderin some ways?segmentLoaderto low-latency-> for now: another segment loader for low-latency only
The text was updated successfully, but these errors were encountered: