Outloud

Outloud 是一个跨平台 PDF 无障碍辅助检查工具，可在终端、CI 流程和浏览器中运行，支持 PDF/UA-1 和 WCAG 2.2 标准。它不仅能完成现有验证工具的检查项，还能在验证器力所不能及的地方发现问题——比如一张图片的替代文字内容其实是「IMG_2041.jpg」这样毫无意义的文件名，或者一个被标记为装饰性的句子实际上包含了关键信息。

项目简介

PDF 无障碍辅助（Accessibility）检查对于视障用户能否顺利使用文档至关重要。传统解决方案 PAC 只支持 Windows 桌面环境，veraPDF 是面向合规检测实验室的 Java 工具，两者在实际开发和 CI 场景中使用起来都不够轻便。更重要的是，它们只能验证「键是否存在」——图片有没有 alt 属性？有，通过；表格有没有表头单元格？有，通过——但它们无法告诉你那张图片的 alt 属性里填的其实是乱码，表格的表头单元格是空的，整个屏幕阅读器播报出来的信息毫无意义。Outloud 正是针对这个空白而生的。

核心功能

1. PDF/UA-1 合规性检查：验证 PDF 文件是否符合 ISO 14289-1（PDF/UA）标准，这是视障用户使用辅助技术访问 PDF 的基础要求。

2. WCAG 2.2 可访问性检查：在网页内容无障碍指南（WCAG）的框架下检查 PDF 的结构语义是否符合要求。

3. 超越验证器的深度语义检查：不仅检查键是否存在，还深入分析替代文字是否具有实际描述意义、表头是否为空、哪些被标记为装饰性的元素实际上含有重要内容等。

4. 终端直接运行：无需安装 Java、无需 Windows、无需桌面环境，在终端输入一条命令即可完成检查。

5. CI 集成支持：可将检查无缝嵌入 CI 流水线，在每次提交或合并请求时自动验证 PDF 内容的可访问性。

6. 本地浏览器查看：提供图形化界面，直接在浏览器中打开文件并展示发现的问题。

7. 完全本地运行：没有任何数据上传步骤，文件从不离开用户的机器。

技术实现

Outloud 的核心逻辑在于「语义验证」而非「结构验证」。传统的 PAC 和 veraPDF 采用的是结构化校验：检查 PDF 字典中是否存在必要的键值对（如 /Alt 键是否存在）。这种方法在大多数情况下有效，但在以下场景中会失效：

第一种失效场景是「存在但无意义」。比如一张图片的 /Alt 属性值是「IMG_2041.jpg」，验证器看到键存在就判定通过，但屏幕阅读器播报出来的内容对用户毫无价值。Outloud 通过分析属性值的实际内容，过滤掉这类「形式合规、实质无效」的情况。

第二种失效场景是「结构与语义不匹配」。比如一个表格有正确的表头单元格结构，但表头单元格内容为空，导致屏幕阅读器在遍历表格时把所有单元格的值都播报为「无标题」，用户根本无法理解数据的含义。Outloud 会对表格结构进行深度遍历，检测这类语义缺失问题。

技术栈方面，Outloud 使用 Python 开发，通过 pipx 或 uv 即可完成安装，依赖极简，无需复杂的运行时环境。

快速上手

1. 安装：在终端执行 pipx install outloud（或 uv tool install outloud），无需管理员权限。

2. 运行检查：执行 outloud report.pdf，工具会立即对指定 PDF 文件进行扫描。

3. 查看图形报告：执行 outloud --view，或直接打开图形界面将 PDF 文件拖入窗口，即可看到完整的问题清单。

4. 集成 CI：在项目的 CI 配置文件中加入 outloud report.pdf 命令，即可在每次构建时自动验证 PDF 可访问性。

适用人群

• PDF 内容创作者和发布者：在发布文档前进行自查，确保视障用户能顺利访问内容。

• 无障碍工程师和质量保证团队：将检查自动化嵌入 CI 流程，保证每个交付的 PDF 都经过可访问性验证。

• 残障权益倡导者和公益组织：批量检测内部和外部文档的可访问性水平，推动无障碍标准落地。

• 使用屏幕阅读器的个人用户：对自己收到的 PDF 文件进行预先检测，了解文档是否对自己友好。