Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating TOC section to reflect changes #112

Closed
wants to merge 6 commits into from
Closed

Updating TOC section to reflect changes #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5caec6e
correcting errata and adding changelog
wareid Jan 19, 2022
bf6cbc0
fixing change log
wareid Jan 19, 2022
9af7946
clarifying versioning in change log
wareid Jan 19, 2022
115b0f1
adding resolution to 110
wareid Feb 16, 2022
9d0b404
adding proposed correction text
wareid Feb 16, 2022
4f87254
updating TOC recommendation and adding note
wareid Feb 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions experiments/flatland.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,47 +30,47 @@
{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_1_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1371,
"duration": "PT1371S",
"name": "Part 1, Sections 1 - 3"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_2_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1669,
"duration": "PT1669S",
"name": "Part 1, Sections 4 - 5"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_3_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1506,
"duration": "PT1506S",
"name": "Part 1, Sections 6 - 7"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_4_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1669,
"duration": "PT1669S",
"name": "Part 1, Sections 8 - 10"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_5_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1506,
"duration": "PT1506S",
"name": "Part 1, Sections 11 - 12"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_6_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1798,
"duration": "PT1798S",
"name": "Part 2, Sections 13 - 14"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_7_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1225,
"duration": "PT1225S",
"name": "Part 2, Sections 15 - 17"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_8_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1371,
"duration": "PT1371S",
"name": "Part 2, Sections 18 - 20"
},{
"url": "http://www.archive.org/download/flatland_rg_librivox/flatland_9_abbott.mp3",
"encodingFormat": "audio/mpeg",
"duration": 1659,
"duration": "PT1659S",
"name": "Part 2, Sections 21 - 22"
}
]
Expand Down
57 changes: 26 additions & 31 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ <h3>Table of Contents</h3>
<p>If the table of contents is not located in the <a href="#audio-pep">primary entry page</a>, the
manifest SHOULD identify the resource that contains the structure.</p>

<p>When an Audiobook contains additional resources (i.e. supplemental content):</p>
<p>When an Audiobook contains audio resources that include multiple chapters or parts, or if the audiobook contains supplemental content:</p>

<ul>
<li>
Expand All @@ -150,6 +150,8 @@ <h3>Table of Contents</h3>
</li>
</ul>

<p class="note">Some Audiobooks may have audio resources that contain more than one chapter or section of the book content. It is strongly recommended that content creators provide a table of contents using <a href="https://www.w3.org/TR/media-frags/">media fragments</a> [[media-frags]] to provide the user with access to the structure of the Audiobook.</p>

<p class="note">When including supplemental content, be aware that users might not have access to this
content unless it is linked to from the table of contents. It is strongly advised to provide links
to all content that is not in the default reading order.</p>
Expand Down Expand Up @@ -442,9 +444,14 @@ <h4>Duration</h4>
Manifest</a> [[!pub-manifest]].</p>

<p>Duration SHOULD be expressed for the entirety of the audiobook as part of the manifest, and
SHOULD be present at the item level in the <a href="#audio-readingorder">default reading
MUST be present at the item level in the <a href="#audio-readingorder">default reading
order</a>.</p>

<div class="proposed correction">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have created a separate PR (#113) to handle these types of normative changes.

<span class="marker">Proposed Correction 1.1</span>
<p>We have updated the normative requirement for the duration property on the item level, to address implementer feedback in regards to facilitating streaming. This normative requirement is now a MUST.</p>
</div>

<p>When a content creator specifies both the duration for the audiobook and item-level duration in
the <a href="#audio-readingorder">default reading order</a> the resource-level duration SHOULD
be equal to the sum of the durations of the items in the reading order.</p>
Expand Down Expand Up @@ -479,15 +486,18 @@ <h3>Default Reading Order</h3>
><code>LinkedResource</code></a> [[!pub-manifest]]. The default reading order MUST NOT
contain non-audio resources.</p>

<p>An audio resource can be referenced in its entirety via a URL [[url]], or for content where multiple
chapters occupy a single file by using <a href="https://www.w3.org/TR/media-frags/">media
fragments</a> [[media-frags]] to locate the exact starting and end points.</p>
<p>An audio resource MUST be referenced in its entirety via a URL [[url]].</p>

<p class="note">It is important to note that a resource cannot be referenced more than once in the
reading order. In the case where an audio file represents the content of multiple chapters or
sections of the book, the <a href="#audio-toc">table of contents</a> can be used to specify the
sections of the book, the <a href="#audio-toc">table of contents</a> should be used to specify the
starting and ending points of those chapters in the larger audio file, as demonstrated in <a
href="#toc-mediafragments">this example</a>.</p>

<div class="proposed correction">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above, see #113

<span class="marker">Proposed Correction 1.1</span>
<p>Update previously non-normative statement about the use of media fragments to allow for referencing of audio files that span multiple chapters. The previous statement contradicted the note on referencing an audio file more than once in the reading order. The new normative statement will require that media fragments not be used on the <code>url</code> property in the Reading Order.</p>
</div>

<p class="note">Annotations can also use media fragments to identify the location of the annotation in
the resource, and are compatible with the <a href="https://www.w3.org/TR/annotation-model/">Web
Expand All @@ -509,29 +519,6 @@ <h3>Default Reading Order</h3>
}]
}
</pre>

<pre class="example" title="Audiobook Reading Order for Multiple Resources using Media Fragments">
{
"@context" : ["https://schema.org", "https://www.w3.org/ns/pub-context"],
"conformsTo" : "https://www.w3.org/TR/audiobooks/",
"url" : "https://publisher.example.org/janeeyre",
"name" : "Jane Eyre",
"readingOrder" : [{
"type": "LinkedResource",
"url" : "audio/part001.wav#t=0,457.931",
"encodingFormat" : "audio/vnd-wav",
"name" : "Chapter 1",
"duration" : "PT457.931S"
}, {
"type" : "LinkedResource",
"url" : "audio/part002.wav#t=12.741",
"encodingFormat" : "audio/vnd-wav",
"name" : "Chapter 2",
"duration" : "PT234.245S"
}]
}
</pre>

</section>

<section id="audio-resourcelist">
Expand Down Expand Up @@ -973,6 +960,14 @@ <h3>Audiobooks Accessibility</h3>
<section id="change-log">
<h2>Change Log</h2>

<p>Substantive changes since <a href="https://www.w3.org/TR/audiobooks">Recommendation</a> publication.</p>

<ul>
<li>16-Feb-2022: To address <a href="https://www.github.com/w3c/audiobooks/issues/110">issue 110</a>, media fragments can no longer be used in the <code>url</code> property in the Reading Order.</li>
<li>19-Jan-2022: Duration for items in the reading order is now a MUST, see <a href="https://www.github.com/w3c/audiobooks/issues/108">issue 108</a>.</li>
<li>19-Jan-2022: Corrected a syntax error in the <a href="#audio-simple">simple audiobook</a> sample file, see <a href="https://www.github.com/w3c/audiobooks/issues/109">issue 109</a>.</li>
</ul>

<p>Substantive changes since the <a href="https://www.w3.org/TR/2019/WD-audiobooks-20190620/">First Public
Working Draft</a>:</p>

Expand Down Expand Up @@ -1088,14 +1083,14 @@ <h3>Primary Entry Page with a Table of Contents</h3>
&lt;/head&gt;
&lt;body&gt;
&#8230;
&lt;section role="doc-toc"&gt;
&lt;nav role="doc-toc"&gt;
&lt;ol>
&lt;li>&lt;a href="audio/chapter001.wav">Chapter 1. There was no possibility of taking a walk that day...&lt;/a>&lt;/li>
&lt;li>&lt;a href="audio/chapter002.wav">Chapter 2. I resisted all the way:...&lt;/a>&lt;/li>
&lt;li>&lt;a href="audio/chapter003.wav">Chapter 3. The next thing I remember is,...&lt;/a>&lt;/li>
&#8230;
&lt;/ol>
&lt;/section&gt;
&lt;/nav&gt;
&#8230;
&lt;/body&gt;
</pre>
Expand Down