Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation: Advanced Features > DVB Font Downloading (#4390)
* Add initial text and assets for dvb-font-downloading exaplanation * Suggested changes to documentation * Clearer wording and diagram change * Apply suggestions from Nigel * Change version of imsc referenced * Page structure changes and suggestions from Daniel
- Loading branch information
1 parent
6fc50ef
commit 4348fc0
Showing
5 changed files
with
235 additions
and
7 deletions.
There are no files selected for viewing
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| <mxfile host="app.diagrams.net" modified="2024-02-19T17:05:54.109Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:122.0) Gecko/20100101 Firefox/122.0" etag="sAAOFV3IEYAv0A6jfb2J" version="23.1.4" type="device"> | ||
| <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1"> | ||
| <mxGraphModel dx="1434" dy="792" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="583" math="0" shadow="0"> | ||
| <root> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-0" /> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0" /> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-2" value="" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-3" target="RTdJWKshOJOjh0HueMQR-2" edge="1"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-3" value="Playback initiated" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="76.99" y="120" width="238.01" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-4" value="Yes" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-6" target="RTdJWKshOJOjh0HueMQR-6" edge="1"> | ||
| <mxGeometry x="-0.68" y="20" relative="1" as="geometry"> | ||
| <mxPoint as="offset" /> | ||
| <mxPoint x="155" y="460" as="targetPoint" /> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-5" value="No" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;entryX=1;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="WIyWlLk6GJQsqaUBKTNV-6" target="RTdJWKshOJOjh0HueMQR-2" edge="1"> | ||
| <mxGeometry x="-0.8206" y="13" relative="1" as="geometry"> | ||
| <mxPoint as="offset" /> | ||
| <mxPoint x="385" y="300" as="targetPoint" /> | ||
| <Array as="points"> | ||
| <mxPoint x="355" y="383" /> | ||
| <mxPoint x="355" y="240" /> | ||
| </Array> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="WIyWlLk6GJQsqaUBKTNV-6" value="<div>Has 'SubtitleDisplay' font <br>downloaded?<br></div>" style="rhombus;whiteSpace=wrap;html=1;shadow=0;fontFamily=Helvetica;fontSize=12;align=center;strokeWidth=1;spacing=6;spacingTop=-4;fillColor=#80FF00;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="75" y="313" width="240" height="140" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-0" value="<div>Supplemental</div><div>Property Descriptor<br></div>" style="text;strokeColor=none;fillColor=none;html=1;fontSize=24;fontStyle=1;verticalAlign=middle;align=center;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="135" y="20" width="100" height="40" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-1" value="<div>Essential</div><div>Property Descriptor<br></div>" style="text;strokeColor=none;fillColor=none;html=1;fontSize=24;fontStyle=1;verticalAlign=middle;align=center;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="495" y="30" width="230" height="20" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="RTdJWKshOJOjh0HueMQR-2" target="WIyWlLk6GJQsqaUBKTNV-6" edge="1"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <mxPoint x="149" y="230" as="targetPoint" /> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-2" value="TextTrack: 'showing'<br>Displayed with 'Arial'" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="75.93" y="210" width="239.07" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-6" value="TextTrack: 'showing'<br>Displayed with 'SubtitleDisplay'" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="74.99000000000001" y="502" width="239.07" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-7" value="" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="RTdJWKshOJOjh0HueMQR-8" target="RTdJWKshOJOjh0HueMQR-13" edge="1"> | ||
| <mxGeometry relative="1" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-8" value="Playback initiated" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="497" y="120" width="238.01" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-9" value="Yes" style="rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;edgeStyle=orthogonalEdgeStyle;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="RTdJWKshOJOjh0HueMQR-11" target="RTdJWKshOJOjh0HueMQR-15" edge="1"> | ||
| <mxGeometry x="-0.68" y="20" relative="1" as="geometry"> | ||
| <mxPoint as="offset" /> | ||
| <mxPoint x="575.01" y="460" as="targetPoint" /> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-10" value="No" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;jettySize=auto;orthogonalLoop=1;fontSize=11;endArrow=block;endFill=0;endSize=8;strokeWidth=1;shadow=0;labelBackgroundColor=none;entryX=1;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="RTdJWKshOJOjh0HueMQR-11" target="RTdJWKshOJOjh0HueMQR-13" edge="1"> | ||
| <mxGeometry x="-0.8206" y="13" relative="1" as="geometry"> | ||
| <mxPoint as="offset" /> | ||
| <mxPoint x="805.01" y="300" as="targetPoint" /> | ||
| <Array as="points"> | ||
| <mxPoint x="775.01" y="383" /> | ||
| <mxPoint x="775.01" y="240" /> | ||
| </Array> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-11" value="<div>Has 'SubtitleDisplay' font <br>downloaded?<br></div>" style="rhombus;whiteSpace=wrap;html=1;shadow=0;fontFamily=Helvetica;fontSize=12;align=center;strokeWidth=1;spacing=6;spacingTop=-4;fillColor=#80FF00;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="495.01" y="313" width="240" height="140" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="RTdJWKshOJOjh0HueMQR-13" target="RTdJWKshOJOjh0HueMQR-11" edge="1"> | ||
| <mxGeometry relative="1" as="geometry"> | ||
| <mxPoint x="569.01" y="230" as="targetPoint" /> | ||
| </mxGeometry> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-13" value="<div>TextTrack: 'disabled'</div><div>No text displayed<br></div>" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="495.94" y="210" width="239.07" height="60" as="geometry" /> | ||
| </mxCell> | ||
| <mxCell id="RTdJWKshOJOjh0HueMQR-15" value="TextTrack: 'showing'<br>Displayed with 'SubtitleDisplay'" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;fillColor=#99CCFF;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1"> | ||
| <mxGeometry x="495" y="502" width="239.07" height="60" as="geometry" /> | ||
| </mxCell> | ||
| </root> | ||
| </mxGraphModel> | ||
| </diagram> | ||
| </mxfile> |
136 changes: 136 additions & 0 deletions
136
pages/advanced/subtitles-and-captions/dvb-font-downloading.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| --- | ||
| layout: default | ||
| title: DVB Font Downloading | ||
| parent: Subtitles & Captions | ||
| grand_parent: Advanced Features | ||
| --- | ||
|
|
||
| <details markdown="block"> | ||
| <summary> | ||
| Table of contents | ||
| </summary> | ||
| {: .text-delta } | ||
| 1. TOC | ||
| {:toc} | ||
| </details> | ||
|
|
||
| # DVB Font Downloading | ||
|
|
||
| dash.js supports the mechanism described in the DVB DASH profile ([ETSI TS 103 285](https://www.etsi.org/deliver/etsi_ts/103200_103299/103285/01.03.01_60/ts_103285v010301p.pdf) Section 7.2 Downloadable Fonts) for signalling downloadable fonts using descriptors within an MPD. | ||
| This is intended for use with [EBU-TT-D](https://tech.ebu.ch/publications/tech3380) (compatible with [IMSC1](https://www.w3.org/TR/ttml-imsc1.0.1/) Text Profile) subtitles. | ||
| The key details of the mechanism and how to use it are covered here. | ||
|
|
||
| ## Usage | ||
|
|
||
| As a content provider, you may choose to specify fonts within your TTML subtitles that the subtitles should be rendered with. | ||
| This could be for accessibility, language, or stylistic reasons. | ||
| However this will only work if the specified fonts are available on the device or browser where the dash player is being used, which may not always be under the control of the content provider. | ||
|
|
||
| To assist with this, the DVB font download mechanism allows you to [signal font resources for download in an MPD](#signalling-downloadable-fonts), and associate them with specific font family names used within the TTML. | ||
| This is achieved by including Supplemental or Essential Property descriptors with the specified scheme in the MPD. | ||
|
|
||
| Reference media which signals fonts for download can be found in the [dash.js reference player](http://reference.dashif.org/dash.js/nightly/samples/dash-if-reference-player/). | ||
|
|
||
| This functionality is always available and does not need to be enabled through player settings. | ||
| If a downloadable font is correctly signalled, the download will be attempted. | ||
|
|
||
| ## Signalling Downloadable Fonts | ||
|
|
||
| Downloadable fonts are signalled in an MPD by using a `<SupplementalProperty>` descriptor, or a `<EssentialProperty>` descriptor, within an `<AdaptationSet>`. | ||
| The descriptor used must have a `schemeIdUri` attribute set to `"urn:dvb:dash:fontdownload:2014"` and a `value` attribute set to `"1"`. | ||
|
|
||
| ### DVB Attributes | ||
|
|
||
| Additional attributes are required on the descriptors to signal information about the downloadable font. | ||
|
|
||
| These attributes are defined in the DVB namespace `urn:dvb:dash-extensions:2014-1`. | ||
| Below gives an example of mapping the namespace to a `dvb:` prefix in an MPD. | ||
|
|
||
| ```xml | ||
| <MPD xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:dvb="urn:dvb:dash-extensions:2014-1"> | ||
| ``` | ||
|
|
||
| The table below details the attributes themselves. | ||
|
|
||
| | Name | Type | Description | | ||
| |:---------------- |:-------|:---------------------------------------------------------------------------------------| | ||
| | `dvb:url` | URI | The URL of the font to download. Can be absolute or can make use of relative BaseURLs. | | ||
| | `dvb:fontFamily` | String | The font family used in EBU-TT-D documents, within the [`tts:fontFamily`](https://www.w3.org/TR/ttml1/#style-attribute-fontFamily) style attribute. | | ||
| | `dvb:mimeType` | String | The mimeType of the font available from the URL. | | ||
|
|
||
| ### Property Descriptor Example | ||
|
|
||
| ```xml | ||
| <SupplementalProperty | ||
| schemeIdUri="urn:dvb:dash:fontdownload:2014" | ||
| value="1" | ||
| dvb:url="https://example.com/fonts/SubtitleDisplay.woff" | ||
| dvb:fontFamily="SubtitleDisplay" | ||
| dvb:mimeType="application/font-woff" | ||
| /> | ||
| ``` | ||
|
|
||
| ### Mimetype Support | ||
|
|
||
| The DVB DASH specification denotes support for two mimeTypes: | ||
|
|
||
| * `application/font-sfnt` - This covers `.ttf` and `.otf` fonts. | ||
| * `application/font-woff` - Covering `.woff` fonts. | ||
|
|
||
| No further support for unspecified mimeTypes has been provided. | ||
|
|
||
| ### Supplemental vs Essential Property Descriptors | ||
|
|
||
| SupplementalProperty descriptors are used when it is acceptable to show the subtitles in another font if the download fails. | ||
| EssentialProperty descriptors are used when the subtitles must not be shown at all if the download fails. | ||
|
|
||
| As such the player acts based on what kind of property descriptor was used to describe the downloadable font. | ||
| If a `<SupplementalProperty>` descriptor was used and download fails, then the `<AdaptationSet>` containing the descriptor continues to be presented as if the `<SupplementalProperty>` descriptor was not present. | ||
|
|
||
| If an `<EssentialProperty>` descriptor was used and download fails, then the `<AdaptationSet>` containing the descriptor is not be presented at all. | ||
|
|
||
| What this looks like on a client is [described in a later section](#download-process). | ||
|
|
||
| ## Using the Downloaded Fonts | ||
|
|
||
| ### TTML Font Family Attribute | ||
|
|
||
| The EBU-TT-D subtitles need to indicate that they want to use the downloaded font. | ||
| To do this, they must include the font family name within the comma-separated list of fonts in the [`tts:fontFamily`](https://www.w3.org/TR/ttml1/#style-attribute-fontFamily) attribute, and the name must match the value of the `dvb:fontFamily` attribute in the MPD. | ||
|
|
||
| So, for example, if we have this attribute in an MPD, | ||
|
|
||
| ```xml | ||
| <SupplementalProperty | ||
| dvb:fontFamily="SubtitleDisplay" | ||
| /> | ||
| ``` | ||
|
|
||
| we would need to ensure this is present in the subtitle TTML documents to put the font to use. | ||
|
|
||
| ```xml | ||
| <style | ||
| tts:fontFamily="SubtitleDisplay, Arial, default" | ||
| /> | ||
| ``` | ||
|
|
||
| Note that fallback fonts can still be specified. | ||
| In this case we have "Arial" specified as an expected system font, and "default" which is interpreted by [IMSC1](https://www.w3.org/TR/ttml-imsc1.0.1/) as the default monospace serif font provided by the browser/device in use. | ||
|
|
||
| ### Download Process | ||
|
|
||
| Download of fonts happens alongside other media, as to not impede the start of playback. | ||
| If the download is successful then the font is added to the `document` interface. | ||
| When the player is reset, or a new source is added, any added fonts are then removed from the `document`. | ||
|
|
||
| The download status of a font and the type of property descriptor used to describe the font have an effect on display of the `<AdaptationSet>` it is related to. | ||
| Consider a situation where subtitles are set to display on load, and we have the correct entries in our MPD and TTML documents to use our hypothetical 'SubtitleDisplay' font. | ||
| The process followed for the different property descriptors is described below. | ||
|
|
||
|  | ||
|
|
||
| For a `<SupplementalProperty>` descriptor, the displayed subtitles can appear in a 'fall-back' font before 'SubtitleDisplay' has been downloaded, in this case 'Arial'. | ||
| This causes, in effect, a flash of unstyled text ([FOUT](https://fonts.google.com/knowledge/glossary/fout)). | ||
| The subtitles, handled as a [TextTrack](https://developer.mozilla.org/en-US/docs/Web/API/TextTrack) can retain a [mode property](https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/mode) of `"showing"` throughout the process. | ||
|
|
||
| For an `<EssentialProperty>` descriptor, the subtitles will not appear unless the 'SubtitleDisplay' font downloads. Until this has downloaded, the mode property of the TextTrack handling these subtitles is set to `"disabled"`. This is done to best replicate what is expected by the DVB DASH specification, and also given there is no method to delete a TextTrack from a TextTrackList if the tracks are not linked to DOM elements. Once 'SubtitleDisplay' has downloaded the text track mode can be set to `"showing"`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| layout: default | ||
| title: Subtitles & Captions | ||
| parent: Advanced Features | ||
| has_children: true | ||
| --- | ||
|
|
||
| # Subtitles & Captions | ||
|
|
||
| dash.js has support for multiple subtitling and captioning formats including VTT captions, embedded CEA 608/708 captions, and TTML EBU timed text tracks. | ||
| Additionally, dash.js has a mechanism for consuming subtitle events so subtitles can be rendered separately, outside of dash.js. |
This file was deleted.
Oops, something went wrong.