a11y: the `video` shortcode cannot add captions to a local video file

Ouverte
  • Quelque chose ne va pas ?
#15,141 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
54/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
html, javascript
Domaine
accessibility

Piste de recherche

Read the video shortcode handler at src/resources/extensions/quarto/video/video.lua, especially the metadata handling around line 314, and trace how local media files are copied to website output. Render the supplied captions example and check that the output includes a WebVTT track and that the track file is copied to _site/; apply the same check to the proposed descriptions track.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

accessibility enhancement shortcodes

I have:

  • searched the issue tracker for similar issues
  • installed the latest version of Quarto CLI
  • formatted my issue following the Bug Reports guide

Bug description

For a local video file, the video shortcode emits a Video.js player with one <source> and no <track>. The shortcode has no argument for a caption track or a description track. As a result, an author who uses the shortcode cannot give a local video captions or an audio description.

Hosted videos (YouTube, Vimeo, Brightcove) do not have this problem. Their players show the captions that the host gives.

This gap fails these criteria for local videos:

An author workaround is to add raw HTML <video> element with <track> children. This workaround has two problems: no Video.js player (unless the page uses a video shortcode elsewhere); the author needs to list the .vtt files in resources to ensure they end up in _site/.

Proposal

Add a captions argument that takes a WebVTT file, with two optional arguments for the language and the menu label:

{{< video demo.mp4 title="Demo" captions="demo.vtt" captions-lang="en" captions-label="English" >}}

The shortcode then adds a track to the player:

<video ...>
  <source src="demo.mp4">
  <track kind="captions" src="demo.vtt" srclang="en" label="English">
</video>

A descriptions argument, with descriptions-lang and descriptions-label, adds a kind="descriptions" track in the same way.

For the defaults:

  • If captions-lang is not given, the shortcode can use the document lang. The shortcode handler already receives the document metadata (video.lua#L314).
  • If captions-label is not given, the Video.js captions menu shows the language code, for example "en Captions". If the track has no language either, the menu shows "Unknown Captions". A label is better, so the documentation can recommend one.

These arguments give one track of each kind, which is sufficient for accessibility. Tracks in more than one language need a different syntax, and can come later.

The Video.js that Quarto ships (7.20.2) already supports <track> children. It reads them when the player starts, so the shortcode needs no extra JavaScript (Video.js text tracks guide). The track file must be WebVTT.

The shortcode must also make sure that the track files go to the output directory. In a website project, the render copies demo.mp4 to _site/, but it does not copy demo.vtt.

AI tools helped with this investigation. All findings come from a local clone of quarto-cli, and I rendered the example to confirm them.

Steps to reproduce

Put any demo.mp4 and this demo.vtt next to the document:

WEBVTT

00:00.000 --> 00:02.000
Hello

Then render this document:

---
title: Video captions
---

{{< video demo.mp4 title="Demo" captions="demo.vtt" >}}

Actual behavior

The output has no <track> element.

Expected behavior

The output has a <track> element. The player can show the captions.

Your environment

  • IDE: Positron 2026.11.0 (build 76). I rendered from the terminal.
  • OS: macOS 27.0.1 (build 26A434)

Quarto check output

Quarto 1.11.6
[✓] Checking environment information...
      Quarto cache location: /Users/charlottewickham/Library/Caches/quarto
      Project: none found (single-file mode)
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.10.0: OK
      Dart Sass version 1.101.0: OK
      Deno version 2.7.14: OK
      Typst version 0.15.1: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.11.6
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.04
      Chrome Headless Shell: 150.0.7871.115
      VeraPDF: 1.28.2

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/charlottewickham/Library/TinyTeX/bin/universal-darwin
      Version: 2026

[✓] Checking Chrome Headless....................OK
      Using: Chrome Headless Shell installed by Quarto
      Path: /Users/charlottewickham/Library/Application Support/quarto/chrome-headless-shell/chrome-headless-shell-mac-arm64/chrome-headless-shell
      Version: 150.0.7871.115

[✓] Checking basic markdown render....OK

[✓] Checking R installation...........OK
      Version: 4.6.0
      Path: /Library/Frameworks/R.framework/Versions/4.6/Resources
      LibPaths:
        - /Users/charlottewickham/Library/R/arm64/4.6/library
        - /Library/Frameworks/R.framework/Versions/4.6/Resources/library
      knitr: 1.51
      rmarkdown: 2.31

[✓] Checking Knitr engine render......OK

[✓] Checking Python 3 installation....OK
      Version: 3.12.2
      Path: /Users/charlottewickham/.pyenv/versions/3.12.2/bin/python
      Jupyter: 5.9.1
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking Julia installation...
Langage dominant
JavaScript
Étoiles
6.1k
Forks
478
Merge moyen
17 h 7 min
PR mergées (30 j)
112

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de quarto-dev/quarto-cli

Toutes les issues de quarto-dev/quarto-cli

Issues similaires

Plus d'issues JavaScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.