# CMCD V2 - Response Mode
## PR Description
This PR focuses on the implementation of Response Mode functionalities
for version 2 of the Common Media Client Data (CMCD v2) specification
within the Shaka Player project.
Key changes made in this pull request include:
- **Response Mode**: CMCD v2 introduces "Request Mode" "Response Mode"
and "Event Mode". Request Mode aligns with the default delivery mode in
CMCD v1. Response Mode, which this PR implements, allows clients to send
data to one or more alternative destinations after receiving either a
full response or an error to a media object request. These reports use
one of the defined data transmission modes (Query Mode or Headers Mode)
- **CmcdTarget**: A new configuration type, `shaka.extern.CmcdTarget`,
was introduced. This configuration allows specifying the transmission
strategy (mode=response) since targets can also be configured for
**event mode** (mode=event), whether it's enabled (enabled), if it uses
HTTP headers mode (`useHeaders=true`) or query parameters mode, the
destination URL (url), and specific keys to include (`includeKeys`). For
Response Mode, the mode value includes 'response'.
- **Independent Handling of Transmission Modes**: Request mode and
Response mode can be enabled and disabled independently using the
previously mentioned CmcdTarget config for response mode and the base
config for request mode.
- **Validation and Filtering of Keys**: Allowed keys for Response Mode
were added, and validation for these keys was implemented. The
capability to include (`includeKeys`) and filter specific keys for both
Request Mode and each Response Mode target was also enabled. Also, CMCD
dictionary definitions were moved to a new dedicated section to improve
structure
- **Unit Tests**: Extensive unit tests were included and unified to
validate CMCD v2 functionality in both Request Mode and Response Mode.
Config example with request mode and targets with response mode:
```js
const cmcdConfig = {
enabled: true,
version: 2,
contentId: 'content-id',
useHeaders: false,
targets: [{
mode: 'response',
useHeaders: false,
enabled: true,
url: 'http://localhost:3003/response-mode'
}]
}
```
## Keys not implemented in this PR
The following keys are defined in the CMCD v2 specification but are not
calculated or attached to requests/responses in the `cmcd_manager.js`
code:
- **Common & Request Mode Keys:**
- **`ab` (Aggregate encoded bitrate)**
- **`tbl` (Target Buffer length)**
- **`cdn` (CDN Id)**
- **`bg` (Backgrounded)**
- **`sta` (State)**
- **`ts` (Timestamp)**
- **`tpb` (Top playable bitrate)**
- **`lb` (Lowest encoded bitrate)**
- **`tab` (Top aggregated encoded bitrate)**
- **`lab` (Lowest aggregated encoded bitrate)**
- **`pt` (Playhead time)**
- **`ec` (Player Error Code)**
- **Response Mode Keys:**
- **`rc` (Response code)**
- **`ttfb` (Time to first byte)**
- **`ttfbb` (Time to first body byte)**
- **`ttlb` (Time to last byte)**
- **`url` (Request URL)**
- **`cmsdd` (CMSD Dynamic Header)**
- **`cmsds` (CMSD Static Header)**
Related to https://github.com/shaka-project/shaka-player/issues/8660
---------
Co-authored-by: Constanza Dibueno <121617928+cotid-qualabs@users.noreply.github.com>
Co-authored-by: Álvaro Velad Galván <ladvan91@hotmail.com>
Provides the Segment Reference to the ABR Manager via the request
context. This allows the ABR manager to get information about the
specific segment being downloaded such as the start and end time (used
to calculate segment duration).
Adds a replacement for removed JSDoc checks from ESLint v9.
Additionally fixes lots of issues found in the JSDoc, such as:
- missing `@param`/`@return` annotations
- bad formatting
- params order
- param name in the same line as type definition (tried to disable it,
but it was causing other issues and we didn't have lots of places with
such formatting)
Minor fixes in code found by Closure Compiler after fixing JSDoc are
also included.
By limiting progress events to only ones with minimal chunk size, we might end up with feeding better default ABR implementation, which should result in more accurate adaptation in case of network throttle.
Some assets might rely on networking engine filters (request and
response filters) to properly download their assets. However, the
preload manager's need to use a fresh networking engine also caused it
to not use any filters set on the player already. This changes the
process of setting up a preload manager, to make it copy over any
filters defined on the player's networking engine.
Fixes#6698
This PR makes the following request information available for ABR consideration. Allowing the ABR manager to know about the request latency from the time to first byte and knowing the order order of a packet, as well as the contentType of the request.
This adds an optional parameter to request and response filters, of a
new enum called AdvancedRequestType.
This enum describes request types that are subtypes of the basic types.
For example, INIT_SEGMENT is a type of SEGMENT.
This gives users more information about the type of the request, while
maintaining backwards compatibility.
Closes#4966
Before, we would count on all event listeners for FakeEventTargets to
be cleaned up by the object that listens. Now, FakeEventTarget
implements IReleasable, so that all listeners are removed when owners
call release().
For objects extending FakeEventTarget and also implementing
IDestroyable, the destroy() methods will call out to super.release()
to clean up listeners then. The owner should use destroy() in those
cases.
Issue #3949 (memory leak in DASH live streams with inband EventStream)
Previously, many events were being defined with a data dictionary
that used variable-type keys (e.g. {key: value}). This worked fine
in uncompiled mode, but in compiled mode it lead to those properties
being obfuscated.
This changes the FakeEvent constructor to take a map rather than an
object, so the compiler will force the keys to be strings.
Closes#3710
Change-Id: I67b1a391540a5ee21f0aaf940ae054d26f4c10a4
This adds two new player events, 'downloadheadersreceived' and
'downloadfailed', to allow users to measure network performance
in greater detail.
Issue #3533
Change-Id: I33a3bd411d815e926d4bea2184e8d3ea69e2bb49
An async process handles the appending of partial segments for LL-DASH. This fixes the caller to wait on the results, so that partial segments are always appended in order.
Fixes#3404
With the low latency streaming mode, we fetch a segment, and get the
response data through a ReadableStream.
For each segment request, we may get multiple chunked data. We handle
and append the chunked data of the ReadableStream via a callback
function in the StreamingEngine.
Once the whole segment gets handled and appended, we move on to the
next segment.
Issue #1525
Change-Id: I7949c87f4e491c928919c2e9dc4dafbebac22c9b
This fixes all the license headers in the main library, which corrects
the appearance of the main license in the compiled output.
It seems that the `!` in the header forces the compiler to keep it in
the output. I believe older compiler releases did this purely based
on `@license`.
Issue #2638
Change-Id: I7f0e918caad10c9af689c9d07672b7fe9be7b2f3
Since we are getting strict about semantic versioning, we can't remove
features in v3.1. Any backward compatibility we offer will be
maintained until v4.0.
The exception is explicit IE 11 support, which will still be removed
in v3.1.
To help us follow the rules for removal, the Deprecate utility no
longer accepts a minor version argument.
Change-Id: I4dd94a6084e4ed72eeec410eb9aa0ad974d8dac8
We have decided to bump the major version number instead of the minor
number, based primarily on the fact that this release breaks
compatibility with our previous manifest structure.
Change-Id: I67e4c8267c6e103cfc7278e09daac186ae5cbbc6
In many places, we check error codes on shaka.util.Error. But the
compiler doesn't know that what is caught in "catch" is that type, so
we add type assertions.
In some cases, we know that other types may also be thrown, so there
are also some runtime checks. Some of these had to be refactored to
allow the compiler to correctly infer types.
Change-Id: I053bd7e96213c689aae3889315052dd402124690
In many places, the implicit type info was insufficient. For example,
document.createElement returns Element, but the actual return is
always a subclass of Element. In many cases, we need the compiler to
know that a specific subclass is in use, so that it can correctly
check our use of subclass-specific properties. Another common pattern
is confusion between Node and Element (which is a subclass of Node).
Almost all of the changes in the demo and UI are Element-related.
In some places, we referred to HTMLMediaElement, used in the Player
API, instead of the more specific HTMLVideoElement in use in our demo.
Since the demo uses video-specific properties, we must use the more
specific type.
Another case is the use of document.createEvent, which returns Event
according to the compiler, but in reality always returns a subclass,
like CustomEvent.
In one case in NetworkingEngine, correcting the type of an
AbortableOperation led to the discovery that we had been incorrectly
accessing a private method of that type.
In goog.Uri, there were several instances of "*" for a type, which the
newer compiler won't accept. These have all been corrected.
Finally, in some places, we had the wrong nullability on a type.
These were all caught by a compiler upgrade.
Issue #2528
Change-Id: I7f2d070e3da32fe9ff5f444315649f3cbdb5a4a5
These classes were over-idented, making formatting more challenging.
I wanted to fix this before making compiler-upgrade-related changes in
these files.
Issue #2528
Change-Id: Ic44448760161a3e724d8c92f41f07c1a0babfa72
This changes the eslint rule to enforce a strict pattern for the
argument comments. The comment must appear before the argument and
must be /* foo= */. This still ignores line comments.
Change-Id: I3afb01c65e1088eda13facb3aeeaa7595a2f5aee
This reflects changes in Google's policy on JavaScript license
headers, which should be smaller to avoid increasing the size of the
binary unnecessarily.
This also updates the company name from "Google, Inc" to "Google LLC".
Change-Id: I3f8b9ed3700b6351f43173d50c94d35c333e82b4
According to RFC 3986, URL schemes should be case-insensitive. Our
scheme plugin map is registered with exclusively-lowercase scheme
names, so we should convert the input scheme to lowercase before
looking up the plugin.
Closes#2173
Change-Id: I78218c18d3df154aabd101a9ef5fd3156d0c57a8
Joey Parrish
Juan Manuel Gonzalez
Nick Michael
Álvaro Velad Galván
Wojciech Tyczyński
vlazh
Wojciech Tyczyński
theodab
Dave Nicholas
Casey Occhialini
Álvaro Velad Galván
Percy Tse
Vincent Valot
michellezhuo
Joey Parrish
Jacob Trimble