├── setup.bat ├── .vs ├── ProjectSettings.json ├── slnx.sqlite ├── DASH-IF-IOP │ └── v16 │ │ └── .suo └── VSWorkspaceState.json ├── .gitignore ├── .vscode ├── spellright.dict ├── tasks.json └── settings.json ├── data └── boilerplate │ ├── dashif.kdl │ └── dashif │ ├── logo.include │ ├── defaults.include │ └── header.include ├── setup.sh ├── specs ├── authoring │ ├── Images │ │ └── Math.png │ ├── Diagrams │ │ ├── second.wsd │ │ └── GitHubConcepts1-Original.wsd │ ├── authoring.bs │ └── authoring.md ├── live2vod │ ├── Images │ │ └── Live2VoD.png │ ├── Diagrams │ │ └── Live2VoD.pptx │ ├── live2vod.bs │ └── 01-live2vod.inc.md ├── lc-evc │ ├── lc-evc.bs │ └── 01-lc-evc.inc.md ├── l3d │ ├── 01-l3d.inc.md │ └── l3d.bs ├── mpd-patch │ ├── mpd-patch.bs │ └── 01-mpd-patch.inc.md ├── varsub │ ├── 01-varsub.inc.md │ └── varsub.bs ├── cmcd │ ├── cmcd.bs │ └── 01-cmcd.inc.md └── content-steering │ ├── 01-content-steering.inc.md │ └── content-steering.bs ├── .editorconfig ├── .github └── workflows │ ├── build-pr.yml │ ├── build-container.yml │ └── publish-bikeshed.yml ├── biblio.json └── README.md /setup.bat: -------------------------------------------------------------------------------- 1 | @echo off 2 | docker pull dashif/specs-builder:latest -------------------------------------------------------------------------------- /.vs/ProjectSettings.json: -------------------------------------------------------------------------------- 1 | { 2 | "CurrentProjectSetting": null 3 | } -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | .idea 3 | .python-version 4 | *.html 5 | dist/ 6 | -------------------------------------------------------------------------------- /.vscode/spellright.dict: -------------------------------------------------------------------------------- 1 | live2vod 2 | Inband 3 | Dash.js 4 | rfc 5 | Bikeshed 6 | -------------------------------------------------------------------------------- /.vs/slnx.sqlite: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/HEAD/.vs/slnx.sqlite -------------------------------------------------------------------------------- /.vs/DASH-IF-IOP/v16/.suo: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/HEAD/.vs/DASH-IF-IOP/v16/.suo -------------------------------------------------------------------------------- /.vs/VSWorkspaceState.json: -------------------------------------------------------------------------------- 1 | { 2 | "ExpandedNodes": [ 3 | "" 4 | ], 5 | "PreviewInSolutionExplorer": false 6 | } -------------------------------------------------------------------------------- /data/boilerplate/dashif.kdl: -------------------------------------------------------------------------------- 1 | org "dashif" { 2 | group "dashif" 3 | 4 | status "CR" "Community Review" 5 | } 6 | -------------------------------------------------------------------------------- /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/Images/Math.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/HEAD/specs/authoring/Images/Math.png -------------------------------------------------------------------------------- /specs/live2vod/Images/Live2VoD.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/HEAD/specs/live2vod/Images/Live2VoD.png -------------------------------------------------------------------------------- /specs/live2vod/Diagrams/Live2VoD.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Dash-Industry-Forum/DASH-IF-IOP/HEAD/specs/live2vod/Diagrams/Live2VoD.pptx -------------------------------------------------------------------------------- /data/boilerplate/dashif/logo.include: -------------------------------------------------------------------------------- 1 | 2 | DASH-IF Logo 4 | 5 | -------------------------------------------------------------------------------- /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/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/lc-evc/lc-evc.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: Support for LC-EVC in DASH
 4 | Status: LD
 5 | Shortname: l3d
 6 | URL: https://dashif.org/Guidelines/master/lc-evc.html
 7 | Group: dashif
 8 | !Contributors: [Alan Stein](https://www.linkedin.com/in/ajstein/)
 9 |
10 | 11 | 
12 | path: 01-lc-evc.inc.md
13 |
14 | -------------------------------------------------------------------------------- /specs/lc-evc/01-lc-evc.inc.md: -------------------------------------------------------------------------------- 1 | # [TITLE] # {#lcevc} 2 | 3 | ## Introduction ## {#lcevc:introduction} 4 | 5 | This feature description is an update to DASH-IF IOP Part 7 (Video) adding additional features. 6 | 7 | The document is developed in [Google docs and can be accessed here](https://docs.google.com/document/d/1ImwRa2XRG0Amr5o9WA176scmAgeVnzPLhXW7IyWvE8Q/edit?usp=sharing). 8 | -------------------------------------------------------------------------------- /specs/l3d/01-l3d.inc.md: -------------------------------------------------------------------------------- 1 | # [TITLE] # {#l3d} 2 | 3 | ## Introduction ## {#l3d:introduction} 4 | 5 | This feature description is an update to DASH-IF Low-Latency extensions [[!IOP5-PART4-LL]] adding additional features. 6 | 7 | The document is developed in [Google docs and can be accessed here](https://docs.google.com/document/d/1pj3Ex5AdmkfeYGd9KAXHEVercfee30NsjHg36L5EZos/edit?usp=sharing). 8 | -------------------------------------------------------------------------------- /specs/mpd-patch/mpd-patch.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: DASH-IF implementation guidelines: MPD Patch
 4 | Status: LD
 5 | Shortname: mpd-patch
 6 | URL: https://dashif.org/Guidelines/master/mpd-patch.html
 7 | Group: dashif
 8 | 
 9 | !Contributor:
10 | !Key Word:
11 | !Related Features:
12 |
13 | 14 | 
15 | path: 01-mpd-patch.inc.md
16 |
17 | -------------------------------------------------------------------------------- /specs/authoring/authoring.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: DASH-IF IOP Document Authoring
 4 | Status: LD
 5 | Shortname: authoring
 6 | URL: https://dashif.org/Guidelines/master/authoring.html
 7 | Group: dashif
 8 | 
 9 | !Contributor: Thasso Griebel
10 | !Key Word: Authoring
11 | !Related Features:
12 |
13 | 14 | 
15 | path: authoring.md
16 |
17 | -------------------------------------------------------------------------------- /specs/varsub/01-varsub.inc.md: -------------------------------------------------------------------------------- 1 | # [TITLE] # {#varsub} 2 | 3 | ## Introduction ## {#varsub_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/1rFvEMFsqz6FZk4ldSFRpnnIfxRkgWE7q1pqvJMJcjD0/edit). 9 | 10 | -------------------------------------------------------------------------------- /specs/cmcd/cmcd.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: DASH-IF implementation guidelines: Common Media Client Metadata (CMCD) in DASH
 4 | Status: LD
 5 | Shortname: cmcd
 6 | URL: https://dashif.org/Guidelines/master/cmcd.html
 7 | Group: dashif
 8 | 
 9 | !Contributor:
10 | !Key Word: CMCD
11 | !Related Features:
12 |
13 | 14 | 
15 | path: 01-cmcd.inc.md
16 |
17 | -------------------------------------------------------------------------------- /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/content-steering/01-content-steering.inc.md: -------------------------------------------------------------------------------- 1 | # Content Steering # {#content-steering} 2 | 3 | ## Introduction ## {#content-steering_introduction} 4 | 5 | This feature description is an update to DASH-IF IOP Guidelines v4.3 [[!IOP43]]. 6 | It adds an additional features. 7 | 8 | The document is developed in [Google docs and can be accessed here](https://docs.google.com/document/d/18DjRAQS4MMbP1zwOf0d_VU9X4A3rIvj6lAFk3_ChYQM/edit). 9 | -------------------------------------------------------------------------------- /specs/varsub/varsub.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: DASH-IF implementation guidelines: Variable Substitution using query and header parameter
 4 | Status: LD
 5 | Shortname: varsub
 6 | URL: https://dashif.org/Guidelines/master/varsub.html
 7 | Group: dashif
 8 | 
 9 | !Contributor:
10 | !Key Word: Annex I
11 | !Related Features:
12 |
13 | 14 | 
15 | path: 01-varsub.inc.md
16 |
17 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig is awesome: https://EditorConfig.org 2 | 3 | # top-most EditorConfig file 4 | root = true 5 | 6 | # Unix-style newlines with a newline ending every file 7 | [*] 8 | end_of_line = lf 9 | insert_final_newline = true 10 | trim_trailing_whitespace = true 11 | charset = utf-8 12 | indent_style = space 13 | indent_size = 2 14 | 15 | # Tab indentation (no size specified) 16 | [Makefile] 17 | indent_style = tab 18 | -------------------------------------------------------------------------------- /specs/content-steering/content-steering.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1.0
 3 | Title: DASH-IF Implementation Guidelines: Content Steering
 4 | Status: LD
 5 | Shortname: content-steering
 6 | URL: https://dashif.org/Guidelines/master/content-steering.html
 7 | Group: dashif
 8 | !Contributors: [Yuriy Reznik](https://www.linkedin.com/in/yuriy-a-reznik/)
 9 |
10 | 11 | 
12 | path: 01-content-steering.inc.md
13 |
14 | -------------------------------------------------------------------------------- /specs/l3d/l3d.bs: -------------------------------------------------------------------------------- 1 | 
 2 | Revision: 0.1
 3 | Title: Lower Latency, Startup and Switching for DASH (L3D)
 4 | Status: LD
 5 | Shortname: l3d
 6 | URL: https://dashif.org/Guidelines/master/l3d.html
 7 | Group: dashif
 8 | !Contributors: [Alex Giladi](https://www.linkedin.com/in/agiladi/)
 9 | !Contributors: [Thomas Stockhammer](https://www.linkedin.com/in/stockhammer/)
10 |
11 | 12 | 
13 | path: 01-l3d.inc.md
14 |
15 | -------------------------------------------------------------------------------- /data/boilerplate/dashif/defaults.include: -------------------------------------------------------------------------------- 1 | { 2 | "Issue Tracking": "GitHub https://github.com/Dash-Industry-Forum/DASH-IF-IOP/issues", 3 | "Repository": "https://github.com/Dash-Industry-Forum/DASH-IF-IOP GitHub", 4 | "Editor": "SVTA DASH-IF Working Group", 5 | "Default Highlight": "text", 6 | "Line Numbers": "off", 7 | "Markup Shorthands": "markdown yes, biblio yes", 8 | "Boilerplate": "copyright off, abstract off, conformance off", 9 | "Abstract": "None", 10 | "Indent": "2" 11 | } 12 | -------------------------------------------------------------------------------- /.vscode/tasks.json: -------------------------------------------------------------------------------- 1 | { 2 | // See https://go.microsoft.com/fwlink/?LinkId=733558 3 | // for the documentation about the tasks.json format 4 | "version": "2.0.0", 5 | "tasks": [ 6 | { 7 | "label": "Build All", 8 | "type": "shell", 9 | "command": "./build.sh", 10 | "problemMatcher": [], 11 | "group": { 12 | "kind": "build", 13 | "isDefault": true 14 | } 15 | } 16 | ] 17 | } -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "editor.renderWhitespace": "all", 3 | "editor.rulers": [ 4 | 80, 5 | 120 6 | ], 7 | "spellright.language": [ 8 | "en" 9 | ], 10 | "spellright.documentTypes": [ 11 | "bikeshed", 12 | "markdown", 13 | "latex", 14 | "plaintext" 15 | ], 16 | "files.associations": { 17 | "*.bs.md": "bikeshed", 18 | "*.inc.md": "markdown" 19 | }, 20 | "cSpell.enabled": true, 21 | "cSpell.words": [ 22 | "advisements", 23 | "biblio", 24 | "bikeshed", 25 | "Codespaces", 26 | "dashif", 27 | "plantuml" 28 | ], 29 | } 30 | -------------------------------------------------------------------------------- /.github/workflows/build-pr.yml: -------------------------------------------------------------------------------- 1 | name: Build Pull Request 2 | 3 | on: 4 | pull_request: 5 | branches: 6 | - master 7 | paths-ignore: 8 | - 'build-tools/**' 9 | - 'data/boilerplate/**' 10 | - '.github/workflows/build-container.yml' 11 | 12 | 13 | jobs: 14 | build: 15 | runs-on: ubuntu-latest 16 | container: 17 | image: ghcr.io/dash-industry-forum/dashif-specs:latest 18 | credentials: 19 | username: ${{ github.actor }} 20 | password: ${{ secrets.github_token }} 21 | 22 | steps: 23 | - uses: actions/checkout@v4 24 | - name: Build 25 | env: 26 | # Reset OPTS to empty to make sure we are not using 27 | # interactive mode in CI 28 | OPTS: 29 | run: make -f /tools/Makefile 30 | - name: Archive 31 | uses: actions/upload-artifact@v4 32 | with: 33 | name: dist 34 | path: dist/ 35 | -------------------------------------------------------------------------------- /.github/workflows/build-container.yml: -------------------------------------------------------------------------------- 1 | name: Build Container 2 | 3 | on: 4 | workflow_dispatch: 5 | push: 6 | branches: 7 | - master 8 | paths: 9 | - 'build-tools/**' 10 | - 'data/boilerplate/**' 11 | - '.github/workflows/build-container.yml' 12 | 13 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 14 | permissions: 15 | contents: read 16 | packages: write 17 | 18 | jobs: 19 | build: 20 | runs-on: ubuntu-latest 21 | 22 | steps: 23 | - uses: actions/checkout@v4 24 | 25 | - name: Set up QEMU 26 | uses: docker/setup-qemu-action@v3 27 | 28 | - name: Set up Docker Buildx 29 | uses: docker/setup-buildx-action@v3 30 | 31 | - name: Login to Docker Hub 32 | uses: docker/login-action@v3 33 | with: 34 | username: ${{ secrets.DOCKERHUB_USER }} 35 | password: ${{ secrets.DOCKERHUB_TOKEN }} 36 | 37 | - name: Login to GitHub Container Registry 38 | uses: docker/login-action@v3 39 | with: 40 | registry: ghcr.io 41 | username: ${{ github.repository_owner }} 42 | password: ${{ secrets.GITHUB_TOKEN }} 43 | 44 | - name: Build and push 45 | uses: docker/build-push-action@v6 46 | with: 47 | file: build-tools/Dockerfile 48 | platforms: linux/amd64,linux/arm64 49 | push: true 50 | tags: | 51 | dashif/specs-builder:latest 52 | ghcr.io/dash-industry-forum/dashif-specs:latest 53 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /.github/workflows/publish-bikeshed.yml: -------------------------------------------------------------------------------- 1 | name: Publish Bikeshed Document 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | paths-ignore: 8 | - 'build-tools/**' 9 | - 'data/boilerplate/**' 10 | - '.github/workflows/build-container.yml' 11 | 12 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 13 | permissions: 14 | contents: read 15 | packages: read 16 | pages: write 17 | id-token: write 18 | 19 | jobs: 20 | build: 21 | runs-on: ubuntu-latest 22 | container: 23 | image: ghcr.io/dash-industry-forum/dashif-specs:latest 24 | credentials: 25 | username: ${{ github.actor }} 26 | password: ${{ secrets.github_token }} 27 | 28 | steps: 29 | - uses: actions/checkout@v4 30 | - name: Build 31 | env: 32 | # Reset OPTS to empty to make sure we are not using 33 | # interactive mode in CI 34 | OPTS: 35 | run: make -f /tools/Makefile 36 | - name: Archive 37 | uses: actions/upload-artifact@v4 38 | with: 39 | name: dist 40 | path: dist/ 41 | 42 | package: 43 | runs-on: ubuntu-latest 44 | needs: build 45 | steps: 46 | - uses: actions/download-artifact@v4 47 | with: 48 | name: dist 49 | path: dist 50 | - uses: actions/upload-pages-artifact@v3 51 | with: 52 | path: dist 53 | 54 | publish: 55 | runs-on: ubuntu-latest 56 | needs: package 57 | steps: 58 | - name: Deploy to GitHub Pages 59 | uses: actions/deploy-pages@v4 60 | -------------------------------------------------------------------------------- /biblio.json: -------------------------------------------------------------------------------- 1 | { 2 | "ATSC3": { 3 | "href": "https://https://www.atsc.org/wp-content/uploads/2017/10/A300-2017-ATSC-3-System-Standard-1.pdf", 4 | "title": "ATSC Standard: A/300:2017 �ATSC3.0 System�", 5 | "publisher": "ATSC" 6 | }, 7 | "DASH-CMAF": { 8 | "aliasOf": "iso23009-1-cdamd1" 9 | }, 10 | "DASH-SystemIDs": { 11 | "href": "https://dashif.org/identifiers/content_protection/", 12 | "title": "DASH-IF registry of DRM System IDs", 13 | "publisher": "DASH Industry Forum" 14 | }, 15 | "HLS": { 16 | "aliasOf": "rfc8216" 17 | }, 18 | "DASH": { 19 | "aliasOf": "MPEGDASH" 20 | }, 21 | "CMAF": { 22 | "aliasOf": "MPEGCMAF" 23 | }, 24 | "LEAP-SECONDS": { 25 | "href": "https://datacenter.iers.org/data/latestVersion/16_BULLETIN_C16.txt", 26 | "title": "IERS Bulletin C (leap second announcements)", 27 | "publisher": "IERS" 28 | }, 29 | "IOP43": { 30 | "href": "https://dash-industry-forum.github.io/docs/DASH-IF-IOP-v4.3.pdf", 31 | "title": "Guidelines for Implementation: DASH-IF Interoperability Points", 32 | "publisher": "DASH-IF" 33 | }, 34 | "IOP5-PART5": { 35 | "href": "https://dashif.org/guidelines/iop-v5#part-5-ad-insertion", 36 | "title": "DASH-IF-IOP-Part5-v5.0.0: Ad Insertion", 37 | "publisher": "DASH-IF" 38 | }, 39 | "IOP5-PART4-LL": { 40 | "href": "https://dashif.org/guidelines/iop-v5/#part-Live-and-low-latency-services", 41 | "title": "Prepublished v5 on Low-Latency Modes for DASH", 42 | "publisher": "DASH-IF" 43 | }, 44 | "LL-REPORT": { 45 | "href": "https://dash-industry-forum.github.io/docs/Report%20on%20Low%20Latency%20DASH.pdf", 46 | "title": "DASH-IF/DVB Report on Low-Latency Live Service with DASH", 47 | "publisher": "DASH-IF" 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /data/boilerplate/dashif/header.include: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | [TITLE] 6 | 7 | 9 | 17 | 28 | 29 | 30 | 34 | 35 | 36 |
37 |

38 |

[TITLE]

39 |

[LONGSTATUS], 40 |

41 |
42 |
43 |

44 |
45 |
46 | 47 |
48 |
49 | 50 | 51 |
52 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DASH-IF Interoperability Points 2 | 3 | This repository contains the issue tracker for the DASH-IF Interoperability Points document (all versions). Report bugs 4 | and proposals as issues. 5 | 6 | ## Documents 7 | 8 | [![Published](https://github.com/Dash-Industry-Forum/DASH-IF-IOP/actions/workflows/publish-bikeshed.yml/badge.svg)](https://github.com/Dash-Industry-Forum/DASH-IF-IOP/actions/workflows/publish-bikeshed.yml) 9 | 10 | * [Live to VoD Conversion](https://dashif.org/DASH-IF-IOP/live2vod/) 11 | - [Live to VoD Conversion - PDF Version](https://dashif.org/DASH-IF-IOP/live2vod.pdf) 12 | 13 | * [MPD Patch](https://dashif.org/DASH-IF-IOP/mpd-patch/) 14 | - [MPD Patch - PDF Version](https://dashif.org/DASH-IF-IOP/mpd-patch.pdf) 15 | 16 | * [Content Steering](https://dashif.org/DASH-IF-IOP/content-steering/) 17 | - [Content Steering - PDF Version](https://dashif.org/DASH-IF-IOP/content-steering.pdf) 18 | 19 | * [Lower Latency and Switching Delay DASH (L3D)](https://dashif.org/DASH-IF-IOP/l3d/) 20 | - [MPD Patch - PDF Version](https://dashif.org/DASH-IF-IOP/l3d.pdf) 21 | 22 | * [Common Media Client Metadata (CMCD) in DASH](https://dashif.org/DASH-IF-IOP/cmcd/) 23 | - [Common Media Client Metadata (CMCD) in DASH - PDF Version](https://dashif.org/DASH-IF-IOP/cmcd.pdf) 24 | 25 | Some chapters of the document are maintained in their own separate repositories: 26 | 27 | * [DASH-IF implementation guidelines: the DASH timing model](https://github.com/Dash-Industry-Forum/Guidelines-TimingModel) 28 | * [DASH-IF implementation guidelines: content protection and security](https://github.com/Dash-Industry-Forum/Guidelines-Security) 29 | 30 | ## Authoring Documentation 31 | 32 | Documentation on how to use Bikeshed and the build pipeline of this repository can be found as a separate document: 33 | 34 | * [Authoring Documentation](https://dashif.org/DASH-IF-IOP/authoring/) 35 | - [Authoring Documentation - PDF Version](https://dashif.org/DASH-IF-IOP/authoring.pdf) 36 | 37 | > [!NOTE] 38 | > The authoring documentation is very much still work on progress! 39 | -------------------------------------------------------------------------------- /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/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/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 | 
118 | Revision: 0.1
119 | Title: DASH-IF IOP Document Authoring
120 | Status: LD
121 | Shortname: authoring
122 | URL: https://dashif.org/Guidelines/master/authoring.html
123 | Group: dashif
124 | 
125 | !Contributor: Thasso Griebel
126 | !Key Word: Authoring
127 | !Related Features:
128 |
129 | 130 | 
131 | path: authoring.md
132 |
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 | 
382 |   graph TD
383 |   A[Client] --> B[Load Balancer]
384 |   B --> C[Server01]
385 |   B --> D[Server02]
386 | 

387 | ```
388 | 
389 | becomes
390 | 
391 | 
392 |   graph TD
393 |   A[Client] --> B[Load Balancer]
394 |   B --> C[Server01]
395 |   B --> D[Server02]
396 | 

397 | 
398 | To create a caption, you can simply wrap a mermaid diagram in a `
`
399 | tag.
400 | 
401 | ```
402 | 

403 |   
404 |     graph TD
405 |     A[Client] --> B[Load Balancer]
406 |     B --> C[Server01]
407 |     B --> D[Server02]
408 |   

409 |   
Example Mermaid diagram.

410 | 

411 | ```
412 | 
413 | becomes
414 | 
415 | 

416 |   
417 |     graph TD
418 |     A[Client] --> B[Load Balancer]
419 |     B --> C[Server01]
420 |     B --> D[Server02]
421 |   

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 |         
475 |       
476 |         
480 |         
484 |         
Animal
472 |         Feet
473 |         Average height
474 |     
Duck
477 |         2
478 |         1 foot
479 |       
Cow
481 |         4
482 |         1.612 meters
483 |       
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 |         
502 |       
503 |         
507 |         
511 |         
Animal
499 |         Feet
500 |         Average height
501 |     
Duck
504 |         2
505 |         1 foot
506 |       
Cow
508 |         4
509 |         1.612 meters
510 |       
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 | 


--------------------------------------------------------------------------------