Screen Reader Accessibility in Java

Use the Aspose.HTML for Java accessibility API to check machine-testable rules related to text alternatives and time-based media. Select WCAG 2.0 guideline 1.1 or 1.2, validate an HTMLDocument, and inspect reported errors and affected HTML elements.

Screen readers convert digital content into synthesized speech or refreshable Braille. Accessible HTML gives assistive technologies meaningful text alternatives, labels, semantics, and media alternatives so users can understand and operate the page.

Aspose.HTML can identify issues covered by the selected accessibility rules, but it does not run a screen reader or determine whether every text alternative accurately communicates the content’s purpose. Combine automated results with manual review and assistive-technology testing.

Check Image Alt Text in Java

The following input contains a labeled password field, a login field whose <label> is not associated through for, an image with descriptive alternative text, and an image with an empty alt value:

Save this source as alt-tag.html:

 1<html>
 2    <body>
 3        <img src="./resourses/login.png" alt="Login icon">
 4
 5        <label>Enter login:</label>
 6        <!-- error: the label is not associated with this input -->
 7        <input type="text" id="login">
 8
 9        <label for="password">Enter password:</label>
10        <input type="password" id="password">
11    
12        <!-- error: this informative image needs meaningful alt text -->
13        <img src="./resourses/sign.png" alt="">
14    </body>
15</html>

For this sample, sign.png is treated as informative, so it needs a meaningful text alternative. An empty alt="" is appropriate when an image is purely decorative and should be ignored by assistive technologies.

To check the document against guideline 1.1, Text Alternatives:

Create a WebAccessibility instance.
Use getPrinciple() and getGuideline() to retrieve guideline 1.1 from principle 1, Perceivable.
Pass the guideline and ValidationBuilder.getAll() to createValidator().
Load alt-tag.html into an HTMLDocument.
Call validate().
Iterate through unsuccessful rule and technique results and print each message and HTMLElement target.

 1// Validate HTML image alt text accessibility with detailed error reporting
 2
 3// Prepare a path to a source HTML file
 4String documentPath = "alt-tag.html";
 5
 6// Create a WebAccessibility instance
 7WebAccessibility webAccessibility = new WebAccessibility();
 8
 9// Get from the rules list Principle "1. Perceivable"
10// by code "1" and get guideline "1.1 Text Alternatives"
11Guideline guideline = webAccessibility.getRules()
12        .getPrinciple("1").getGuideline("1.1");
13
14// Create an accessibility validator - pass the found guideline
15// as parameters and specify the full validation settings
16AccessibilityValidator validator = webAccessibility.createValidator(
17        guideline,
18        ValidationBuilder.getAll()
19);
20
21// Initialize an HTMLDocument object
22final HTMLDocument document = new HTMLDocument(documentPath);
23ValidationResult validationResult = validator.validate(document);
24
25if (!validationResult.getSuccess()) {
26    // Get all the result details
27    for (RuleValidationResult ruleResult : validationResult.getDetails()) {
28        // If the result of the rule is unsuccessful
29        if (!ruleResult.getSuccess()) {
30            // Get an errors list
31            for (ITechniqueResult result : ruleResult.getErrors()) {
32                // Check the type of the erroneous element, in this case,
33                // we have an error in the HTML Element
34                if (result.getError().getTarget().getTargetType() == TargetTypes.HTMLElement) {
35                    HTMLElement rule = (HTMLElement) result.getError().getTarget().getItem();
36
37                    System.out.println(String.format("Error in rule %s : %s",
38                            result.getRule().getCode(),
39                            result.getError().getErrorMessage()
40                    ));
41
42                    System.out.println(String.format("HTML Element: %s",
43                            rule.getOuterHTML()
44                    ));
45                }
46            }
47        }
48    }
49}

Example_CheckAltText.java hosted with ❤ by GitHub

For the supplied HTML, the program reports the empty text alternative and the unassociated form label. Its console output can include:

1Error in rule H37 : Img element missing an alt attribute. The value of this attribute is referred to as "alt text".
2HTML Element: <img src="./resourses/sign.png" alt="">
3Error in rule H44 : Check that the label element contains for attribute.
4HTML Element: <label>Enter login:</label>
5Error in rule H65 : Check that the title attribute identifies the purpose of the control and that it matches the apparent visual purpose.
6HTML Element: <input type="text" id="login">
7Error in rule F65 : Absence of an alt attribute or text alternative on img elements, area elements, and input elements of type "image".
8HTML Element: <img src="./resourses/sign.png" alt="">

Check Multimedia Accessibility in Java

This example selects guideline 1.2, Time-based Media, loads a remote webpage, and inspects unsuccessful results associated with HTML elements:

Retrieve guideline 1.2 from principle 1, Perceivable.
Create an accessibility validator for that guideline with ValidationBuilder.getAll().
Load the remote page into an HTMLDocument.
Validate the loaded document and iterate through unsuccessful rule and technique results.
Print the technique code, error message, and affected HTML markup when the target is an HTMLElement.

 1// Validate HTML for multimedia accessibility using Java
 2
 3// Initialize a WebAccessibility container
 4WebAccessibility webAccessibility = new WebAccessibility();
 5
 6// Get from the rules list Principle "1.Perceivable" by code "1"
 7// and get guideline "1.2 Time-based Media"
 8Guideline guideline = webAccessibility.getRules()
 9        .getPrinciple("1").getGuideline("1.2");
10
11// Create an accessibility validator, pass the found guideline
12// as parameters, and specify the full validation settings
13AccessibilityValidator validator = webAccessibility.createValidator(
14        guideline,
15        ValidationBuilder.getAll()
16);
17
18// Initialize an HTMLDocument object
19final HTMLDocument document = new HTMLDocument("https://www.youtube.com/watch?v=Yugq1KyZCI0");
20ValidationResult validationResult = validator.validate(document);
21
22// Checking for success
23if (!validationResult.getSuccess()) {
24    // Get all result details
25    for (RuleValidationResult ruleResult : validationResult.getDetails()) {
26        // If the result of the rule is unsuccessful
27        if (!ruleResult.getSuccess()) {
28            // Get an errors list
29            for (ITechniqueResult result : ruleResult.getErrors()) {
30                // Check the type of the erroneous element
31                if (result.getError().getTarget().getTargetType() == TargetTypes.HTMLElement) {
32                    HTMLElement rule = (HTMLElement) result.getError().getTarget().getItem();
33
34                    System.out.println(String.format("Error in rule %s : %s",
35                            result.getRule().getCode(),
36                            result.getError().getErrorMessage()
37                    ));
38
39                    System.out.println(String.format("HTML Element: %s",
40                            rule.getOuterHTML()
41                    ));
42                }
43            }
44        }
45    }
46}

Example_CheckMultimediaAccessibility.java hosted with ❤ by GitHub

The validator evaluates the HTML loaded by Aspose.HTML against machine-testable rules. It does not play the media or simulate a screen reader, and client-side changes to a remote page can affect which content is available for checking.

Check a Specific Time-Based Media Criterion

To narrow the validation scope, retrieve a specific criterion from guideline 1.2. The following fragment selects criterion 1.2.3, Audio Description or Media Alternative (Prerecorded):

 1    // Get the principle "1. Perceivable" by its code and retrieve the guideline "1.2 Time-based Media"
 2    Guideline guideline = webAccessibility.getRules().getPrinciple("1").getGuideline("1.2");
 3
 4    // Get the specific criterion: 1.2.3 Audio Description or Media Alternative (Prerecorded)
 5    Criterion criterion = guideline.getCriterion("1.2.3");
 6
 7    // Create an accessibility validator with the found criterion and full validation settings
 8    AccessibilityValidator validator = webAccessibility.createValidator(criterion, ValidationBuilder.getAll());
 9
10    ...

Captions, transcripts, audio descriptions, and media alternatives address different user needs. Select the relevant criteria for automated checks and manually verify that the alternatives are accurate, synchronized, and equivalent to the important media content.

Common Screen Reader Accessibility Issues

Issue	Explanation and fix
Treating any non-empty `alt` value as sufficient	Alternative text must communicate the image’s purpose in context. Review its meaning manually after checking that the attribute exists.
Treating `alt=""` as an error for every image	Empty alternative text is appropriate for a purely decorative image. Informative and functional images need a meaningful text alternative.
Adding visible label text without associating it with a control	Match the label’s `for` value to the control’s `id`, or wrap the control in its `<label>`.
Assuming a remote-page check includes every dynamic state	Client-side content may not be represented in the loaded DOM. Test important states and user interactions separately.
Treating automated validation as a screen reader test	Automated rules find detectable markup issues. Test the page with keyboard navigation and relevant assistive technologies as well.

FAQ

How do I check image alt text in Java?

Retrieve WCAG 2.0 guideline 1.1, create an AccessibilityValidator for that guideline, and validate the HTMLDocument. Inspect unsuccessful technique results and their HTMLElement targets.

Is an empty alt attribute always an accessibility error?

No. Use alt="" for an image that is purely decorative and should be ignored by assistive technologies. Informative and functional images require an alternative that conveys their purpose.

Can Aspose.HTML check multimedia accessibility?

Aspose.HTML can evaluate machine-testable rules selected under guideline 1.2, Time-based Media. Manually verify the accuracy, timing, and equivalence of captions, transcripts, audio descriptions, and other alternatives.

WCAG Techniques Referenced

The WCAG technique catalog also contains techniques for legacy elements such as <applet>, <embed>, and <noembed>. Prefer current HTML elements and accessibility patterns for new content.

Add Alt Text to Images in Java – find missing alt attributes, add reviewed descriptions, and save the updated HTML.
Accessibility Validator – create validators and select rule scopes.
Web Accessibility Rules – retrieve principles, guidelines, criteria, and techniques.
Validation Results – inspect rule and technique results.
Web Accessibility Check – collect errors, warnings, and affected elements.
Color Contrast Accessibility – validate text contrast criteria.

Other Platforms

Screen Reader Accessibility in C# – review alternative-text patterns and .NET accessibility checks.
Multimedia Accessibility in C# – review captions, transcripts, and audio-description guidance.

Try the Online Web Accessibility Checker

Use the free online Web Accessibility Checker for a quick page scan before implementing or extending Java accessibility checks.

Validation Results Check Color Contrast

Screen Reader Accessibility in Java