Skip to content

Commit 4078910

Browse files
author
terrill
committed
Make 'video' default format for description, if both methods are available
- Remove Preferred Format option from user Description Preferences dialog - If descriptions are available both as 'video' and text', always use video (based on our user studies, users almost unanimously prefer built-in professionally mixed descriptions over text-based using WebVTT, if both are available). - If "Pause video during description" preference is checked, only do this if description is delivered as text, not video - If "Make description visible is checked", always show it if a WebVTT description is available, even if the audio description itself is delivered via video - If delivering description via video, do not expose description text for audible rendering
1 parent 246f659 commit 4078910

18 files changed

Lines changed: 136 additions & 363 deletions

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,16 @@ controller.
360360
If descriptions are available using either of the above methods, a
361361
Description toggle button appears on the controller (represented by the
362362
universal Description symbol, the letter "D"). How descriptions are
363-
ultimately delivered depends on which of the above methods is used, and
363+
ultimately delivered depends on which of the above methods is used.
364+
365+
If *both* methods are used, description will be delivered using the separate
366+
described version of the video. However, the WebVTT file will be used to
367+
(a) display the description text visibly (if users have selected this option in their
368+
preferences), and (b) incorporate the description text into the
369+
auto-generated interactive transcript. Therefore, it is important for the
370+
WebVTT description file to be accurately synchronized with the separate
371+
described version of the video.
372+
364373
on user preference. If a user prefers text-based description announced
365374
by their screen reader, that’s what they’ll get. If they prefer an
366375
alternate video with description mixed in, that’s what they’ll get. See
@@ -373,6 +382,7 @@ HTML overlays; text-based description could be used in this context to provide
373382
additional instructions for screen reader users). In such cases the Descriptions
374383
button can be eliminated from the controller with **data-use-descriptions-button="false"**.
375384

385+
376386
#### Sign language
377387

378388
Sign language translation is supported in a separate video player,

‎build/ableplayer.dist.js‎

Lines changed: 37 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1565,7 +1565,7 @@
15651565
});
15661566
prefs.push({
15671567
'name': 'prefDescFormat', // audio description default state
1568-
'label': this.tt.prefDescFormat,
1568+
'label': null,
15691569
'group': 'descriptions',
15701570
'default': 'video'
15711571
});
@@ -1624,7 +1624,7 @@
16241624
var available, thisObj, $prefsDiv, formTitle, introText,
16251625
$prefsIntro,$prefsIntroP2,p3Text,$prefsIntroP3,i, j,
16261626
$fieldset, fieldsetClass, fieldsetId,
1627-
$descFieldset1, $descLegend1, $descFieldset2, $descLegend2, $legend,
1627+
$descFieldset, $descLegend, $legend,
16281628
thisPref, $thisDiv, thisClass, thisId, $thisLabel, $thisField,
16291629
$div1,id1,$radio1,$label1,
16301630
$div2,id2,$radio2,$label2,
@@ -1722,35 +1722,17 @@
17221722
$prefsDiv.append($prefsIntro);
17231723
}
17241724

1725-
if (form === 'descriptions') {
1726-
// descriptions form has two field sets
1727-
1728-
// Fieldset 1
1729-
$descFieldset1 = $('<fieldset>');
1730-
fieldsetClass = 'able-prefs-' + form + '1';
1731-
fieldsetId = this.mediaId + '-prefs-' + form + '1';
1732-
$descFieldset1.addClass(fieldsetClass).attr('id',fieldsetId);
1733-
$descLegend1 = $('<legend>' + this.tt.prefDescFormat + '</legend>');
1734-
$descFieldset1.append($descLegend1);
1735-
1736-
// Fieldset 2
1737-
$descFieldset2 = $('<fieldset>');
1738-
fieldsetClass = 'able-prefs-' + form + '2';
1739-
fieldsetId = this.mediaId + '-prefs-' + form + '2';
1740-
$descFieldset2.addClass(fieldsetClass).attr('id',fieldsetId);
1741-
$descLegend2 = $('<legend>' + this.tt.prefHeadingTextDescription + '</legend>');
1742-
$descFieldset2.append($descLegend2);
1725+
$fieldset = $('<fieldset>');
1726+
fieldsetClass = 'able-prefs-' + form;
1727+
fieldsetId = this.mediaId + '-prefs-' + form;
1728+
$fieldset.addClass(fieldsetClass).attr('id',fieldsetId);
1729+
if (form === 'keyboard') {
1730+
$legend = $('<legend>' + this.tt.prefHeadingKeyboard1 + '</legend>');
1731+
$fieldset.append($legend);
17431732
}
1744-
else {
1745-
// all other forms just have one fieldset
1746-
$fieldset = $('<fieldset>');
1747-
fieldsetClass = 'able-prefs-' + form;
1748-
fieldsetId = this.mediaId + '-prefs-' + form;
1749-
$fieldset.addClass(fieldsetClass).attr('id',fieldsetId);
1750-
if (form === 'keyboard') {
1751-
$legend = $('<legend>' + this.tt.prefHeadingKeyboard1 + '</legend>');
1752-
$fieldset.append($legend);
1753-
}
1733+
else if (form === 'descriptions') {
1734+
$legend = $('<legend>' + this.tt.prefHeadingTextDescription + '</legend>');
1735+
$fieldset.append($legend);
17541736
}
17551737
for (i=0; i<available.length; i++) {
17561738

@@ -1760,48 +1742,9 @@
17601742
thisPref = available[i]['name'];
17611743
thisClass = 'able-' + thisPref;
17621744
thisId = this.mediaId + '_' + thisPref;
1763-
if (thisPref !== 'prefDescFormat') {
1764-
$thisDiv = $('<div>').addClass(thisClass);
1765-
}
1745+
$thisDiv = $('<div>').addClass(thisClass);
17661746

1767-
// Audio Description preferred format radio buttons
1768-
if (thisPref == 'prefDescFormat') {
1769-
1770-
// option 1 radio button
1771-
$div1 = $('<div>');
1772-
id1 = thisId + '_1';
1773-
$label1 = $('<label>')
1774-
.attr('for',id1)
1775-
.text(this.capitalizeFirstLetter(this.tt.prefDescFormatOption1))
1776-
$radio1 = $('<input>',{
1777-
type: 'radio',
1778-
name: thisPref,
1779-
id: id1,
1780-
value: 'video'
1781-
});
1782-
if (this.prefDescFormat === 'video') {
1783-
$radio1.prop('checked',true);
1784-
};
1785-
$div1.append($radio1,$label1);
1786-
1787-
// option 2 radio button
1788-
$div2 = $('<div>');
1789-
id2 = thisId + '_2';
1790-
$label2 = $('<label>')
1791-
.attr('for',id2)
1792-
.text(this.capitalizeFirstLetter(this.tt.prefDescFormatOption2));
1793-
$radio2 = $('<input>',{
1794-
type: 'radio',
1795-
name: thisPref,
1796-
id: id2,
1797-
value: 'text'
1798-
});
1799-
if (this.prefDescFormat === 'text') {
1800-
$radio2.prop('checked',true);
1801-
};
1802-
$div2.append($radio2,$label2);
1803-
}
1804-
else if (form === 'captions') {
1747+
if (form === 'captions') {
18051748
$thisLabel = $('<label for="' + thisId + '"> ' + available[i]['label'] + '</label>');
18061749
$thisField = $('<select>',{
18071750
name: thisPref,
@@ -1893,25 +1836,11 @@
18931836
}
18941837
$thisDiv.append($thisField,$thisLabel);
18951838
}
1896-
if (form === 'descriptions') {
1897-
if (thisPref === 'prefDescFormat') {
1898-
$descFieldset1.append($div1,$div2);
1899-
}
1900-
else {
1901-
$descFieldset2.append($thisDiv);
1902-
}
1903-
}
1904-
else {
1905-
$fieldset.append($thisDiv);
1906-
}
1839+
$fieldset.append($thisDiv);
19071840
}
19081841
}
1909-
if (form === 'descriptions') {
1910-
$prefsDiv.append($descFieldset1,$descFieldset2);
1911-
}
1912-
else {
1913-
$prefsDiv.append($fieldset);
1914-
}
1842+
$prefsDiv.append($fieldset);
1843+
19151844
if (form === 'captions') {
19161845
// add a sample closed caption div to prefs dialog
19171846
if (this.mediaType === 'video') {
@@ -2098,15 +2027,7 @@
20982027
available = this.getAvailablePreferences();
20992028
for (i=0; i<available.length; i++) {
21002029
prefName = available[i]['name'];
2101-
if (prefName === 'prefDescFormat') {
2102-
if (this[prefName] === 'text') {
2103-
$('input[value="text"]').prop('checked',true);
2104-
}
2105-
else {
2106-
$('input[value="video"]').prop('checked',true);
2107-
}
2108-
}
2109-
else if ((prefName.indexOf('Captions') !== -1) && (prefName !== 'prefCaptions')) {
2030+
if ((prefName.indexOf('Captions') !== -1) && (prefName !== 'prefCaptions')) {
21102031
// this is a caption-related select box
21112032
$('select[name="' + prefName + '"]').val(cookie.preferences[prefName]);
21122033
}
@@ -2139,8 +2060,10 @@
21392060
if (available[i]['label']) {
21402061
var prefName = available[i]['name'];
21412062
if (prefName == 'prefDescFormat') {
2142-
this.prefDescFormat = $('input[name="' + prefName + '"]:checked').val();
2143-
if (this.prefDescFormat !== cookie.preferences['prefDescFormat']) { // user changed setting
2063+
// As of v4.0.10, prefDescFormat is no longer a choice
2064+
// this.prefDescFormat = $('input[name="' + prefName + '"]:checked').val();
2065+
this.prefDescFormat = 'video';
2066+
if (this.prefDescFormat !== cookie.preferences['prefDescFormat']) { // user's preference has changed
21442067
cookie.preferences['prefDescFormat'] = this.prefDescFormat;
21452068
numChanges++;
21462069
}
@@ -7117,7 +7040,7 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
71177040

71187041
// The following variables are applicable to delivery of description:
71197042
// prefDesc == 1 if user wants description (i.e., Description button is on); else 0
7120-
// prefDescFormat == either 'video' or 'text'
7043+
// prefDescFormat == either 'video' or 'text' (as of v4.0.10, prefDescFormat is always 'video')
71217044
// prefDescPause == 1 to pause video when description starts; else 0
71227045
// prefVisibleDesc == 1 to visibly show text-based description area; else 0
71237046
// hasOpenDesc == true if a described version of video is available via data-desc-src attribute
@@ -7126,8 +7049,10 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
71267049
// descOn == true if description of either type is on
71277050

71287051
var thisObj = this;
7129-
7130-
if (!this.refreshingDesc) {
7052+
if (this.refreshingDesc) {
7053+
this.prevDescFormat = this.useDescFormat;
7054+
}
7055+
else {
71317056
// this is the initial build
71327057
// first, check to see if there's an open-described version of this video
71337058
// checks only the first source since if a described version is provided,
@@ -7151,9 +7076,11 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
71517076
// update this.useDescFormat based on media availability & user preferences
71527077
if (this.prefDesc) {
71537078
if (this.hasOpenDesc && this.hasClosedDesc) {
7154-
// both formats are available. Use whichever one user prefers
7079+
// both formats are available. Always use 'video'
71557080
this.useDescFormat = this.prefDescFormat;
71567081
this.descOn = true;
7082+
// Do not pause during descriptions when playing described video
7083+
this.prefDescPause = false;
71577084
}
71587085
else if (this.hasOpenDesc) {
71597086
this.useDescFormat = 'video';
@@ -7167,9 +7094,6 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
71677094
else { // description button is off
71687095
this.useDescFormat = false;
71697096
this.descOn = false;
7170-
if (this.refreshingDesc) { // user just now toggled it off
7171-
this.prevDescFormat = this.useDescFormat;
7172-
}
71737097
}
71747098

71757099
if (this.useDescFormat === 'text') {
@@ -7201,22 +7125,21 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
72017125
}
72027126
}
72037127
if (this.descOn) {
7204-
72057128
if (this.useDescFormat === 'video') {
72067129
if (!this.usingAudioDescription()) {
72077130
// switched from non-described to described version
72087131
this.swapDescription();
72097132
}
7210-
// hide description div
7211-
this.$descDiv.hide();
7212-
this.$descDiv.removeClass('able-clipped');
72137133
}
7214-
else if (this.useDescFormat === 'text') {
7215-
this.$descDiv.show();
7216-
if (this.prefVisibleDesc) { // make it visible to everyone
7134+
if (this.hasClosedDesc) {
7135+
if (this.prefVisibleDesc) {
7136+
// make description text visible
7137+
// New in v4.0.10: Do this regardless of useDescFormat
7138+
this.$descDiv.show();
72177139
this.$descDiv.removeClass('able-clipped');
72187140
}
7219-
else { // keep it visible to screen readers, but hide from everyone else
7141+
else {
7142+
// keep it visible to screen readers, but hide it visibly
72207143
this.$descDiv.addClass('able-clipped');
72217144
}
72227145
if (!this.swappingSrc) {
@@ -7225,7 +7148,6 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
72257148
}
72267149
}
72277150
else { // description is off.
7228-
72297151
if (this.prevDescFormat === 'video') { // user was previously using description via video
72307152
if (this.usingAudioDescription()) {
72317153
this.swapDescription();
@@ -7255,7 +7177,6 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
72557177
};
72567178

72577179
AblePlayer.prototype.swapDescription = function() {
7258-
72597180
// swap described and non-described source media, depending on which is playing
72607181
// this function is only called in two circumstances:
72617182
// 1. Swapping to described version when initializing player (based on user prefs & availability)

0 commit comments

Comments
 (0)