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

Đang mở
  • Có gì không ổn?
#15,141 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
54/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
html, javascript
Lĩnh vực
accessibility

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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...
Ngôn ngữ chính
JavaScript
Star
6.1k
Fork
478
Merge trung bình
17 giờ 26 phút
Pull request đã merge (30 ngày)
126

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của quarto-dev/quarto-cli

Tất cả issue của quarto-dev/quarto-cli

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.