THEOplayer 8.5.0

theoplayer/changelog.md

@@ -5,6 +5,49 @@ sidebar_custom_props: { 'icon': '📰' }
 toc_max_heading_level: 2
 ---
 
+## 🚀 8.5.0 (2024/11/19)
+
+### Web
+
+#### ✨ Features
+
+- Added support for Millicast audio-only streams.
+- Added audio track events for Millicast audio tracks.
+- Added support for chromecasting and airplaying THEOlive streams (with higher latency).
+
+#### ⚡ Improvements
+
+- Improved error reporting when an asset cannot be played because of lack of DRM support in the platform.
+- Updated documentation to clearly state the incompatibility of VMAP ads with `timeOffset` and added in warnings for when it happens anyway.
+
+#### 🐛 Issues
+
+- Fixed an issue where the `ended` event would no longer fire when seeking to the end of a stream while the player is paused in Chrome.
+- Fixed a memory leak for HESP streams.
+
+### Android
+
+#### ✨ Features
+
+- Added `MillicastSource.option` to set additional subscriber options for a [Millicast](https://www.theoplayer.com/docs/theoplayer/how-to-guides/android/millicast/getting-started/) stream.
+- Added support for CMCD in TheoLive.
+
+#### 🐛 Issues
+
+- Fixed an issue where attempting to load an MP4 or MP3 source that is not allowed by the player's license would crash the app instead of dispatching an `ErrorEvent`.
+- Fixed an issue where switching video tracks in a Millicast stream would show frames from both the old and new video track.
+- Fixed an issue where VMAP mid-roll ads were not being played.
+
+### iOS
+
+#### ⚡ Improvements
+
+- Removed extra play/pause events after preroll ads.
+
+#### 🐛 Issues
+
+- Fixed an issue on the cue activation algorithm for iOS, that was preventing cues from being activated (i.e 'entered').
+
 ## 🚀 8.4.2 (2024/11/14)
 
 ### Android

theoplayer/getting-started/01-sdks/03-ios/00-getting-started.md

@@ -209,7 +209,7 @@ let adDescription = GoogleImaAdDescription(src: adSrc)
 let adDescriptionWithOffset = GoogleImaAdDescription(src: adSrc, timeOffset: "10")
 ```
 
-The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file thus they don't require a timeOffset parameter.
+The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.
 
 Finally, we pass the ad description to the player either by setting it in the source:
 

theoplayer/how-to-guides/01-ads/03-how-to-set-up-vast-and-vmap.md

@@ -15,7 +15,7 @@ THEOplayer currently supports 4 types of client-side ad integrations:
 4. [FreeWheel](../../how-to-guides/01-ads/06-freewheel.md)
 
 This article explains scheduling VAST and VMAP ads.
-Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide. 
+Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.
 
 ## SDKs
 
@@ -57,17 +57,17 @@ In this `AdDescription`,
 player.source = {
   sources: [
     {
-      src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
-    }
+      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
+    },
   ],
   ads: [
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "start",
-      type: "vast",
-      integration: "csai" // When no integration is provided, the player defaults to `csai`.
-    }
-  ]
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: 'start',
+      type: 'vast',
+      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
+    },
+  ],
 };
 ```
 
@@ -156,31 +156,31 @@ The following snippets demonstrate how you would configure two pre-rolls, two mi
 player.source = {
   sources: [
     {
-      src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
-    }
+      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
+    },
   ],
   ads: [
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "start"
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: 'start',
     },
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "start"
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: 'start',
     },
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "00:00:15"
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: '00:00:15',
     },
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "00:00:30"
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: '00:00:30',
     },
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "end"
-    }
-  ]
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      timeOffset: 'end',
+    },
+  ],
 };
 ```
 
@@ -244,23 +244,23 @@ Note that the `skipOffset` property is not supported when using other ad integra
 player.source = {
   sources: [
     {
-      src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
-    }
+      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
+    },
   ],
   ads: [
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      type: "vast",
-      timeOffset: "00:00:15",
-      skipOffset: "5"
-    }
-  ]
+      sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
+      type: 'vast',
+      timeOffset: '00:00:15',
+      skipOffset: '5',
+    },
+  ],
 };
 ```
 
 ## VMAP
 
-Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains.
+Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement. However, you don't define the `timeOffset`, because the VMAP playlist defines the offsets of each ad break it contains. The time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than `VAST`. Setting a `timeOffset` on a `VMAP` ad will cause your ads not to be scheduled correctly, unless you explicitly configured an `AdSource.type`, in which case `timeOffset` will be ignored. This is because the player must decide up front when to load the ad source: `VMAP` ads must be loaded immediately in order to schedule them correctly, while loading a `VAST` ad can be deferred until right before the `timeOffset` at which to play them. Therefore, if a `timeOffset` is configured without an explicit `AdSource.Type`, the player will assume that it's a `VAST` ad.
 
 The snippets below demonstrate how to configure a VMAP advertisement.
 
@@ -271,17 +271,16 @@ The snippets below demonstrate how to configure a VMAP advertisement.
 player.source = {
   sources: [
     {
-      src: "https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
-    }
+      src: 'https://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
+    },
   ],
   ads: [
     {
-      sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml",
-      timeOffset: "start",
-      type: "vmap",
-      integration: "csai" // When no integration is provided, the player defaults to `csai`.
-    }
-  ]
+      sources: 'https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml',
+      type: 'vmap',
+      integration: 'csai', // When no integration is provided, the player defaults to `csai`.
+    },
+  ],
 };
 ```
 
@@ -328,7 +327,7 @@ The following samples illustrate the `schedule` function across different SDKs.
 
 ```javascript
 player.ads.schedule({
-  sources: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"
+  sources: 'https://cdn.theoplayer.com/demos/ads/vast/vast.xml',
 });
 ```
 
@@ -348,6 +347,7 @@ theoplayer.ads.schedule(adDescription: GoogleImaAdDescription(src: "https://cdn.
 ```
 
 ## Resources
+
 - [Samples for Web SDK](https://github.com/THEOplayer/samples-html5-sdk)
 - [Samples for Android SDK](https://github.com/THEOplayer/samples-android-sdk)
-- [Samples for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk)
+- [Samples for iOS SDK](https://github.com/THEOplayer/samples-ios-sdk)

theoplayer/how-to-guides/shared/theolive/_getting-started-intro.mdx

@@ -0,0 +1 @@
+THEOlive delivers broadcast quality live streaming at sub-second latency, enabling interactivity and fan engagement.

theoplayer/how-to-guides/web/theolive/00-getting-started.mdx

@@ -0,0 +1,50 @@
+# Getting started with THEOlive on Web
+
+import Intro from '../../shared/theolive/_getting-started-intro.mdx';
+
+<Intro />
+
+## Usage
+
+1. Follow [our Getting Started guide](../../../getting-started/01-sdks/01-web/00-getting-started.mdx)
+   to set up THEOplayer in your web app or website.
+2. Add a THEOlive source to your player's source.
+
+### Add a THEOlive source
+
+After setting up your THEOplayer on your web page, set its source to a `SourceDescription` containing a `THEOliveSource`.
+You'll need a THEOlive channel ID:
+
+```javascript
+const player = new THEOplayer.Player(element, configuration);
+player.source = {
+  sources: {
+    type: 'theolive',
+    src: 'your-channel-id',
+  },
+};
+```
+
+### Add configuration
+
+Optionally, you can provide additional configuration to the player, specific for THEOlive streams. To
+configure these settings, add a `theolive` property to the player configuration. For an exhaustive list of these options,
+please visit the [documentation](pathname:///theoplayer/v8/api-reference/web/interfaces/TheoLiveConfiguration.html).
+
+```javascript
+var player = new THEOplayer.Player(element, {
+    license: 'your-license',
+    // This is needed for fallback to work properly
+    retryConfiguration: {
+        maxRetries: 6
+    },
+    theoLive: {
+        externalSessionId: 'my-external-session-id',
+        fallbackEnabled: true
+    }
+});
+```
+
+## More information
+
+- [API references](pathname:///theoplayer/v8/api-reference/web/interfaces/TheoLiveSource.html)

theoplayer/how-to-guides/web/theolive/01-chromecast.mdx

@@ -0,0 +1,5 @@
+# Chromecast
+
+THEOlive streams have support for Chromecast. However, a limitation for now is that the latency is higher while
+casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer.
+The instructions are described in the [Chromecast guide](../../03-cast/01-chromecast/06-enable-chromecast-on-the-sender.md).

theoplayer/how-to-guides/web/theolive/02-airplay.mdx

@@ -0,0 +1,5 @@
+# Airplay
+
+THEOlive streams have support for Airplay. However, a limitation for now is that the latency is higher while
+casting (about 12 seconds). Configuring it is exactly the same as for other streams you would play with THEOplayer.
+The instructions are described in the [Airplay guide](../../03-cast/02-airplay/00-introduction.md).

theoplayer/how-to-guides/web/theolive/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "THEOlive",
+  "customProps": {
+    "icon": "🚀"
+  }
+}

theoplayer/knowledge-base/01-advertisement/01-user-guide.md

@@ -173,12 +173,14 @@ The player supports VAST by specifying a URL parameter to the VAST description i
 
 You can specify an optional offset parameter that indicates at what time the ad should be displayed before, during or after the video. This parameter works for linear as well as non-linear and companion ads and has the following specification:
 
-- `timeOffset`: This optional parameter allows you to determine the place of the specified ad. Five different formats are allowed:
+- `timeOffset`: This optional parameter allows you to determine the placement of the specified ad. Five different formats are allowed:
   - **seconds**: a numeric value representing the number of seconds into the video the ad should play.
   - **time**: in the format `hh:mm:ss.mmm` (`.mmm` is optional), for example `'00:35:30.000'`.
   - **percentage**: in the format `n%`, where n is a value from 0-100, for example `50%`.
   - **start/end**: The value `'start'` signifies that the video is a pre-roll and should be played before the actual video can be watched. The value `'end'` signifies that the video is a post-roll and should be played after the original video.
 
+If you are using a VMAP ad, this property should not be used, as the VMAP format specifies its own time offset for breaks. Using this property with VMAP may cause no ad breaks or incorrect placement of ad breaks.
+
 **Configuring your ad to be skippable**
 
 You can allow an ad to be skipped by adding a skip parameter in the configuration. The skip parameter describes how long - in seconds - the ad must be watched before the user can skip it. The parameter is optional: if you do not define one, THEOplayer will use the information specified by the VAST file itself.

theoplayer/static/theoplayer/v8/api-reference/android/com/theoplayer/android/api/millicast/MillicastSource.html

@@ -178,6 +178,12 @@ <h3>Field Summary</h3>
                                             <td class="colLast"></td>
                                         </tr>
 
+                                        <tr class="rowColor">
+                                            <td class="colFirst"><code>private final Option</code></td>
+                                            <th class="colSecond" scope="row"><code><a href=MillicastSource.html#option>option</a></code></th>
+                                            <td class="colLast"></td>
+                                        </tr>
+
                                     </table>
                                 </div>
                             </li>
@@ -204,7 +210,7 @@ <h3>Constructor Summary</h3>
 
                                             <tr class="altColor">
                                                 <th class="colConstructorName" scope="row"><code><span class="memberNameLink"><a
-                                                        href="#MillicastSource(com.millicast.subscribers.Credential)">MillicastSource</a></span>(Credential credential)</code></th>
+                                                        href="#MillicastSource(com.millicast.subscribers.Credential,com.millicast.subscribers.Option)">MillicastSource</a></span>(Credential credential, Option option)</code></th>
                                                 <td class="colLast"></td>
                                             </tr>
 
@@ -265,6 +271,14 @@ <h3>Method Summary</h3>
                                             <td class="colLast">The credentials required to connect and subscribe to the stream.</td>
                                         </tr>
 
+                                        <tr id="i1" class="rowColor">
+                                            <td class="colFirst"><code>final Option</code>
+                                            </td>
+                                            <th class="colSecond" scope="row"><code><a href=MillicastSource.html#getOption()>getOption</a>() </code>
+                                            </th>
+                                            <td class="colLast">The optional configuration for adjusting stream settings</td>
+                                        </tr>
+
                                         </tbody>
                                     </table>
                                 </div>
@@ -302,11 +316,11 @@ <h3>Methods inherited from class&nbsp;java.lang.Object</h3>
                             </a>
                                 <h3>Constructor Detail</h3>
 
-                                <a name="MillicastSource(com.millicast.subscribers.Credential)"></a>
+                                <a name="MillicastSource(com.millicast.subscribers.Credential,com.millicast.subscribers.Option)"></a>
                                 <ul class="blockList">
                                     <li class="blockList">
                                         <h4>MillicastSource</h4>
-                                        <pre>MillicastSource(Credential credential)</pre>
+                                        <pre>MillicastSource(Credential credential, Option option)</pre>
                                         <div class="block"></div>
 
                                     </li>
@@ -329,7 +343,7 @@ <h3>Method Detail</h3>
                                     <!--   -->
                                 </a>
                                 <ul class=
-                                              "blockListLast"
+                                              "blockList"
                                           >
                                     <li class="blockList">
                                         <h4>getCredential</h4>
@@ -344,6 +358,29 @@ <h4>getCredential</h4>
 
 
 
+                                        </dl>
+                                    </li>
+                                </ul>
+
+                                <a id="getOption()">
+                                    <!--   -->
+                                </a>
+                                <ul class=
+                                              "blockListLast"
+                                          >
+                                    <li class="blockList">
+                                        <h4>getOption</h4>
+                                        <pre class="methodSignature"> final Option <a href=MillicastSource.html#getOption()>getOption</a>()</pre>
+                                        <div class="block"><p>The optional configuration for adjusting stream settings</p></div>
+
+                                        <dl>
+
+
+
+
+
+
+
                                         </dl>
                                     </li>
                                 </ul>