diff --git a/hisplayer-api.md b/hisplayer-api.md index 149b199..3de437d 100644 --- a/hisplayer-api.md +++ b/hisplayer-api.md @@ -17,9 +17,19 @@ The following public APIs are provided by **HISPlayerManager** * **public List \ url**: List of the URLs for the stream. * **public bool autoPlay**: If true, the players will start playing automatically after set-up. * **public bool EnableRendering**: Determines if the stream will be rendered or not. The value can change in every moment for toggling between render or non-render mode. If true, the player will be rendered. It only can change in runtime. - * **public bool LoopPlayback (Read-only)**: Loop the current playback. It's true by default. To modify this value, please, use the Editor or the alternative constructor **StreamProperties(loopPlayback, autoTransition)**. - * **public bool AutoTransition (Read-only)**: Change the playback to the next video in the playlist. This action won't have effect when loopPlayback is true. It's false by default. To modify this value, please, use the Editor or the alternative constructor **StreamProperties(loopPlayback, autoTransition)**. + * **public bool FlipTextureVertically**: Flip the texture of the stream vertically. This value should be called before **SetUpPlayer** or **AddStream** functions. Only supported on Android. + * **public bool LoopPlayback (Read-only)**: Loop the current playback. It's true by default. To modify this value, please, use the Editor or the constructor **StreamProperties(loopPlayback, autoTransition)**. + * **public bool AutoTransition (Read-only)**: Change the playback to the next video in the playlist. This action won't have effect when loopPlayback is true. It's false by default. To modify this value, please, use the Editor or the constructor **StreamProperties(loopPlayback, autoTransition)**. * **public List \ keyServerURI**: List of the DRM license key for each URL. + * **public List \ DRMTokens**: List of the DRM tokens for each URL. + * **public List adsProperties**: List of properties to configure advertisement insertions for each player in the scene. This API is not supported for Android. Supported Platform: [WebGL](https://hisplayer.github.io/UnityWebGL-SDK/#/). + * **public int startingBitrate**: The bitrate in bps the player will try to start playing. Setting it to 0 will make the player start with the lowest track. This API is not supported for Android. Supported Platform: [WebGL](https://hisplayer.github.io/UnityWebGL-SDK/#/). + * **public int manifestTimeout**: The manifest request connection timeout, in milliseconds. Zero means unlimited. Defaults to 10000 milliseconds. Not visible in the Editor. This API is not supported for Android. Supported Platform: [WebGL](https://hisplayer.github.io/UnityWebGL-SDK/#/). + * **public int segmentsTimeout**: The segments requests connection timeout, in milliseconds. Zero means unlimited. Defaults to 5000 milliseconds. Not visible in the Editor. This API is not supported for Android. Supported Platform: [WebGL](https://hisplayer.github.io/UnityWebGL-SDK/#/). + +* **public struct DRM_Token**: Information for the DRM token: + * **public string tokenKey**: Key of the token associated with the url. + * **public string tokenValue**: Value of the token associated with the key. * **public enum HISPlayerRenderMode**: Type of texture for rendering. * **RenderTexture** @@ -29,39 +39,54 @@ The following public APIs are provided by **HISPlayerManager** * **public enum HISPlayerEvent**: The list of events provided by HISPlayer SDK. The events can be used with the virtual functions in the next section: * **HISPLAYER_EVENT_PLAYBACK_READY** + * **HISPLAYER_EVENT_PLAYLIST_CHANGE** + * **HISPLAYER_EVENT_VIDEO_SIZE_CHANGE** * **HISPLAYER_EVENT_PLAYBACK_PLAY** * **HISPLAYER_EVENT_PLAYBACK_PAUSE** * **HISPLAYER_EVENT_PLAYBACK_STOP** * **HISPLAYER_EVENT_PLAYBACK_SEEK** * **HISPLAYER_EVENT_VOLUME_CHANGE** * **HISPLAYER_EVENT_END_OF_PLAYLIST** + * **HISPLATER_EVENT_ON_TRACK_CHANGE** * **HISPLAYER_EVENT_ON_STREAM_RELEASE** - * **HISPLAYER_EVENT_TEXT_RENDER** + * **HISPLAYER_EVENT_TEXT_RENDER** * **HISPLAYER_EVENT_AUTO_TRANSITION** - * **HISPLAYER_EVENT_PLAYBACK_BUFFERING** + * **HISPLAYER_EVENT_PLAYBACK_BUFFERING** + * **HISPLAYER_EVENT_NETWORK_CONNECTED** * **HISPLAYER_EVENT_END_OF_CONTENT** + * **HISPLAYER_EVENT_AD_BLOCK_STARTED** + * **HISPLAYER_EVENT_AD_BLOCK_ENDY** + * **HISPLAYER_EVENT_AD_STARTED** + * **HISPLAYER_EVENT_AD_STOPPED** + * **HISPLAYER_EVENT_AD_PODS_INFO** + * **HISPLAYER_EVENT_ID3_METADATA** + - * **public enum HISPlayerError**: The list of errors provided by HISPlayer SDK. The errors can be used with the virtual functions in the next section: +* **public enum HISPlayerError**: The list of errors provided by HISPlayer SDK. The errors can be used with the virtual functions in the next section: * **HISPLAYER_ERROR_LICENSE_EXPIRED** (no function on this) * **HISPLAYER_ERROR_NOT_VALID_APPID** (no function on this) * **HISPLAYER_ERROR_GENERAL_LICENSE_ERROR** (no function on this) * **HISPLAYER_ERROR_IOS_API_NOT_REGISTERED** (no function on this) * **HISPLAYER_ERROR_LICENSE_DISABLED** (no function on this) + * **HISPLAYER_ERROR_IMPRESSIONS_LIMIT_REACHED** (no function on this) + * **HISPLAYER_ERROR_PLAYBACK_DURATION_LIMIT_REACHED** (no function on this) * **HISPLAYER_ERROR_NETWORK_FAILED** * **public struct HISPlayerEventInfo**: The information of the triggered event. - * **public HISPlayerEvent eventType**: The type of the event triggered. - * **public int playerIndex**: The index of the player where the event is triggered. - * **public float param1**: This will have different meanings depending on the event (see more information in [Functions](#Functions)). If there is no information about the parameter, it will have the default value -1. - * **public float param2**: This will have different meanings depending on the event (see more information in [Functions](#Functions)). If there is no information about the parameter, it will have the default value -1. - * **public float param3**: This will have different meanings depending on the event (see more information in [Functions](#Functions)). If there is no information about the parameter, it will have the default value -1. - * **public float param4**: This will have different meanings depending on the event (see more information in [Functions](#Functions)). If there is no information about the parameter, it will have the default value -1. - * **public string stringInfo**: Log information about the event. - -* **public struct HISPlayerCaptionElement**: The information of the triggered event turns into caption’s format. + * **public HISPlayerEvent eventType**: The type of the event triggered. * **public int playerIndex**: The index of the player where the event is triggered. - * **public string caption**: The next generated caption text. - + * **public float param1**: This will have different meanings depending on the event. If there is no information about the parameter, it will have the default value -1. + * **public float param2**: This will have different meanings depending on the event. If there is no information about the parameter, it will have the default value -1. + * **public float param3**: This will have different meanings depending on the event. If there is no information about the parameter, it will have the default value -1. + * **public float param4**: This will have different meanings depending on the event. If there is no information about the parameter, it will have the default value -1. + * **public string stringInfo**: Log information about the event. + +* **public struct HISPlayerErrorInfo**: The information of the triggered error. + * **public HISPlayerError errorType**: The type of the error triggered. + * **public int playerIndex**: The index of the player where the error is triggered. + * **public float param1**: This will have different meanings depending on the error. If there is no information about the parameter, it will have the default value -1. + * **public string stringInfo**: Log information about the error. + * **public struct HISPlayerTrack**: * **public string id**: Id of the track * **public int bitrate**: Bitrate of the track in bits per second. @@ -73,6 +98,10 @@ The following public APIs are provided by **HISPlayerManager** * **public string id**: ID of the caption * **public string language**: Language of the caption +* **public struct HISPlayerCaptionElement**: The information of the triggered event turns into caption’s format. + * **public int playerIndex**: The index of the player where the event is triggered. + * **public string caption**: The next generated caption text. + ## Functions The following functions are provided by **HISPlayerManager**. They are **not public** so it’s necessary to create a custom script which inherits from **HISPlayerManager**. @@ -100,16 +129,6 @@ Calling functions such as GetTracks before this event is triggered will provide #### protected virtual void EventPlaybackPlay(HISPlayerEventInfo eventInfo) Override this method to add custom logic when **HISPlayerEvent.HISPlayer_EVENT_PLAYBACK_PLAY** is triggered. This event occurs whenever an internal playback has been played. - - - - - - - - - -
NameDescription
param1PLAY = 1, PAUSE = 0.
#### protected virtual void EventPlaybackPause(HISPlayerEventInfo eventInfo) Override this method to add custom logic when **HISPlayerEvent.HISPlayer_EVENT_PLAYBACK_PAUSE** is triggered. @@ -198,6 +217,9 @@ This event occurs whenever an internal playback is buffering. Override this method to add custom logic when **HISPlayerEvent.HISPlayer_EVENT_END_OF_CONTENT** is triggered. This event occurs whenever an internal playlist reaches the end of the list. +#### protected virtual void ErrorInfo(HISPlayerErrorInfo subtitlesInfo) +Override this method to add custom logic when an error callback is triggered. Please, refer to the **HISPlayerError** list. + #### protected virtual void ErrorNetworkFailed(HISPlayerErrorInfo errorInfo) Override this method to add custom logic when **HISPlayerError.HISPLAYER_ERROR_NETWORK_FAILED** is triggered. This error occurs whenever the network on a stream playback has failed. @@ -229,23 +251,27 @@ Modify the volume of a certain stream giving a **playerIndex**. The **volume** o #### protected void AddStream(StreamProperties newStream) Add a new stream to the list **multiStreamProperties**. The stream must be added using this function instead of changing the list manually. -#### protected void ChangeVideoContent(int playerIndex, int urlIndex) -Change the video’s url of a certain player. The **playerIndex** is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. The **urlIndex** is associated with the index of the element in the list of urls. - -#### protected void RemoveStream(int playerIndex) -Remove a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. - #### protected void AddVideoContent(int playerIndex, string url) -Add new content to a certain player. If the **enableDRM** variable is true, a video content with an empty license will be added. The **playerIndex** is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. The url is the link to the new video. Please, make sure the string is correct. +Add new content to a certain player. If the **enableDRM** variable is true, a video content with an empty license will be added. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. The **url** is the link to the new video. Please, make sure the string is correct. This function supports local file paths. #### protected void AddVideoContent(int playerIndex, string url, string keyServerUri, string token key = “empty”opt, string token value= “empty”opt) Add new content to a certain player and its respective key server uri. The enableDRM variable must be true to use this function. The **playerIndex** is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. The url is the link to the new video. The keyServerUri is the token key associated with the url. Please, make sure the string is correct. +#### protected void ChangeVideoContent(int playerIndex, int urlIndex, int resumePosition = 0, AdsProperties ads = null) +Change the video’s url of a certain player. The next playback will start paused. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. The **urlIndex** is associated with the index of the element in the list of urls. +The parameters **resumePosition** and **AdsProperties** are not supported for Android and null by default. Please leave them empty when using this function. + #### protected void RemoveVideoContent(int playerIndex, int urlIndex) -Remove content from a certain player. The **playerIndex** is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. The urlIndex is associated with the index of the element in the list of urls. +Remove content from a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. The **urlIndex** is associated with the index of the element in the list of urls. -#### protected string GetPlayerLog(int playerIndex) -Provides a log message obtained from a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. +#### protected void RemoveStream(int playerIndex) +Remove a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected void SetPlaybackSpeedRate(int playerIndex, float speed) +Modify the **speed rate** of a certain stream giving a **playerIndex**. The value of the player's speed must be greater (>) than 0.0f and less than or equal (<=) to 8.0f. The default value of player's speed is 1.0f. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected float GetPlaybackSpeedRate(int playerIndex) +Obtain the **speed rate** of a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. #### protected long GetVideoPosition(int playerIndex) Provides information about the timeline position in milliseconds, of the current video of a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. @@ -253,6 +279,30 @@ Provides information about the timeline position in milliseconds, of the current #### protected long GetVideoDuration(int playerIndex) Provides information about the total duration in milliseconds, of the current video of a certain player. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. +#### protected HISPlayerTrack[] GetTracks(int playerIndex) +Provides information about a track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetTrackBitrate(int playerIndex, int trackIndex) +Get the bitrate of a certain track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetTrackWidth(int playerIndex, int trackIndex) +Get the width of a certain track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetTrackHeight(int playerIndex, int trackIndex) +Get the height of a certain track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 of the list. + +#### protected int GetVideoWidth(int playerIndex) +Get the width of the current track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetVideoHeight(int playerIndex) +Get the height of the current track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetTrackID(int playerIndex, int trackIndex) +Get the ID of a certain track of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected int GetTrackCount(int playerIndex) +Get the number of tracks of a certain stream. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + #### public void EnableCaptions(int playerIndex, bool enabled) Enables the captions of the stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. @@ -271,6 +321,12 @@ Obtain the language of a certain caption of a certain player. The playerIndex is #### public void SelectCaptionTrack(int playerIndex, int ccTrackIndex) Select a certain caption of a certain stream to be used. Before using this functions is recommended to use GetCaptionTrackList in order to know all the information about the captions. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. +#### protected void SetMaxBitrate(int playerIndex, int bitrate) +Set a new maximum bitrate (in bits per second) of a specific track. This doesn't disable ABR. The possible tracks can be obtained from the tracks returned from the method GetTracks. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + +#### protected void SelectTrack(int playerIndex, int bitrate) +Select a certain track of a certain stream to be used as the main track. This action will disable ABR, to enable it again you can use **EnableABR** API. The possible tracks can be obtained from the tracks returned from the method GetTracks. The **playerIndex** is associated with the index of the element of **Multi Stream Properties**, e.g. the index 0 is the element 0 in the list. + #### public HisPlayerAudioTrack[] GetAudioTrackList(int playerIndex) Provide information about all the audio tracks of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. @@ -285,30 +341,3 @@ Obtain the language of a certain audio of a certain player. The playerIndex is a #### public void SelectAudioTrack(int playerIndex, int audioTrackIndex) Select a certain audio-track of a certain stream to be used. Before using this functions is recommended to use GetAudioTrackList in order to know all the information about the audio-tracks. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected HISPlayerTrack[] GetTracks(int playerIndex) -Provides information about a track of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected int GetTrackBitrate(int playerIndex, int trackIndex) -Get the bitrate of a certain track of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected int GetTrackWidth(int playerIndex, int trackIndex) -Get the width of a certain track of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected int GetTrackHeight(int playerIndex, int trackIndex) -Get the height of a certain track of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 of the list. - -#### protected int GetTrackID(int playerIndex, int trackIndex) -Get the ID of a certain track of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected int GetTrackCount(int playerIndex) -Get the number of tracks of a certain stream. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### protected void SelectTrack(int playerIndex, int bitrate) -Select a certain track of a certain stream to be used as the main track. This action will disable ABR. The possible tracks can be obtained from the tracks returned from the method GetTracks. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### public void SetPlaybackSpeedRate(int playerIndex, float speed) -Modify the **speed rate** of a certain stream. The value of the player's speed must be greater (>) than 0.0f and less than or equal (<=) to 8.0f. The default value of player's speed is 1.0f. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list. - -#### public float GetPlaybackSpeedRate(int playerIndex) -Obtain the **speed rate** of a certain player. The playerIndex is associated with the index of the element of Multi Stream Properties, e.g. the index 0 is the element 0 in the list.