From cd6e900f35733c05728d93d4b91f02890eda2c03 Mon Sep 17 00:00:00 2001 From: Stephen Perrott <891sdp@gmail.com> Date: Mon, 19 Feb 2024 15:48:17 +0000 Subject: [PATCH] Suggested changes to documentation --- pages/advanced/dvb-font-downloading.md | 60 ++++++++++++++------------ 1 file changed, 32 insertions(+), 28 deletions(-) diff --git a/pages/advanced/dvb-font-downloading.md b/pages/advanced/dvb-font-downloading.md index 87fc84adcd..f611296472 100644 --- a/pages/advanced/dvb-font-downloading.md +++ b/pages/advanced/dvb-font-downloading.md @@ -15,28 +15,38 @@ parent: Advanced Features # DVB Font Downloading -Dash.js supports the mechanism described in the DVB DASH specification (ETSI TS 103 285 Section 7.2 Downloadable Fonts) for signalling downloadable fonts using descriptors within an MPD. -This is intended for use with EBU-TT-D subtitles. The key details of the mechanism and how to use it are covered here. +Dash.js supports the mechanism described in the DVB DASH profile (ETSI TS 103 285 Section 7.2 Downloadable Fonts) for signalling downloadable fonts using descriptors within an MPD. +This is intended for use with EBU-TT-D (compatible with IMSC1 text) subtitles. The key details of the mechanism and how to use it are covered here. ## Usage -As a content provider, you may want to specify a font for your TTML subtitles carried with your content to be displayed with. -This may be for accessibility, or language reasons. -It's possible that you may have no control over the webpage or device where the dash player used to play your content is used. -Therefore, it wont be possible to specify separate styling or initiate a font download on the webpage or device. +As a content provider, you may choose to specify the font within your TTML subtitles that they should be rendered using. This could be for accessibility, language, or stylistic reasons. However this will only work if the specified font is available on the device or browser where the dash player is being used, which may not always be under content provider control. -To combat this, it is possible to signal a font for download in an MPD. This is done by signalling it using additional DVB attributes in an MPD. +To assist with this, the DVB font download mechanism allows you to signal a font for download in an MPD. This is acheived by including Supplemental or Essential Properties with the specified scheme in the MPD. -Reference media with signalled fonts for download can be found in the [dash.js reference player](http://reference.dashif.org/dash.js/nightly/samples/dash-if-reference-player/). +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/). -_N.B. If a downloadable font is correctly signalled, a download will be attempted. This functionality is not required to be enabled through player settings._ +This functionality is always available - it 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 can be signalled in an MPD by using a `` descriptor, or a `` descriptor, within an ``. +Downloadable fonts are signalled in an MPD by using a `` descriptor, or a `` descriptor, within an ``. 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, defined in the DVB namespace `urn:dvb:dash-extensions:2014-1` (assumed here to be mapped to the dvb:prefix in the xml document), are required on the descriptors to signal information about the downloadable font. + +| 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. | +| `dvb:mimeType` | String | The mimeType of the font available from the URL. | + +### Example + ```xml + ``` -### DVB Attributes -Additional DVB attributes are required to signal information about the downloadable font. - -| 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. | -| `dvb:mimeType` | String | The mimeType of the font available from the URL. | ### Mimetype Support @@ -67,10 +69,12 @@ No further support for unspecified mimeTypes has been provided. ### Supplemental vs Essential Property Descriptors -If it is not possible to download a font, then the player needs to act based on what kind of property descriptor was used to describe the downloadable font. -If a `` descriptor was used and download fails, then the `` containing the descriptor should be presented as if the `` descriptor was not present. +SupplementalProperty descriptors are used when it is acceptable to show the subtitles in another font if the download fails (or if a dash player doesn't support the mechanism at all). 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 `` descriptor was used and download fails, then the `` containing the descriptor continues to be presented as if the `` descriptor was not present. -If an `` descriptor was used and download fails, then the `` containing the descriptor should not be presented at all. +If an `` descriptor was used and download fails, then the `` containing the descriptor is not be presented at all. What this looks like on a client is described in a later section. @@ -78,9 +82,9 @@ What this looks like on a client is described in a later section. ### TTML Font Family Attribute -The EBU-TT-D subtitles need to indicate that they want to use a downloaded font. To do this, they must use the same `fontFamily` name as described by the `dvb:fontFamily` attribute in an MPD. +The EBU-TT-D subtitles need to indicate that they want to use the downloaded font. To do this, they must use the same `fontFamily` name as described by the `dvb:fontFamily` attribute in the MPD. -So, for example, if we had this attribute in an MPD, +So, for example, if we have this attribute in an MPD, ```xml ``` -we would need to ensure this was present in the subtitle TTML documents to put the font to use. +we would need to ensure this is present in the subtitle TTML documents to put the font to use. ```xml