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 kinddescriptions标准用法、WebVTT 描述文件格式、React 组件落地方式、描述文案编写规范与验证清单让你能在实际项目中为盲人用户提供与视听者同等的视频内容体验。为什么需要音频描述盲人用户正在错过什么Blind users miss critical plot points, product demos, and on-screen information thats 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 kinddescriptions提供独立描述轨道HTML5 的track元素是承载音频描述的标准机制。规则文档给出的最小可用示例video controls source srcproduct-demo.mp4 typevideo/mp4 !-- Captions for deaf users -- track kindcaptions srccaptions-en.vtt srclangen labelEnglish !-- Audio descriptions for blind users -- track kinddescriptions srcdescriptions-en.vtt srclangen labelEnglish Audio Description /video关键点拆解kinddescriptions声明该轨道是音频描述轨道这是与kindcaptions字幕最本质的区别src指向 WebVTT 格式的描述文件见下一节srclangen声明轨道语言便于浏览器和辅助技术筛选label在播放器 UI 中展示给用户的轨道名称应当清晰可辨如 English Audio Description。从实现原理看kinddescriptions轨道由浏览器/播放器负责在对话间隙混入旁白音轨。仓库 video-accessibility 规则的完整示例 展示了更完整的搭配在同一个video内同时提供多语言字幕kindcaptions其中一条加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 useRefHTMLVideoElement(null) return ( div classNamevideo-container video ref{videoRef} controls poster{poster} aria-describedbyvideo-description source src{src} typevideo/mp4 / {captions ( track kindcaptions src{captions} srcLangen labelEnglish Captions default / )} {descriptions ( track kinddescriptions src{descriptions} srcLangen labelAudio Description / )} /video {descriptions ( button onClick{() setDescriptionsEnabled(!descriptionsEnabled)} aria-pressed{descriptionsEnabled} {descriptionsEnabled ? Disable : Enable} Audio Descriptions /button )} p idvideo-description classNamesr-only Video with audio descriptions available. Use the Audio Descriptions button to enable. /p /div ) }实现要点条件渲染轨道captions与descriptions均为可选属性没有对应文件时不输出trackaria-pressed切换按钮通过aria-pressed状态向屏幕阅读器通告开关状态aria-describedby与 sr-only 文本video通过aria-describedby关联到一段仅供屏幕阅读器读取的说明文字向辅助技术用户预先告知本视频提供音频描述可通过按钮开启poster属性为尚未加载的视频帧提供封面避免纯空白区域。说明规则文档示例中的useState状态用于驱动按钮文案切换描述轨道本身的启用最终由浏览器/播放器根据用户选择播放。在实际工程中可以进一步通过 DOM API如videoRef.current.textTracks同步启用状态形成更完整的开关—状态—界面闭环。扩展方案对话间隙太短时的扩展描述版本标准的kinddescriptions轨道要求描述必须塞进对白间隙中。当画面信息密集、间隙不足时规则文档给出的替代方案是提供两个版本的视频标准版与带停顿的扩展描述版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 rolegroup aria-labelVideo version selection label input typeradio namevideo-version checked{!useExtended} onChange{() setUseExtended(false)} / Standard version /label label input typeradio namevideo-version checked{useExtended} onChange{() setUseExtended(true)} / Version with audio descriptions /label /div video controls key{useExtended ? extended : standard} source src{useExtended ? extendedSrc : standardSrc} typevideo/mp4 / /video /div ) }设计要点用rolegroup配合aria-labelVideo 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 dont 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 kinddescriptions接入 → 编写描述文案 → 自动化 手动双重验证的流程落地本规则并在每个迭代中把视频媒体纳入无障碍评审范围。【免费下载链接】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），仅供参考 Front-End-Checklist 无障碍指南：为视频添加音频描述（Audio Descriptions）的完整实现方案
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 kinddescriptions标准用法、WebVTT 描述文件格式、React 组件落地方式、描述文案编写规范与验证清单让你能在实际项目中为盲人用户提供与视听者同等的视频内容体验。为什么需要音频描述盲人用户正在错过什么Blind users miss critical plot points, product demos, and on-screen information thats 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 kinddescriptions提供独立描述轨道HTML5 的track元素是承载音频描述的标准机制。规则文档给出的最小可用示例video controls source srcproduct-demo.mp4 typevideo/mp4 !-- Captions for deaf users -- track kindcaptions srccaptions-en.vtt srclangen labelEnglish !-- Audio descriptions for blind users -- track kinddescriptions srcdescriptions-en.vtt srclangen labelEnglish Audio Description /video关键点拆解kinddescriptions声明该轨道是音频描述轨道这是与kindcaptions字幕最本质的区别src指向 WebVTT 格式的描述文件见下一节srclangen声明轨道语言便于浏览器和辅助技术筛选label在播放器 UI 中展示给用户的轨道名称应当清晰可辨如 English Audio Description。从实现原理看kinddescriptions轨道由浏览器/播放器负责在对话间隙混入旁白音轨。仓库 video-accessibility 规则的完整示例 展示了更完整的搭配在同一个video内同时提供多语言字幕kindcaptions其中一条加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 useRefHTMLVideoElement(null) return ( div classNamevideo-container video ref{videoRef} controls poster{poster} aria-describedbyvideo-description source src{src} typevideo/mp4 / {captions ( track kindcaptions src{captions} srcLangen labelEnglish Captions default / )} {descriptions ( track kinddescriptions src{descriptions} srcLangen labelAudio Description / )} /video {descriptions ( button onClick{() setDescriptionsEnabled(!descriptionsEnabled)} aria-pressed{descriptionsEnabled} {descriptionsEnabled ? Disable : Enable} Audio Descriptions /button )} p idvideo-description classNamesr-only Video with audio descriptions available. Use the Audio Descriptions button to enable. /p /div ) }实现要点条件渲染轨道captions与descriptions均为可选属性没有对应文件时不输出trackaria-pressed切换按钮通过aria-pressed状态向屏幕阅读器通告开关状态aria-describedby与 sr-only 文本video通过aria-describedby关联到一段仅供屏幕阅读器读取的说明文字向辅助技术用户预先告知本视频提供音频描述可通过按钮开启poster属性为尚未加载的视频帧提供封面避免纯空白区域。说明规则文档示例中的useState状态用于驱动按钮文案切换描述轨道本身的启用最终由浏览器/播放器根据用户选择播放。在实际工程中可以进一步通过 DOM API如videoRef.current.textTracks同步启用状态形成更完整的开关—状态—界面闭环。扩展方案对话间隙太短时的扩展描述版本标准的kinddescriptions轨道要求描述必须塞进对白间隙中。当画面信息密集、间隙不足时规则文档给出的替代方案是提供两个版本的视频标准版与带停顿的扩展描述版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 rolegroup aria-labelVideo version selection label input typeradio namevideo-version checked{!useExtended} onChange{() setUseExtended(false)} / Standard version /label label input typeradio namevideo-version checked{useExtended} onChange{() setUseExtended(true)} / Version with audio descriptions /label /div video controls key{useExtended ? extended : standard} source src{useExtended ? extendedSrc : standardSrc} typevideo/mp4 / /video /div ) }设计要点用rolegroup配合aria-labelVideo 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 dont 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 kinddescriptions接入 → 编写描述文案 → 自动化 手动双重验证的流程落地本规则并在每个迭代中把视频媒体纳入无障碍评审范围。【免费下载链接】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），仅供参考