Front-End-Checklist 无障碍指南：为视频添加音频描述（Audio Descriptions）的完整实现方案
【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist
在纯视觉信息无法通过现有音轨传达的视频中，音频描述（Audio Descriptions）通过额外旁白向盲人和低视力用户叙述画面内容，是 Web 媒体无障碍（Media Accessibility）的核心环节。本篇指南以 Front-End-Checklist 仓库中的 audio-descriptions 规则 为主体，结合仓库内对应的 规则内容文件 与 SKILL.md 使用说明，完整讲解音频描述的实现时机、
<track kind="descriptions">标准用法、WebVTT 描述文件格式、React 组件落地方式、描述文案编写规范与验证清单，让你能在实际项目中为盲人用户提供与视听者同等的视频内容体验。
为什么需要音频描述：盲人用户正在错过什么
Blind users miss critical plot points, product demos, and on-screen information that's only shown visually—audio descriptions provide equal access to the complete experience.
在 Front-End-Checklist 的 audio-descriptions 规则元数据 中，这一规则的whyItMatters字段给出了最凝练的回答：盲人用户会错过关键的剧情转折、产品演示以及仅在视觉上呈现的屏幕信息。音频描述（Audio Descriptions）通过旁白把"只能看"的信息转化为"可以听"的信息，从而为所有人提供对完整视频内容的平等访问。
从仓库的 Accessibility Essentials 检查清单 可以看到，audio-descriptions与video-captions一同被列入核心媒体无障碍基线（见该清单 frontmatter 中的rules列表），并且"Missing captions or audio descriptions on important video content"被明确列为常见错误之一。这说明在项目中，音频描述与字幕（Captions）是成对出现的媒体无障碍需求：
- 字幕（Captions）：为耳聋和听障用户服务，呈现对白与声音信息；
- 音频描述（Audio Descriptions）：为盲人和低视力用户服务，叙述画面中不可从音轨获得的信息。
规则文档同时指出，relatedRules 中与audio-descriptions常被一起评审的还包括video-captions、autoplay-media与video-accessibility，它们同属accessibility/media领域，建议在实际项目中合并开展无障碍评审。
什么时候需要音频描述：判定清单
不是所有视频都需要音频描述。规则文档给出了一张明确的判定表，核心判断标准是：画面中是否存在"仅视觉呈现"的信息。
| 视觉内容 | 需要描述吗？ |
|---|---|
| 角色动作/反应 | 是 |
| 场景切换/地点变化 | 是 |
| 屏幕上的文字/图形 | 是 |
| 传达情感的面部表情 | 是 |
| 无视觉动作的讲话镜头 | 否 |
| 纯音频内容（如播客） | 否 |
判定方法（对应仓库 规则文件中的 check prompt）：先找出那些"画面信息无法从音轨获得"的视频（如动作、表情、场景变化、屏幕文字），再验证该视频是否提供了音频描述，或者视觉内容是否已被对白本身完整叙述。如果旁白已经把关键视觉信息讲清楚了，就不需要额外的描述轨道。
标准实现：用<track kind="descriptions">提供独立描述轨道
HTML5 的<track>元素是承载音频描述的标准机制。规则文档给出的最小可用示例：
<video controls> <source src="product-demo.mp4" type="video/mp4"> <!-- Captions for deaf users --> <track kind="captions" src="captions-en.vtt" srclang="en" label="English"> <!-- Audio descriptions for blind users --> <track kind="descriptions" src="descriptions-en.vtt" srclang="en" label="English Audio Description"> </video>关键点拆解：
kind="descriptions"：声明该轨道是音频描述轨道，这是与kind="captions"（字幕）最本质的区别；src：指向 WebVTT 格式的描述文件（见下一节）；srclang="en"：声明轨道语言，便于浏览器和辅助技术筛选；label：在播放器 UI 中展示给用户的轨道名称，应当清晰可辨，如 "English Audio Description"。
从实现原理看，kind="descriptions"轨道由浏览器/播放器负责在对话间隙混入旁白音轨。仓库 video-accessibility 规则的完整示例 展示了更完整的搭配：在同一个<video>内同时提供多语言字幕（kind="captions"，其中一条加default属性作为默认）与音频描述轨道，并配合<figure>/<figcaption>与aria-describedby提供文字描述兜底。
描述轨道的常见误区
在规则文档的 Exceptions 章节 中强调：Logo、纯装饰性文字效果以及作为文档说明用途的截图，只要其无障碍替代信息被合理提供，可以作为例外；同时，如果附近已有其他机制清晰提供了等价信息，就不应强行要求冗余的 alt 文本、字幕或转写文本。若一个媒体资源同时违反多条规则，应优先修复"对辅助技术用户理解内容阻碍最大"的那一条。
WebVTT 描述文件格式：为时间轴编写旁白
音频描述轨道的内容存放在 WebVTT 文件中。规则文档给出的标准格式示例：
WEBVTT 00:00:03.000 --> 00:00:06.000 A woman in business attire enters a modern office lobby. 00:00:15.000 --> 00:00:18.000 She approaches the reception desk where a man looks up from his computer. 00:00:32.000 --> 00:00:35.000 On-screen text reads: "Three months later" 00:01:05.000 --> 00:01:08.000 Close-up of her face showing concern as she reads the document.要点说明：
- 文件必须以
WEBVTT开头； - 每条描述包含时间戳区间（
HH:MM:SS.mmm --> HH:MM:SS.mmm）和描述文本； - 描述只覆盖需要解释的画面片段，时间戳必须落在对白间隙内，避免与重要音频重叠；
- 屏幕上的文字应按原文叙述，例如上例中的
On-screen text reads: "Three months later"。
作为对比，仓库 video-captions 规则 对应的字幕文件同样使用 WebVTT 格式，但内容面向"听见"而非"看见"——例如[Background music playing]、[door closes]这类非言语声音标记。两者在同一个时间轴上分工明确：字幕负责声音，描述负责画面。
React 落地：可切换的音频描述播放器组件
规则文档提供了一套 React/TSX 实现，将descriptions作为可选属性传入，并配合一个aria-pressed切换按钮，让用户能显式开关描述轨道：
interface VideoPlayerProps { src: string captions?: string descriptions?: string poster?: string } function AccessibleVideoPlayer({ src, captions, descriptions, poster }: VideoPlayerProps) { const [descriptionsEnabled, setDescriptionsEnabled] = useState(false) const videoRef = useRef<HTMLVideoElement>(null) return ( <div className="video-container"> <video ref={videoRef} controls poster={poster} aria-describedby="video-description" > <source src={src} type="video/mp4" /> {captions && ( <track kind="captions" src={captions} srcLang="en" label="English Captions" default /> )} {descriptions && ( <track kind="descriptions" src={descriptions} srcLang="en" label="Audio Description" /> )} </video> {descriptions && ( <button onClick={() => setDescriptionsEnabled(!descriptionsEnabled)} aria-pressed={descriptionsEnabled} > {descriptionsEnabled ? 'Disable' : 'Enable'} Audio Descriptions </button> )} <p id="video-description" className="sr-only"> Video with audio descriptions available. Use the Audio Descriptions button to enable. </p> </div> ) }实现要点：
- 条件渲染轨道：
captions与descriptions均为可选属性，没有对应文件时不输出<track>； aria-pressed：切换按钮通过aria-pressed状态向屏幕阅读器通告开关状态；aria-describedby与 sr-only 文本：<video>通过aria-describedby关联到一段仅供屏幕阅读器读取的说明文字，向辅助技术用户预先告知"本视频提供音频描述，可通过按钮开启"；poster属性：为尚未加载的视频帧提供封面，避免纯空白区域。
说明：规则文档示例中的
useState状态用于驱动按钮文案切换；描述轨道本身的启用最终由浏览器/播放器根据用户选择播放。在实际工程中，可以进一步通过 DOM API（如videoRef.current.textTracks）同步启用状态，形成更完整的"开关—状态—界面"闭环。
扩展方案：对话间隙太短时的"扩展描述版本"
标准的kind="descriptions"轨道要求描述必须塞进对白间隙中。当画面信息密集、间隙不足时，规则文档给出的替代方案是提供两个版本的视频：标准版与带停顿的扩展描述版（Extended Description Video）。
// Provide two versions of the video function VideoWithDescriptionChoice({ standardSrc, extendedSrc }: { standardSrc: string extendedSrc: string }) { const [useExtended, setUseExtended] = useState(false) return ( <div> <div role="group" aria-label="Video version selection"> <label> <input type="radio" name="video-version" checked={!useExtended} onChange={() => setUseExtended(false)} /> Standard version </label> <label> <input type="radio" name="video-version" checked={useExtended} onChange={() => setUseExtended(true)} /> Version with audio descriptions </label> </div> <video controls key={useExtended ? 'extended' : 'standard'}> <source src={useExtended ? extendedSrc : standardSrc} type="video/mp4" /> </video> </div> ) }设计要点：
- 用
role="group"配合aria-label="Video version selection"将两个单选按钮组织为语义化的分组； - 通过
key强制 React 在切换版本时重建<video>元素，确保重新加载对应资源； - 扩展版视频在拍摄/剪辑阶段就预留了描述旁白的停顿空间，描述信息直接混入音轨，因此不需要额外的
<track>。
该方案与规则文档"提供带停顿的扩展版本"的修复建议（见 fix prompt）完全对应；第三种备选思路是把视觉描述直接融入主旁白/对白之中，这需要制作方在内容层面介入。
如何写出好的描述文案：具体、客观、传达信息
描述的质量直接决定无障碍体验的成败。规则文档给出了三组"坏 vs 好"的对照示例：
❌ Bad: "A person is there." ✅ Good: "Sarah enters the room looking worried." ❌ Bad: "Something happens on screen." ✅ Good: "The graph shows sales dropping 40% over three months." ❌ Bad: "He reacts." ✅ Good: "Marcus slams his fist on the table in frustration."写作准则可以归纳为：
- 具体而非笼统：避免 "a person is there" 这类零信息描述，给出姓名、动作、情绪；
- 传达数据与含义：屏幕图表应陈述实际数据变化（"sales dropping 40% over three months"），而非"屏幕上发生了点什么"；
- 动作细节化：把 "he reacts" 扩充为可想象的画面 "Marcus slams his fist on the table in frustration"；
- 客观中立：描述看到的事实（行为与表情），不做主观解读；
- 塞进间隙：描述需精炼到能容纳在对白空隙中，必要时采用上述扩展版本方案。
验证与评审：如何确认音频描述真的可用
规则文档将验证拆分为自动化与手动两个层级。
自动化检查
使用浏览器无障碍工具、axe、Lighthouse 或等价工具，对具有代表性的渲染状态（representative rendered state）运行检查。对应仓库 SKILL.md 中的Code Review指引：审查渲染后的标记与交互状态，找出违反规则的精确元素、角色、标签、焦点行为或键盘交互，并说明如何通过浏览器无障碍工具或辅助技术验证修复。
手动检查清单
- Watch video with eyes closed—can you follow the story? - Verify description track appears in player controls - Check descriptions fit in gaps between dialogue - Ensure descriptions don't overlap important audio- 闭眼测试：闭眼观看视频，能否完整跟上故事情节？这是最直观的验收标准；
- 轨道可见性：描述轨道必须出现在播放器控制项中，用户能够发现并选择它；
- 间隙适配：描述必须刚好落在对白之间，不打断对白；
- 音频不重叠：描述旁白不得与重要音效、音乐或对白重叠。
在项目的 Accessibility Essentials 检查清单 中，媒体无障碍还建议配合其他测试手段（键盘全程导航、VoiceOver/NVDA/JAWS 等屏幕阅读器实测、axe/WAVE 浏览器扩展、对比度检查等）组合验证，因为音频描述是否真正生效最终取决于辅助技术与播放器的协同。
在 Front-End-Checklist 项目中的定位与使用
本规则在仓库中对应以下资源，可以互相印证、配套查阅：
- 规则内容文件：packages/content/rules/en/accessibility/audio-descriptions.mdx —— 含完整 frontmatter 元数据（优先级 medium、难度 intermediate、预计耗时 30 分钟、类别 accessibility/html、子类别 media），以及 check/fix/explain/codeReview 四类提示词；
- 技能说明：skills/audio-descriptions/SKILL.md —— 面向审查场景的快速参考，说明"先检查原生语义，再检查键盘行为、焦点流、无障碍名称与屏幕阅读器输出"；
- 配套检查清单：packages/content/checklists/en/accessibility-essentials.mdx —— 将
audio-descriptions列为无障碍基线的核心条目之一； - 关联规则：video-captions（字幕）、
autoplay-media与video-accessibility，它们共同构成accessibility/media领域的完整评审闭环。
实际项目中建议按"判定需求 → 编写 WebVTT 描述文件 → 通过<track kind="descriptions">接入 → 编写描述文案 → 自动化 + 手动双重验证"的流程落地本规则，并在每个迭代中把视频媒体纳入无障碍评审范围。
【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
