diff --git a/pages/features/index_features.md b/pages/features/index_features.md new file mode 100644 index 0000000000..2bfd649e26 --- /dev/null +++ b/pages/features/index_features.md @@ -0,0 +1,25 @@ +--- +layout: default +title: Feature Overview +--- + +# Feature Overview + +The work in dash.js is closely aligned with the work on +the [DASH Interoperability Points](https://dashif.org/guidelines/iop-v5/) and +the [DASH Live Simulator 2](https://github.com/Dash-Industry-Forum/livesim2) +in [DASH-IF](https://www.svta.org/working-group/dash-if/). + +| IOP Documentation | dash.js | LiveSim 2 | +|---------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| +| [Live2VoD](http://dashif.org/DASH-IF-IOP/live2vod) | Basic support | Supported | +| [L3D](http://dashif.org/DASH-IF-IOP/l3d) | Not supported | Not supported | +| [Content Steering](http://dashif.org/DASH-IF-IOP/content-steering) | Supported but needs some updates to be compliant with version 1.0.0. See also [here](../usage/content-steering.html) | Not supported | +| [MPD Patch](http://dashif.org/DASH-IF-IOP/mpd-patch) | Supported, see also [here](../usage/mpd-patching.html) | Supported | +| [CMCD](http://dashif.org/DASH-IF-IOP/cmcd) | Version 1 is implemented, Version 2 is in progress. See also [here](../usage/cmcd.html) | Not supported | +| [CMSD](https://docs.google.com/document/d/1CB1QJd_gz9km1lCr1HOdo1s_JZuACVtoy6yi6bE9Dfw/edit?usp=drive_link) | Implementation completed for two attributes `etp` and `mb` | Not supported | +| [Variable Substitution / DASH Annex I](https://docs.google.com/document/d/1rFvEMFsqz6FZk4ldSFRpnnIfxRkgWE7q1pqvJMJcjD0/edit?usp=drive_link) | Basic support, no support for templating mechanism | Not supported | +| [Server Guided Ad Insertion](https://docs.google.com/document/d/1JY6BXFj2YR9yNqqI6hyDq9_hc2BQ0E8LsDHhHhurWdw/edit?usp=sharing) | Not supported | Not supported | +| DRM / CPIX | Supported | Supports on the fly encryption for different DRMs | +| LC-EVC | Basic support | Not supported | + diff --git a/pages/usage/cmcd.md b/pages/usage/cmcd.md index 861a5ff408..cde72ba1d0 100644 --- a/pages/usage/cmcd.md +++ b/pages/usage/cmcd.md @@ -6,4 +6,54 @@ parent: Usage # Common Media Client Data -TBD +[CTA-5004 - Common Media Client Data](https://cdn.cta.tech/cta/media/media/resources/standards/pdfs/cta-5004-final.pdf) ( +CMCD) defines data +that is collected by the media player and is sent as a custom HTTP header or query parameter alongside each object +request to a CDN. This enables use cases such as log analysis, quality of service monitoring, prioritization of +requests, cross correlation of performance problems with specific devices and platforms and improved edge caching. + +CMCD version 1 is fully supported in dash.js. CMCD version 2 fields are gradually being added to dash.js. + +## Configuration Options + +dash.js offers various configuration options related to CMCD. The following settings can be configured: + +| Setting | Description | +|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| applyParametersFromMpd | Enable if dash.js should use the CMCD parameters defined in the MPD | +| enabled | Enable or disable the CMCD reporting. | +| sid | GUID identifying the current playback session.Should be defined in UUID format | +| cid | A unique string to identify the current content. If not specified it will be a hash of the MPD URL. | +| rtp | The requested maximum throughput that the client considers sufficient for delivery of the asset. If not specified this value will be dynamically calculated in the CMCDModel based on the current buffer level. | +| rtpSafetyFactor | This value is used as a factor for the rtp value calculation: rtp = minBandwidth * rtpSafetyFactor. If not specified this value defaults to 5. Note that this value is only used when no static rtp value is defined. | +| mode | The method to use to attach cmcd metrics to the requests. 'query' to use query parameters, 'header' to use http headers.If not specified this value defaults to 'query'. | +| enabledKeys | This value is used to specify the desired CMCD parameters. Parameters not included in this list are not reported. | +| includeInRequests | Specifies which HTTP GET requests shall carry parameters. If not specified this value defaults to ['segment', 'mpd]. | +| version | The version of the CMCD to use. If not specified this value defaults to 1. | + +For a full documentation of all CMCD related options please refer to +our [API documentation](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html#~CmcdSettings). + +Example configuration: + +````js +player.updateSettings({ + streaming: { + cmcd: { + applyParametersFromMpd: true, + enabled: false, + sid: null, + cid: null, + rtp: null, + rtpSafetyFactor: 5, + mode: 'query', + enabledKeys: ['br', 'd', 'ot', 'tb', 'bl', 'dl', 'mtp', 'nor', 'nrr', 'su', 'bs', 'rtp', 'cid', 'pr', 'sf', 'sid', 'st', 'v'], + includeInRequests: ['segment', 'mpd'], + version: 1 + } + }, +}) +```` + +## Example +An example illustrating CMCD reporting can be found in our dash.js [sample section](https://reference.dashif.org/dash.js/latest/samples/advanced/cmcd.html). diff --git a/pages/usage/custom-callback-functions.md b/pages/usage/custom-callback-functions.md deleted file mode 100644 index 26e17d99eb..0000000000 --- a/pages/usage/custom-callback-functions.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Custom callback functions -parent: Usage ---- - -# Custom callback functions diff --git a/pages/usage/live-streaming.md b/pages/usage/live-streaming.md new file mode 100644 index 0000000000..91c51a53b1 --- /dev/null +++ b/pages/usage/live-streaming.md @@ -0,0 +1,65 @@ +--- +layout: default +title: Live Streaming +parent: Usage +--- + +# Live Streaming + +## Setting the live delay + +In addition to the [buffer settings](buffer-management.html) the live delay plays a significant role in live +streaming. The live delay is the time difference between the live edge and the playback position. The live delay can be +set by the application in two ways: by setting the `liveDelay` or by setting the `liveDelayFragmentCount`. + +The `liveDelay` is the time in seconds that the player should be behind the live edge. The `liveDelayFragmentCount` is +the number of fragments that the +player should be behind the live edge. The `liveDelay` has precedence over the `liveDelayFragmentCount`. + +The`useSuggestedPresentationDelay` is a boolean that indicates whether the player should use the suggested presentation +delay from the MPD if defined. The suggested presentation delay is the time in seconds that the player should be behind +the live +edge. Explicit live delay settings by the appilication using the `liveDelay` and the `liveDelayFragmentCount` take +precedence over the `useSuggestedPresentationDelay`. + +### Configuration Options + +````js +player.updateSettings({ + streaming: { + delay: { + liveDelayFragmentCount: NaN, + liveDelay: NaN, + useSuggestedPresentationDelay: true + } + }, +}) +```` + +### Examples + +Multiple examples demonstrating the live delay settings can be found in +the [live section](https://reference.dashif.org/dash.js/nightly/samples/index.html#Live) of the dash.js sample page. + +## Synchronizing multiple players + +In some scenarios it makes sense to synchronize multiple players. This can be achieved by defining the same live delay +for all instances and enabling catchup mode. In the example configuration below the live delay is set to 10 seconds and +the live catchup mode is enabled. As a result both player instances will play roughly at the same position. + +````js +player.updateSettings({ + streaming: { + delay: { + liveDelay: 10 + }, + liveCatchup: { + enabled: true + } + }, +}) +```` + +An example illustrating how to synchronize multiple players is available in +the [live section](https://reference.dashif.org/dash.js/nightly/samples/live-streaming/synchronized-live-playback.html) +of the dash.js sample page. diff --git a/pages/usage/network-interceptor.md b/pages/usage/network-interceptor.md new file mode 100644 index 0000000000..f1424330db --- /dev/null +++ b/pages/usage/network-interceptor.md @@ -0,0 +1,64 @@ +--- +layout: default +title: Network Interceptor +parent: Usage +--- + +# Network Interceptor + +In some cases it might be necessary to modify the outgoing network requests or the incoming network response data. For +that +reason, dash.js provides a network interceptor API that allows applications to intercept and modify network requests and +responses. + +## Intercepting network requests + +To intercept network requests, the application must register a callback function that will be called before or after the +request is sent. The callback function must return a promise that resolves to the modified request object. The following +example demonstrates how to intercept network requests: + +````js + public init(): void { + this.player = dashjs.MediaPlayer().create() + this.player.initialize(document.querySelector('video') as HTMLMediaElement, this.mpd, true) + + /* Add request plugin to override request url for video segment requests only */ + this.addRequestInterceptor() + + /* Add response plugin to add response header */ + this.addResponseInterceptor() + + window.player = this.player + } + + private addRequestInterceptor() { + if (!this.player) { + return + } + const interceptor: RequestInterceptor = (request: CommonMediaRequest) => { + if (request.cmcd?.ot === CmcdObjectType.VIDEO) { + request.url += (request.url.includes('?') ? '&' : '?') + 'request-interceptor=true' + console.log(request.url) + } + return Promise.resolve(request) + } + this.player.addRequestInterceptor(interceptor) + } + + private addResponseInterceptor() { + if (!this.player) { + return + } + const interceptor: ResponseInterceptor = (response: CommonMediaResponse) => { + if (!response.headers) { + response.headers = {} + } + response.headers['response-interceptor'] = 'true' + return Promise.resolve(response) + } + this.player.addResponseInterceptor(interceptor) + } + } +```` + +A fully working example can be found in our [sample section](https://reference.dashif.org/dash.js/nightly/samples/advanced/network-interceptor.html). diff --git a/pages/usage/settings.md b/pages/usage/settings.md index d44c3de754..3d1c59b6aa 100644 --- a/pages/usage/settings.md +++ b/pages/usage/settings.md @@ -10,10 +10,16 @@ dash.js offers various configuration options that can be set to customize the pl in the player settings object after initializing the player. All settings are maintained in the `Settings.js` file and can easily be adjusted using the dash.js API. -An overview of all settings can be found in our [API documentation](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html). +An overview of all settings can be found in +our [API documentation](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html). ## Example -To update a specific setting use the `updateSettings` method of the player object. The example below shows how to change the log level: + +To update a specific setting use the `updateSettings` method of the player object. A more detailed example can be found +in +our [sample section](https://reference.dashif.org/dash.js/latest/samples/getting-started/manual-load-with-custom-settings.html). + +The example below shows how to change the log level: ````js player.updateSettings({