17 |
--------------------------------------------------------------------------------
/specs/authoring/authoring.md:
--------------------------------------------------------------------------------
1 | # Purpose # {#purpose}
2 |
3 | This document outlines the methodology and tools utilized in the authoring
4 | process for the
5 | [DASH-IF IOP repository](https://github.com/dash-Industry-Forum/DASH-IF-IOP).
6 |
7 | To streamline and enhance the creation of our documents, we employ a suite of
8 | open source tools and packages. These tools are integral to our workflow,
9 | enabling us to produce high-quality, well-structured, and visually engaging
10 | documents. Below is an overview of the tools we use:
11 |
12 | * [Bikeshed](https://speced.github.io/bikeshed/) is our primary tool for
13 | drafting and maintaining the core text and documents. It offers robust
14 | features for creating comprehensive specifications, including syntax
15 | highlighting, automatic cross-references, and customizable formatting.
16 | * [Mermaid](https://mermaid.js.org/) is employed for diagramming within our
17 | documents. This tool allows us to visualize complex information, workflows,
18 | and relationships through a variety of diagram types, such as flowcharts,
19 | sequence diagrams, and class diagrams. The integration of Mermaid enhances
20 | the readability and comprehension of our documentation, making intricate
21 | concepts more accessible to our audience. Mermaid is also supported by GitHub
22 | markdown rendering directly.
23 | * [PlantUML](https://plantuml.com/) is another tool that will be part of the
24 | stack and allow us to create visualizations.
25 |
26 | Issue: Implement support for PlantUML
27 | * [Docker](https://www.docker.com/) is utilized to run the builds and create
28 | the resulting documents. By leveraging Docker, we achieve a consistent and
29 | reproducible environment for our documentation pipeline. This ensures that
30 | our build process is reliable and that the final documents are generated
31 | accurately every time.
32 |
33 | # Local Editing Setup # {#local-setup}
34 |
35 | The primary idea is to wrap to make editing of content easy within a GitHub Pull
36 | Request based workflow. This means that all the primary text is written as
37 | markdown. In addition to this, we process the resulting documents with various
38 | tools. The entire build pipeline is exposed as a single
39 | [Docker](https://www.docker.com/) Container that is publicly available and can
40 | be fetched and updated on demand.
41 |
42 | With the above in mind, what you need to do to get started including checking
43 | your edits locally is to:
44 |
45 | * Install Docker
46 | * [Windows Instructions](https://docs.docker.com/desktop/install/windows-install/)
47 | * [Mac OS Instructions](https://docs.docker.com/desktop/install/mac-install/)
48 | * [Linux Instructions](https://docs.docker.com/desktop/install/linux-install/)
49 | * Open the files to edit with your text editor of choice.
50 | [Visual Studio Code](https://code.visualstudio.com/) is a good choice for
51 | markdown editing, but there are a lot of other editors available for that
52 | purpose.
53 | * Clone [the repository](https://github.com/Dash-Industry-Forum/DASH-IF-IOP)
54 | repository, i.e. `git clone git@github.com:Dash-Industry-Forum/DASH-IF-IOP.git`
55 | * Change to the cloned folder and build things locally:
56 | * `./build.sh` on Mac or Linux
57 | * `build.bat` on Windows
58 |
59 | You might notice that the first build run will take a moment since the
60 | respective container needs to be downloaded. Subsequent runs will be faster after
61 | that initial bootstrap.
62 |
63 | With the above command, _all_ the documents will be generated and you find the
64 | results in the `dist` folder.
65 |
66 | When you are working on a specific document, you can also use the following
67 | commands. For example for `authoring`:
68 |
69 | * `./build.sh authoring` will build only the authoring related artifacts
70 | * `./build.sh authoring.html` will build the html version
71 | * `./build.sh authoring.pdf` will build the pdf version
72 | * `./build.sh authoring-watch` will build the html version and start watching
73 | the related documents for changes. If a change is detected, i.e. you edit one
74 | of the included markdown files and save, the page is re-generated. Reload the
75 | browser page and you will see the updated version. This process will keep on\
76 | running until you terminate it with `Ctrl-C`.
77 |
78 | # Remote Editing Setup # {#remote-editing}
79 |
80 | To quickly edit text in a GitHub repository, you can use the [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor)
81 | browser-based editor. Simply press `.` while viewing the repository to open the
82 | editor in your browser. This will launch a lightweight version of VSCode where
83 | you can edit files, create branches, commit changes, and open pull requests
84 | directly from the browser.
85 |
86 | However, note that this method doesn’t allow you to preview rendered HTML since
87 | the environment doesn’t support running builds.
88 |
89 | If you need to edit documents and preview them, you can use GitHub Codespaces,
90 | which provides a full development environment in the cloud. While not entirely
91 | free, GitHub offers a monthly quota of free minutes for Codespaces usage.
92 |
93 | Once your Codespaces is set up, you can run the build using the `build.sh`
94 | script located in the root folder. To preview the generated HTML, install the
95 | "Live Preview" extension by Microsoft. After running the build, expand the
96 | `dist` folder, right-click on one of the generated HTML files, and select
97 | "Show Preview." This will launch an internal server and allow you to view the
98 | results in a browser window.
99 |
100 | The key advantage of using Codespaces is that it simulates a local development
101 | environment without needing to install any tools on your machine. However, be
102 | mindful that Codespaces usage may incur costs after your free minutes are
103 | exhausted, and it requires working within VSCode.
104 |
105 | # Creating and Editing a Document # {#editing}
106 |
107 | As described in [[#structure]], you will find individual documents in folders
108 | inside the `specs` folder, for instance `specs/authoring` for this document.
109 |
110 | A document consists of exactly one `.bs` bikeshed file and can have many
111 | additional markdown (`.md`) files that are included in the bikeshed document.
112 | For example, this document is primarily written in `authoring.md`. The
113 | corresponding `authoring.bs` bikeshed document contains additional meta-data and
114 | includes of other files. For example:
115 |
116 | ```
117 |
133 | ```
134 |
135 | Note how the `authoring.md` file is included at the bottom. If your document
136 | consists of multiple markdown files, you have to add multiple includes in the
137 | bikeshed document.
138 |
139 | Besides this, the file **must** contain the `
` section.
140 | This is where surrounding document meta-data go including the Title, the Status,
141 | URLs. etc. There are more details on the meta-data keys that are available
142 | in the [Bikeshed Documentation](https://speced.github.io/bikeshed/#metadata).
143 |
144 | The following keys are mandatory for our documents to be rendered correctly:
145 |
146 | * `Group: dashif` -- We have custom boilerplate for the `dashif` group that is
147 | part of the tooling and identified by the group name.
148 |
149 |
150 | # Folder Structure # {#structure}
151 |
152 | The repository is organized in the following way. Note that the folder structure
153 | is important for some of the tooling to work as expected.
154 |
155 | - `specs` This folder contains sub-folders, one for each document that is
156 | managed and maintained as part of this repository.
157 | - `build-tools` This folder container the build tools and describes the Docker
158 | container that we use.
159 | - `data` This folder contains boilerplate data that is used by all documented.
160 | For example, the common header or the logo snippet.
161 | - `dist` This folder is explicitly excluded from the git repository but this is
162 | where all the output of a build will be written to.
163 | - `biblio.json` is a JSON file with custom [SpecRef](https://www.specref.org/)
164 | references. Note that is is much better to submit a missing ref to SpecRef
165 | instead of using custom references.
166 |
167 | Any spec document folder should contain the following files or folders.
168 |
169 | - A `.bs` file that is the actual Bikeshed file and will be used as an entry
170 | point. Note that there should be only one `.bs` file in each specs sub-folder.
171 | - Any number of additional `*.md` files. Note that these files are not processed
172 | by default, but can be [included](#editing) in a bikeshed source.
173 | - `Images` folder. This folder will be copied as is to the resulting document
174 | structure. Add any images that you want to include here.
175 | - `Diagrams` folder. Files in this folder will be pushed through `plantuml` to
176 | generate images that in turn can be included in the document.
177 |
178 |
179 | # Document Editing # {#elements}
180 |
181 | We are using [Bikeshed](https://speced.github.io/bikeshed/) to write documents.
182 | Bikeshed supports a subset of common markdown as well as html tags in the same
183 | document.
184 |
185 | In addition we included a few other tools that can be used to write content.
186 | This section describes some of the Bikeshed features that we rely on, some
187 | details around the markdown flavor that is used by Bikeshed, as well as the
188 | usage of the additional tools that are integrated into our editing and
189 | publishing pipeline.
190 |
191 | ## Markdown Basics ## {#markdown}
192 |
193 | Please refer to the
194 | [Bikeshed documentation on markdown](https://speced.github.io/bikeshed/) for
195 | more details.
196 |
197 | Here we just describe the fundamentals that are supported.
198 |
199 | * `**Bold**` becomes **Bold**
200 | * `*Italic*` becomes *Italic*
201 | * `#`, `##`, `###` etc create headings. There are more details around headings
202 | in [[#headings]].
203 |
204 | Surrounding a word with \` or \~ will create inline code, i.e. ``` `code` ```
205 | becomes `code`. You can also use triple \` or \~ to create a code block, i.e.
206 |
207 | ~~~
208 | ```
209 | This is a code block
210 | ```
211 | ~~~
212 |
213 | becomes
214 |
215 | ```
216 | This is a code block
217 | ```
218 |
219 | By default we render the content of code blocks as text. However, if you know
220 | the language, you can create highlighted code by naming the language after
221 | the triple \`. For example
222 |
223 | ~~~
224 | ```xml
225 |
230 | ...
231 |
232 | ```
233 | ~~~
234 |
235 | will render highlighted xml:
236 |
237 | ```xml
238 |
243 | ...
244 |
245 | ```
246 |
247 | `*` or `-` is used to create unordered lists potentially with sub-items. For
248 | example:
249 |
250 | ```
251 | * This is one item
252 | * This is another item
253 | * With a sub item
254 | ```
255 |
256 | is rendered as
257 |
258 | * This is one item
259 | * This is another item
260 | * With a sub item
261 |
262 | You can use `---` to create a horizontal rule. For example
263 |
264 | ---
265 |
266 | Markdown syntax for links is `[name](link)`, for example
267 | `[Bikeshed](https://speced.github.io/bikeshed)` becomes
268 | [Bikeshed](https://speced.github.io/bikeshed).
269 |
270 | ## Highlighting notes ## {#notes}
271 |
272 | Paragraphs starting with `Note: ` and `Advisement: ` will be highlighted in the
273 | output document. Notes are considered informative, whereas advisements are
274 | normative.
275 |
276 | ```
277 | Note:
278 |
279 | Advisement: Bee stings hurt!
280 | ```
281 |
282 | For example
283 |
284 | ```
285 | Note: Bees can fly up to two miles to find nectar and pollen.
286 | ```
287 |
288 | becomes
289 |
290 | Note: Bees can fly up to two miles to find nectar and pollen.
291 |
292 | and
293 |
294 | ```
295 | Advisement: Bee stings hurt!
296 | ```
297 |
298 | becomes
299 |
300 | Advisement: Bee stings hurt!
301 |
302 | You can also use html elements and css classes to create these blocks. This is
303 | useful if you want to write more extended notes that span multiple paragraphs
304 | or contain images.
305 |
306 | ```
307 |
308 | This is a note that can be longer. In here I can use markdown **like this**.
309 |
310 | And we can also write multiple paragraphs here.
311 |
312 | ```
313 |
314 | becomes
315 |
316 |
317 | This is a note that can be longer. In here I can use markdown **like this**.
318 |
319 | And we can also write multiple paragraphs here.
320 |
321 |
322 | ## Issues ## {#issues}
323 |
324 | Bikeshed supports inline issues by starting a paragraph with `Issue:`. For
325 | example
326 |
327 | ```
328 | Issue: Maybe we need details on issues
329 | ```
330 |
331 | becomes
332 |
333 | Issue: Maybe we need details on issues
334 |
335 | ## Examples ## {#examples}
336 |
337 | You have to use HTML to create examples, for instance
338 |
339 | ```html
340 |
341 | This is an example.
342 |
343 | ```
344 |
345 | becomes
346 |
347 |
348 | This is an example.
349 |
350 |
351 | ## Headings and references ## {#headings}
352 |
353 | To uniquely identify a heading for referencing purposes, you must explicitly add
354 | an anchor. The anchor is the `{#xyz}` tag at the end of the heading. For this,
355 | the heading needs to end with the same number of `#` characters
356 |
357 | ```
358 | # First # {#first}
359 | ## First ## {#second}
360 | ### Headings and references ### {#headings}
361 | ```
362 |
363 | Use the anchor to reference the heading elsewhere in the text. The link will
364 | automatically be replaced with the heading text. For example `[[#headings]]`
365 | becomes [[#headings]]. This will insert the header title as a link. You can also
366 | customize the link text using a pipe (`|`) character. For example,
367 | `[[#headings|here]]` becomes [[#headings|here]].
368 |
369 | **Always add an anchor to every heading**, even those you do not currently
370 | reference - other people might want to link to them later!
371 |
372 |
373 | ## Mermaid Diagrams ## {#mermaid}
374 |
375 | You can use [Mermaid](https://mermaid.js.org/) to add diagrams to the document.
376 | One benefit of mermaid is that this is also supported natively when viewing
377 | markdown documents on GitHub.
378 |
379 | For example
380 | ```
381 |
422 | Example Mermaid diagram.
423 |
424 |
425 |
426 | ## Inserting images ## {#images}
427 |
428 | Use HTML to insert images. The recommended format is:
429 |
430 | ```html
431 |
432 |
433 | Example image.
434 |
435 | ```
436 |
437 | becomes
438 |
439 |
440 |
441 | Example image.
442 |
443 |
444 | You must place all static images and manually exported diagrams in the `Images/`
445 | directory.
446 |
447 | ## Inserting Links ## {#links}
448 |
449 | Use Markdown link syntax for links to the web.
450 |
451 | ```markdown
452 | [Click here for an adventure](https://zombo.com)
453 | ```
454 |
455 | becomes
456 |
457 | [Click here for an adventure](https://zombo.com)
458 |
459 | ## Tables ## {#tables}
460 |
461 | Use HTML for tables.
462 |
463 | Enclose tables in `figure` tags and provide a caption using `figcaption` to
464 | enable automatic numbering.
465 |
466 | ```html
467 |
468 |
469 |
470 |
471 |
Animal
472 |
Feet
473 |
Average height
474 |
475 |
476 |
Duck
477 |
2
478 |
1 foot
479 |
480 |
Cow
481 |
4
482 |
1.612 meters
483 |
484 |
Cat
485 |
4
486 |
Not too much
487 |
488 | Listing of critical animal measurements.
489 |
490 | ```
491 |
492 | Renders as
493 |
494 |
495 |
496 |
497 |
498 |
Animal
499 |
Feet
500 |
Average height
501 |
502 |
503 |
Duck
504 |
2
505 |
1 foot
506 |
507 |
Cow
508 |
4
509 |
1.612 meters
510 |
511 |
Cat
512 |
4
513 |
Not too much
514 |
515 | Listing of critical animal measurements.
516 |
517 |
518 | The `data` class is a builtin table style suitable for presenting data. An
519 | alternative builtin style you can use is the `def` class.
520 |
521 | ## Referencing illustrations and tables ## {#ref-figures}
522 |
523 | Add an ID to the `figure` element and reference it in a hyperlink. Here is an
524 | example of a reference target:
525 |
526 | ```html
527 |
528 | ...
529 |
530 | ```
531 |
532 | renders as
533 |
534 |
535 | This is a figure
536 | The figure caption
537 |
538 |
539 | You can link to the figure using
540 | `basic facts on important animals` which will render
541 | as basic facts on important animals.
542 |
543 | ## Defining terms ## {#defining-terms}
544 |
545 |
546 | Use the `` element to define a term. You can use it anywhere in text but a
547 | common approach is to use a key-value table:
548 |
549 | ```text
550 | : apricot
551 | :: An apricot is a fruit, or the tree that bears the fruit, of several species
552 | in the genus Prunus
553 | : apple
554 | :: An apple is a sweet, edible fruit produced by an apple tree.
555 | ```
556 |
557 | becomes
558 |
559 | : apricot
560 | :: An apricot is a fruit, or the tree that bears the fruit, of several species
561 | in the genus Prunus
562 | : apple
563 | :: An apple is a sweet, edible fruit produced by an apple tree.
564 |
565 | You can reference defined terms using `[=apple=]`. This will create a link to
566 | [=apple=]
567 |
568 | Singular/plural matching is built-in so you can use `[=apples=]` to link to
569 | [=apples=]. Additionally you can use a pipe character to specify custom text for
570 | the generated link if you need to, i.e. use `[=apple|fruit of the apple tree=]`
571 | to write "Not every [=apple|fruit of the apple tree=] is red".
572 |
573 | Note: You can find more details about Defining terms [in the Bikeshed Documentation](https://speced.github.io/bikeshed/#definitions).
574 |
575 | ## Defining data structures ## {#defining-structs}
576 |
577 | If you define, for example, an XML schema or another type of data format, use
578 | the Bikeshed HTML element reference syntax to enable automatic
579 | cross-referencing.
580 |
581 | For example, consider the following XML element:
582 |
583 | ```xml
584 |
585 | John Jackson
586 |
587 | ```
588 |
589 | Use `employee` to mark it as an element that may have
590 | children as attributes. The common situation is to do this in a document section
591 | heading:
592 |
593 | ```text
594 | ## employee element ## {#schema-employee}
595 | ```
596 |
597 | Then use the definition list syntax below to define its children:
598 |
599 | ```text
600 |
601 |
602 | : id (required, attribute, xs:integer)
603 | :: Employee ID.
604 |
605 | : name (required, xs:string)
606 | :: The full name of the employee.
607 |
608 |
609 | ```
610 |
611 | You can later reference the element as `<{employee}>` and its children as
612 | `<{employee/name}>`.
613 |
614 |
615 | ## References to external documents ## {#specref}
616 |
617 | You can directly reference any document listed in the
618 | [SpecRef catalog](https://specref.org) using `[[!rfc7168]]` (normative)
619 | and `[[rfc2324]]` (informative) tags in text. Such tags will be replaced
620 | with a suitable hyperlink during document compilation and, if the reference is
621 | normative, the referenced document will be added to the bibliography section.
622 |
623 | This is a normative references to [[!rfc7168]] while we add an informative
624 | reference to [[rfc2324]].
625 |
626 | To use custom bibliography entries, update the `biblio.json` file in the root
627 | folder of the repository.
628 |
629 | [SpecRef accepts contributions](https://github.com/tobie/specref#updating--adding-new-references).
630 | If you do not find a document in the catalog, consider adding it to SpecRef
631 | instead of maintaining a custom bibliography section.
632 |
633 | Note: allow up to 24 hours for caches to update after a contribution is merged
634 | to the SpecRef database.
635 |
636 | ## Embedding formulas ## {#formulas}
637 |
638 | You can use TeX syntax for formulas. Surround inline content with `\(` and `\)`
639 | and block content with `$$`.
640 |
641 | ```text
642 | When \(a \ne 0\) there are two solutions to \(ax^2 + bx + c = 0\)
643 | and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
644 | ```
645 |
646 | The above produces the following output.
647 |
648 | When \(a \ne 0\) there are two solutions to \(ax^2 + bx + c = 0\)
649 | and they are $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
650 |
--------------------------------------------------------------------------------
/specs/cmcd/01-cmcd.inc.md:
--------------------------------------------------------------------------------
1 | # Common Media Client Metadata in DASH # {#cmcd}
2 |
3 | ## Introduction ## {#cmcd_introduction}
4 |
5 | This feature description is an update to DASH-IF IOP Guidelines v4.3 [[!IOP43]].
6 | It adds an additional feature.
7 |
8 | The document is developed in [Google docs and can be accessed here](https://docs.google.com/document/d/1tmijOI2xB2w6rED4f-yFXQIPdxsVP8rm7DIgFWnjP1E/edit).
9 |
10 |
--------------------------------------------------------------------------------
/specs/cmcd/cmcd.bs:
--------------------------------------------------------------------------------
1 |
14 |
--------------------------------------------------------------------------------
/specs/live2vod/01-live2vod.inc.md:
--------------------------------------------------------------------------------
1 | # [TITLE] # {#live2vod}
2 |
3 | ## Introduction ## {#live2vod_introduction}
4 |
5 | This feature description is an update to DASH-IF IOP Guidelines v4.3 [[!IOP43]],
6 | clause 4.6. It obsoletes clause 4.6 of DASH-IF IOP Guidelines v4.3 [[!IOP43]].
7 |
8 | ## Scenarios and Motivation ## {#live2vod_scenarios}
9 |
10 | ### Common aspects ### {#live2vod_scenario-common-aspects}
11 |
12 | A common scenario for DASH distribution is that a live distributed content is
13 | also made available On-Demand. Different use cases exist and are discussed in
14 | the following. Common to the different use cases presented are the following
15 | aspects when converting a live service to VoD:
16 |
17 | * desire to re-use the Segments as generated for the live service are also
18 | used for the On-Demand case. This avoids reformatting and also permits to
19 | reuse the Segments that are already cached.
20 |
21 | * the re-use of the live MPD, obviously with some modifications
22 |
23 | * Problems from live delivery may be addressed, e.g. variable segment durations can be signaled,
24 | or unavailable Segments can be marked properly or replaced.
25 |
26 | * The content may be augmented with ads.
27 |
28 | In all cases, the VoD asset is defined by a time window of the live
29 | presentation, whereby each, the start time and end time are defined by a Period in
30 | the MPD and a media time within the Period. Specifically,
31 |
32 | * the first media presentation time of the new On-Demand presentation is
33 | specified by a Period P0 of the live service, and the
34 | media presentation time T0 within this Period
35 | P0.
36 |
37 | * the end time of the new On-Demand presentation is specified by a Period
38 | P1 that is not earlier than Period
39 | P1 of the live service, and the media presentation time
40 | T1 within this Period P1.
41 |
42 | The figure below provides an overview of the scenarios.
43 |
44 |
45 |
46 | Different Live to VoD Scenarios
47 |
48 |
49 | ### Scheduled and Bounded Live Service transitioned to VoD ### {#live2vod_scenario-scheduled-and-bounded}
50 |
51 | A first scenario for Live Content being converted to VOD is the case that a
52 | scheduled live event starting at a known date and time is also made available
53 | for On-Demand offering after the live program is completed. This case is
54 | well-known from sports events, for example football matches (for which the duration
55 | can be relatively easily predicted) or tennis matches (for which the duration may
56 | be quite arbitrary).
57 |
58 | ### Extracting a time period from continuous live ### {#live2vod_scenario-extraction}
59 |
60 | In the second scenario, the content is extracted from a longer, e.g. 24/7 stream,
61 | at the beginning, the end, or in between. This allows that the content is
62 | offered in a recorded fashion to users. The On-demand content again is defined by a
63 | start and an end time in the live content.
64 |
65 | ### Transition between Live and On-Demand ### {#live2vod_scenario-transition}
66 |
67 | In an extension of the first scenario, the live service may be converted to a VOD service
68 | in a seamless manner. To allows this, the service is provided in live and on-demand
69 | concurrently in a transition phase. Assume towards the end of a
70 | live service, the content and service remains on the portal, but the clients are
71 | no longer experience the joining of the live service at the live edge, but the
72 | On-Demand service from the start while using the same MPD URL.
73 |
74 | ## Content Offering Requirements and Recommendations ## {#live2vod_content-offering}
75 |
76 | ### Common aspects ### {#live2vod_content-offering-common-aspects}
77 |
78 | A live service is offered with an MPD, where for the MPD the `MPD@type` is set
79 | to `dynamic`. In addition, the MPD may be updated by having the
80 | `MPD@minimumUpdatePeriod` present. The live service may use different types of
81 | profiles, including multi-Period content, number-based or time-based templating,
82 | as well using `@duration` or Segment Timeline based segment duration signaling.
83 | The live service may include events in the MPD and/or Inband Event Streams. Segments get
84 | available over time, whereby the latest segment availability start time can be
85 | determined by information in the MPD as the sum of the `MPD@availabilityStartTime`,
86 | the start of the Period provided in *PeriodStart* as defined in [[!DASH]], clause
87 | 5.3.2.
88 |
89 | In order to provide live content as On-Demand, the following is recommended:
90 |
91 | * The same Segments as generated for the live distribution are reused also for
92 | VoD distribution.
93 |
94 | * The Segments for live and VoD services share the same URLs in order to
95 | exploit caching advantages.
96 |
97 | * An MPD for the VOD service is created using the MPD for the live service
98 | with the following modifications
99 |
100 | * The `MPD@type` is set to `static`.
101 |
102 | * The `MPD@availabilityStartTime` may be removed, but could also be
103 | maintained from the live MPD since all resources referenced in the MPD are
104 | available assuming that the resources of the live program are available.
105 | The content author may also set the `MPD@availabilityStartTime` to a later
106 | time, for example to the largest availability time of any Segment in the
107 | live Media Presentation.
108 |
109 | * The attributes `@timeShiftBufferDepth` and `@minimumUpdatePeriod` should
110 | not be present (in contrast to the live MPD), i.e. it is expected that
111 | such attributes are removed. Note that according to ISO/IEC 23009-1
112 | [[!DASH]], that if present, a client is expected to ignore these
113 | attributes for `MPD@type` set to `static`.
114 |
115 | * Content may be offered in the same Period structure as for live or in a
116 | different one. However,
117 |
118 | * if Periods were only added to provide ad insertion opportunities and
119 | are signaled to be period-continuous [[!IOP5-PART5]], it is preferable
120 | to remove the Period structure.
121 |
122 | * if new Periods are added for Ad Insertion, the Periods are preferably
123 | added in a way that they are at Segment boundaries of video Adaptation
124 | Sets following the recommendations in [[!IOP5-PART5]].
125 |
126 | * The presentation duration is determined through either the
127 | `@mediaPresentationDuration` attribute or, if not present, through the sum
128 | of the *PeriodStart* and the `Period@duration` attribute of the last
129 | Period in the MPD. More details on this setting are defined specifically for
130 | each scenario further below.
131 |
132 | * Independent whether the `@duration` attribute or the `SegmentTimeline`
133 | element was used for the live distribution, the static distribution
134 | version preferably uses the `SegmentTimeline` with accurate timing to
135 | support seeking and to possibly also signal any gaps in the Segment
136 | timeline. However, to obtain the accurate timeline, the Segments may have
137 | to be parsed (at least up to the `tfdt`) to extract the accurate start
138 | time and duration of each Segment.
139 |
140 | * The same templating mode as used in the live service shall also be used
141 | for static distribution in order to reuse the URLs of the cached Segments.
142 |
143 | * MPD validity expiration events should not be present in the MPD. However,
144 | it is not recommended that `emsg` boxes are removed from Segments as this
145 | would result in change of Segments and invalidate caches. It is expected that
146 | by removal of the corresponding `InbandEventStream` element in the MPD, the
147 | DASH client will ignore the `emsg` boxes.
148 |
149 | Specifically on the timing signaling of the Periods in the VoD offering,
150 |
151 | * for first Period P0 in the live period,
152 |
153 | * `Period@start` shall be either be removed or set to zero.
154 |
155 | * the `@presentationTimeOffset` for each Adaptation Set shall be set to the media
156 | presentation time included in the first Segment at T0,
157 | normalized by the value of the `@timescale` of the Adaptation Set.
158 |
159 | * The value of the `Period@duration` attribute shall be set as follows: If
160 | the first Period and the last Period are identical, i.e.
161 | P0 is P1, then *PeriodDuration* is
162 | set to T1 – T0. If the first
163 | Period is different than the last Period, i.e. P1 is
164 | not P0, then the *PeriodDuration* is set to the
165 | difference of *PeriodStart* value of the second Period minus
166 | T0.
167 |
168 | * For all remaining Periods except the last one, the *PeriodDuration* shall be
169 | set to the difference of the *PeriodStart* of the next Period and the
170 | *PeriodStart* value of the this Period in the live MPD.
171 |
172 | * For the last Period, if it is not the identical to the first Period, the
173 | *PeriodDuration* is set to the difference of T1 and the
174 | *PeriodStart* of this last Period P1 in the live MPD. If
175 | the first Period is different than the last Period, then the
176 | *PeriodDuration* is set to the difference of *PeriodStart* value of the
177 | second Period minus T0.
178 |
179 | * For all cases the *PeriodDuration* is preferably signaled by removing the
180 | `Period@start` attribute for each Period and setting the `Period@duration`
181 | attribute to *PeriodDuration*. However, setting the `Period@start` attribute
182 | may also be used. Also, to signal the *PeriodDuration* of the last Period,
183 | the `MPD@mediaPresentationDuration` attribute may be used. According to
184 | ISO/IEC 23009-1 [[!DASH]], Annex A.3.2, the `MPD@mediaPresentationDuration`
185 | attribute takes precendence over the *PeriodDuration*.
186 |
187 | ### Scheduled and Bounded Live Service transitioned to VoD ### {#live2vod_content-offering-scheduled-and-bounded}
188 |
189 | In the specific scenario for a scheduled service, for which the start and end
190 | times of the live and VOD service coincide, it is recommended that for the live
191 | service, the `MPD@availabilityStartTime` is set as the availability time of the
192 | initial Period, and the `Period@start` of the first Period of the live service
193 | is set to 0.
194 |
195 | If this is the case, the operations documented in the common aspects in clause
196 | [[#live2vod_content-offering-common-aspects]] are significantly simplified and
197 | no changes to period timing are needed. The only modifications to the MPD are as
198 | follows:
199 |
200 | * adding the attribute `MPD@mediaPresentationDuration`
201 |
202 | * removing the attribute `MPD@minimumUpdatePeriod`
203 |
204 | * changing the `MPD@type` from `dynamic` to `static`
205 |
206 | Note that these changes may happen all at the same time, or the first two
207 | may be applied first and the second change only in yet another update.
208 |
209 | ### Extracting a time period from continuous live ### {#live2vod_content-offering-extraction}
210 |
211 | In the scenario, for which a part from the live service is extracted and made
212 | available as On-Demand content, all recommendations from the common
213 | aspects in clause [[#live2vod_content-offering-common-aspects]] apply.
214 |
215 | ### Transition between Live and On-Demand ### {#live2vod_content-offering-transition}
216 |
217 | In the case of transitioning the services, the content offering should take into
218 | account the following guidelines.
219 |
220 | Generally, in particular in 24/7 live service,
221 | or if the VOD service starts before the live service ends, it is discouraged
222 | that the the same MPD URL is used for live and on-demand content. It is
223 | preferred to create a new MPD URL for the on-demand content to not confuse
224 | clients when transitioning from live to on-demand MPD. Note that the same Segments
225 | with the same Segment URLs may and should be shared across live and VOD MPD.
226 |
227 | However, there are relevant use cases to support a transition from live to on-demand content
228 | at the end of a live service and re-using the existing MPD URL, in particular when the live
229 | service follows the specific restrictions in section [[#live2vod_content-offering-scheduled-and-bounded]].
230 |
231 | In this transitioning phase when the live service comes to an end, as a first action,
232 | once the URL and publish time of the last Segment is known for the live service,
233 | and the duration of the service is known as well, the live MPD should be changed
234 | as defined in clause 4.4.3.1 of [[!IOP43]],, i.e.,
235 |
236 | * adding the attribute `MPD@mediaPresentationDuration` to match the duration of the service
237 |
238 | * removing the attribute `MPD@minimumUpdatePeriod`
239 |
240 | This action is the normal action when terminating a live service.
241 |
242 | In this case and at this time, all Segments URLs are known and clients playing the live
243 | service can complete the playback of the service until the end without updating the MPD.
244 | However, some clients may also use the timeshift buffer to go back to earlier media times,
245 | or play the live service with some delay. The beneficial aspect of the action above, i.e.
246 | removing the the attribute `MPD@minimumUpdatePeriod` is that the DASH clients are expected
247 | to stop updating the MPD for operational reasons.
248 |
249 | However, clients joining the service for the first time seeing the above MPD
250 | will see the type `dynamic` and will attempt to access the live edge, but no content
251 | is available as the live edge, as this is past the scheduled presentation.
252 | For this case, the client is expected to provide an indication to the user that it
253 | joined at the end of the media presentation, for example by playing the
254 | last few video frames of the last segment. However, such user experience to join
255 | terminated services is less preferred.
256 |
257 | In order for clients to join at the start of the live service, the `MPD@type`
258 | needs to change from `dynamic` to `static`. While this change may confuse
259 | clients that update the MPD, as long as this action happens only at a time when
260 | clients no longer update the MPD, it will not create issues. For clients that
261 | play back, MPD updates are expected to not happen anymore after the MPD change
262 | from `@minimumUpdatePeriod` to `@mediaPresentationDuration` has been done, with
263 | some grace period. The grace period can be estimated as the value of
264 | `@minimumUpdatePeriod` plus the value of the `@maxSegmentDuration`. After this
265 | time, it is expected that only clients would update the MPD that have paused
266 | playback of live, and have not implemented MPD updates in pause state.
267 |
268 | Hence, it is recommended that in the general case, service providers are
269 | permitted to change the MPD and replace the `@type` to be `static` and apply all
270 | of the modifications as documented in section [[#live2vod_content-offering-common-aspects]].
271 |
272 | In the specific service offering above for which the `MPD@availabilityStartTime` is
273 | set to a value that is aligned with the start of the live presentation, and for
274 | which the `Period@start` of the first Period is set to 0, none of the Period
275 | modifications described in section [[#live2vod_content-offering-common-aspects]]
276 | need to be done and the MPD can be used as is. In this case, the change
277 | from type `dynamic` to `static` may happen even earlier.
278 |
279 | ## Client Behavior ## {#live2vod_client}
280 |
281 | For a DASH client, there is basically no difference on whether the content was
282 | generated from a live service or the content is provided as On-Demand. However,
283 | there are some aspects that may be “left-overs” from a live service distribution
284 | that a DASH client should be aware of:
285 |
286 | * The Representations may show gaps in the Segment Timeline. Such gaps should
287 | be recognized and properly handled. For example a DASH client may find a gap
288 | only in one Representation of the content and therefore switches to another
289 | Representation that has no gap.
290 |
291 | * The DASH client shall ignore any possibly present DASH Event boxes `emsg`
292 | (e.g., MPD validity expirations) for which no Inband Event Stream is present
293 | in the MPD.
294 |
295 | * clients that access an MPD with `MPD@type='static'` for first time should
296 | start playback from the beginning (unless a specific start time is chosen
297 | using an MPD anchor).
298 |
299 | * clients that access an `MPD@type='dynamic'` for the
300 | first time should start from the live edge (unless a specific start time is
301 | chosen using an MPD anchor). If the live edge is close to the end or past the end
302 | of the media presentation, the DASH client should play the last few seconds
303 | of the live service in order for the user to provide the impression of
304 | joining the service. The DASH client should also update the MPD and should expect
305 | that the type changes from `dynamic` to `static`.
306 |
307 | DASH clients should support the transition from `MPD@type` being `dynamic` to
308 | `static` in the case when the `@minimumUpdatePeriod` is no longer present in the
309 | MPD, as long as the Period structure is not changed.
310 |
311 | ## Examples ## {#live2vod_examples}
312 |
313 | In the following, three published MPDs are provided.
314 |
315 | The first one is a live MPD and is open-ended.
316 |
317 | ```xml
318 |
328 |
329 | http://example.com/1/
330 |
331 |
332 |
333 |
334 |
335 |
336 |
337 |
338 |
339 |
340 |
341 |
342 |
343 |
344 |
345 |
346 |
347 | ```
348 |
349 | At the time when the duration of the Media Presentation is known, the `MPD@mediaPresentationDuration` is added giving indication that the live presentation will terminate.
350 |
351 | ```xml
352 |
362 |
363 | http://example.com/1/
364 |
365 |
366 |
367 |
368 |
369 |
370 |
371 |
372 |
373 |
374 |
375 |
376 |
377 |
378 |
379 |
380 |
381 | ```
382 |
383 |
384 | ```xml
385 |
394 |
395 | http://example.com/1/
396 |
397 |
398 |
399 |
400 |
401 |
402 |
403 |
404 |
405 |
406 |
407 |
408 |
409 |
410 |
411 |
412 |
413 | ```
414 |
415 | ## Reference Tools ## {#live2vod_reference-tools}
416 |
417 | NOTE: provide status for the following functionalities
418 | * Dash.js
419 | * Live Sim
420 | * Test Vectors
421 | * JCCP
422 |
423 | ## Additional Information ## {#live2vod_additional-information}
424 |
425 |
426 |
427 |
--------------------------------------------------------------------------------
/specs/live2vod/Diagrams/Live2VoD.pptx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/f5b3b227f4392c124c6d2ae439819259b1fb19b0/specs/live2vod/Diagrams/Live2VoD.pptx
--------------------------------------------------------------------------------
/specs/live2vod/Images/Live2VoD.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/f5b3b227f4392c124c6d2ae439819259b1fb19b0/specs/live2vod/Images/Live2VoD.png
--------------------------------------------------------------------------------
/specs/live2vod/live2vod.bs:
--------------------------------------------------------------------------------
1 |
2 | Revision: 0.9
3 | Title: Conversion of Live Services to VoD
4 | Status: CR
5 | Shortname: live2vod
6 | URL: https://dashif.org/Guidelines/live2vod
7 | Group: dashif
8 |
9 | !Disclaimer: This document is technically stable, but public is asked for comments in order to improve details. Community Review documents are published on the DASH-IF WG website in order to get feedback from the industry on tools and features that are documented for improved interoperability. For each of the documents, comments may be submitted on the technologies itself, on specific features, etc. These documents are only published temporarily for community review and will be replaced by a full version after the commenting period has closed and the comments have been addressed. Community Review documents may also be published as Change Requests to existing specifications. The following document is open for community review since February 25, 2025 until March 31st, 2025. Once the comments from community review are addressed, the document will be published as a DASH-IF Technical Specification. Please use github Bugtracker for any feedback: https://github.com/Dash-Industry-Forum/DASH-IF-IOP/issues.
10 | !Contributors: [Thomas Stockhammer](https://linkedin.com/in/stockhammer), [Rufael Mekuria](https://www.linkedin.com/in/rufael-mekuria-652b4828/)
11 | !Key Words: VoD, Live
12 | !Related Features: Live
13 |
14 |
15 |
16 | path: 01-live2vod.inc.md
17 |
18 |
--------------------------------------------------------------------------------
/specs/mpd-patch/01-mpd-patch.inc.md:
--------------------------------------------------------------------------------
1 | # MPD Patch # {#mpd-patch}
2 |
3 | ## Introduction ## {#mpd-patch_introduction}
4 |
5 | This feature description is an update to DASH-IF IOP Guidelines v4.3 [[!IOP43]].
6 | It adds an additional feature, the MPD Patch, a way provide a differential
7 | update to a previous dynamic MPD.
8 |
9 | ## Scenarios ## {#mpd-patch_scenarios}
10 |
11 | The typical use case for MPD patch is for dynamic manifests with long
12 | SegmentTimeline elements due to non-constant segment duration prohibiting
13 | efficient compression using repeat count.
14 | This happens when the media frame rate is not commensurable with
15 | the segment duration.
16 |
17 | For example, a 2s average segment duration is not compatible with AAC
18 | 48kHz audio, since it corresponds to 93.75 frames leading to a cycle
19 | of 4 segments (8s) and the corresponding SegmentTimline pattern:
20 |
21 | ```xml
22 |
23 |
24 |
25 |
26 |
27 |
28 |
29 | ```
30 |
31 | For a long sliding window, this results in a huge MPD. With MPD Patch
32 | one can instead request a delta document, a Patch, describing the changes
33 | relative to a `publishTime`.
34 |
35 | ## Content Offering Requirements and Recommendations ## {#mpd-patch_content-offering}
36 |
37 | MPD Patch is essentially only useful in the case of `SegmentTemplate with
38 | SegmentTimeline`. It is especially useful when the segment durations are
39 | varying leading to long `SegmentTimeline` nodes. It may also help in the
40 | case of multiple periods of a dynamic MPD.
41 |
42 | MPD Patch should NOT be used for for `SegmentTemplate with $Number$` since
43 | such MPDs typically rarely change, meaning that their content including the
44 | `publishTime` is the same over a longer period of time.
45 |
46 | The `PatchLocation` element in the MPD contains an optional `ttl` attribute
47 | providing the availability end time relative to the `publishTime`.
48 | It is recommended to use this value, and set it to relatively small number
49 | like 1 minute.
50 |
51 | The node serving the MPD Patch requests can cache the first response
52 | with an updated `publishTime` respect to the referred one, provided
53 | that the time difference is less than the `ttl` value.
54 |
55 | A client can therefore NOT assume that the Patch response is providing
56 | information about the latest publishTime. It follows that he client may need
57 | to make more MPD Patch requests to arrive at the live edge.
58 |
59 | The server response to a too early request for an MPD Patch,
60 | i.e. before there is a new publishTime, should be the same as when
61 | asking for a segment before its availability time. That could be
62 | `404 Not Found` or `425 Too Early`.
63 |
64 | ## Client Implementation Requirements and Guidelines ## {#mpd-patch_client}
65 |
66 | Clients should ignore the `` element if not understood.
67 | If used, they should make a request for an Patch at the same instant
68 | that they would ask for an updated MPD.
69 |
70 | If they get a `4XX` response to the Patch request, they should either
71 | wait and redo the request, or switch to fetching a full MPD.
72 |
73 | ## Examples ## {#mpd-patch_examples}
74 |
75 | Below is an example with a `` element and
76 | `publishTime="2024-04-16T07:34:38Z`.
77 |
78 | ```xml
79 |
80 |
85 |
86 | Basic MPD with 640x480@30 video at 300kbp and 48kbps audio
87 | VoD source for DASH-IF livesim2
88 |
89 | /patch/livesim2/patch_60/segtimeline_1/testpic_2s/Manifest.mpp?publishTime=2024-04-16T07%3A34%3A38Z
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 |
110 |
111 |
112 |
113 |
114 |
115 |
116 |
117 |
118 |
119 |
120 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
128 | ```
129 |
130 | The segments have an average duration of 2s, so a request 5s after the publishTime
131 | results in the following PATCH document with a more complex change
132 | to the audio part than to the video part.
133 |
134 | ```xml
135 |
136 |
139 | 2024-04-16T07:34:42Z
140 |
141 | /patch/livesim2/patch_60/segtimeline_1/testpic_2s/Manifest.mpp?publishTime=2024-04-16T07%3A34%3A42Z
142 |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
152 |
153 |
154 |
155 |
156 |
157 |
158 | ```
159 |
160 | ## Reference Tools ## {#mpd-patch_reference-tools}
161 |
162 | NOTE: provide status for the following functionalities
163 |
164 | * dash.js supports MPD Patch for `SegmentTemplate with SegmentTimeline`.
165 | It has been tested towards [livesim2][livesim2] including cases with
166 | multiple periods. If a 4XX response is received, it will switches to
167 | ordinary full MPD requests (Daniel to confirm)
168 | * [livesim2][livesim2] supports MPD DASH. There is [Wiki article][livesim2-wiki]
169 | describing how it works
170 | * Test Vectors. One can get test vectors from the
171 | [DASH-IF instance of livesim2][livesim2-instance], e.g.
172 | [https://livesim2.dashif.org/livesim2/patch_60/segtimeline_1/testpic_2s/Manifest.mpd][livesim2-entry].
173 | Use the [urlgen][urlgen] page to generate other test vectors.
174 | * JCCP
175 |
176 | ## Additional Information ## {#mpd-patch_additional-information}
177 |
178 | [livesim2]: https://github.com/Dash-Industry-Forum/livesim2
179 | [livesim2-wiki]: https://github.com/Dash-Industry-Forum/livesim2/wiki/MPD-Patch
180 | [livesim2-instance]: https://livesim2.dashif.org
181 | [livesim2-entry]:https://livesim2.dashif.org/livesim2/patch_60/segtimeline_1/testpic_2s/Manifest.mpd
182 | [urlgen]: https://livesim2.dashif.org/urlgen
--------------------------------------------------------------------------------
/specs/mpd-patch/mpd-patch.bs:
--------------------------------------------------------------------------------
1 |
4 |
5 |
--------------------------------------------------------------------------------
/setup.bat:
--------------------------------------------------------------------------------
1 | @echo off
2 | docker pull dashif/specs-builder:latest
--------------------------------------------------------------------------------
/setup.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | # Pull the latest build image
4 | IMG=dashif/specs-builder:latest
5 | docker pull ${IMG}
6 |
--------------------------------------------------------------------------------
/specs/authoring/Diagrams/GitHubConcepts1-Original.wsd:
--------------------------------------------------------------------------------
1 | @startuml
2 |
3 | package "GitHub account of document owner" {
4 | [Document repository\naka upstream repository] as Upstream
5 | [master branch] as Master
6 |
7 | Upstream - Master
8 | }
9 |
10 | @enduml
--------------------------------------------------------------------------------
/specs/authoring/Diagrams/second.wsd:
--------------------------------------------------------------------------------
1 | @startuml
2 |
3 | package "GitHub account of document owner" {
4 | [Document repository\naka upstream repository] as Upstream
5 | [master branch] as Master
6 |
7 | Upstream - Master
8 | }
9 |
10 | @enduml
11 |
--------------------------------------------------------------------------------
/specs/authoring/Images/Math.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/f5b3b227f4392c124c6d2ae439819259b1fb19b0/specs/authoring/Images/Math.png
--------------------------------------------------------------------------------
/specs/authoring/authoring.bs:
--------------------------------------------------------------------------------
1 | 
433 | 
46 |