Matterhorn 28-015 · PDF/UA-1 UA1:7.18.6.2-1

PDF video or audio with no /Alt: describing a media clip

Media clips require an /Alt array giving a text description.

What a screen reader actually does

The media is announced with no description.

Three descriptions, three places

A video in a PDF can carry three pieces of descriptive text, and they are easy to confuse because they all look like “alt text”:

12 0 obj
<< /Type /Annot /Subtype /Screen
   /Contents (Walkthrough video)              ← the annotation: 28-004
   /StructParent 4                            ← its <Annot> element may have /Alt too
   /A << /S /Rendition /OP 0 /AN 12 0 R
         /R << /S /MR
               /C << /S /MCD
                     /D 14 0 R
                     /CT (video/mp4)
                     /Alt [ (en-GB)
                            (Video, 2 min 10 s: completing section 3 of the
                             form, with narration. Transcript on page 4.) ]
                  >>                          ← the media clip: this condition
            >>
      >>
>>

• /Contents on the annotation names the annotation — the play area on the page. Missing, it is 28-004.
• /Alt on the <Annot> structure element is the alternate text a screen reader is given for that element in the tag tree.
• /Alt in the media clip data dictionary describes the media data itself, and ISO 32000-1 defines it as the text to use when the clip cannot be played. That is the one this condition is about.

PDF/UA-1 clause 7.18.6.2 requires it. ISO 32000-1 lists it as optional, so a perfectly valid PDF can fail here.

The shape of /Alt

It is not a string. It is a multi-language text array: pairs of strings, the first in each pair a language identifier and the second the text in that language.

/Alt [ (en-GB) (Video, 2 min 10 s: completing section 3 of the form.)
       (he-IL) <FEFF…>                     % the same, in Hebrew
       ()      (Video: completing section 3 of the form.) ]  % default

An empty language string marks the default text. A document published in two languages can describe its media in both, and a reader that knows the user’s language can pick the right one. A plain string where the array should be is malformed rather than merely short — veraPDF’s test for this condition checks that the value is correct, not only that the key exists.

What the reader gets without it

When the clip plays, nothing changes for a sighted user. The description matters at exactly the moments the media does not work: the viewer cannot play the format, the security settings block media, the document has been converted to another format, or the user cannot see the picture at all. In each of those cases the clip is a rectangle with nothing in it, and the processor has no text to offer instead.

Writing one that earns its place

Short, and about the clip as an object:

• What kind of media and how long. Video, 2 min 10 s or Audio, 45 s. A user deciding whether to spend two minutes on it needs this first.
• What it shows or says, in one sentence. Not a transcript.
• Where the full alternative is. If there is a transcript or a described version, say where it is — page 4, an appendix, a URL.

Do not repeat the annotation’s /Contents word for word; a reader that announces both says it twice.

How to check it free

veraPDF reports it against clause 7.18.6.2 with the message “Alt key … is missing from the media clip data dictionary or has incorrect value”. It reaches the clip by following the rendition action, as above.

Acrobat Pro has no documented check for the media clip’s own /Alt. Adobe describes the Accessibility Checker’s Other elements alternate text rule as covering content other than figures that requires alternate text, such as multimedia, and its fix as adding alternate text through the Accessibility tags panel — that is, on the structure element. Filling that in is worth doing and does not satisfy this condition.

The pikepdf script on the 28-014 page prints /CT and /Alt for each clip a Screen annotation plays through its own action.

How to fix it free

Acrobat has no field for it. Adobe documents the options for inserted media as launch settings, playback controls and video settings — activation, border, poster image, skin, trimming, chapter points (Adobe: Add audio, video, and interactive objects to PDFs). None of them is a description of the clip.

Set it at object level. With the clip dictionary in hand (the script on the 28-014 page finds it):

clip["/Alt"] = pikepdf.Array([
    pikepdf.String("en-GB"),
    pikepdf.String("Video, 2 min 10 s: completing section 3 of the form, "
                   "with narration. Transcript on page 4."),
])
pdf.save("course-fixed.pdf")

This changes no pixel and no playback behaviour; it adds text where a processor will look for it.

Or move the media out. For a document whose video is supplementary, a described link to the hosted video — with captions and a transcript where it is hosted — is often more useful than an embedded clip with a good /Alt. That is a call about the document, not a repair, and it removes the condition rather than satisfying it.

What Taggart does

Taggart follows each Screen, Movie and RichMedia annotation’s own actions — /A, the entries of /AA, any /Next chain — to its rendition actions, and through media renditions, selector renditions and clip sections to every media clip they play. A clip with no /Alt is reported:

The media clip data dictionary of a /Screen annotation on page 1 has no /Alt text description.

It is a presence test. A plain string where the multi-language array should be passes Taggart and fails veraPDF, so if you set /Alt by hand, check it there. And a clip played from somewhere other than the annotation itself — a Link that starts it, a page action — is not followed; veraPDF reads rendition actions wherever they are, and will find those.

There is no repair, and there would not be an automatic one: a description of a video is a sentence somebody who has watched it has to write.

How Taggart handles it

Taggart checks for this condition automatically and reports it as a blocker, with where in the file it found it.

Where this sits in the standards

Related conditions

• 28-014 CT entry is missing from the media clip data dictionaryThe media clip's content type (/CT) is required so a processor knows what it is being asked to play.
• 28-004 An annotation has neither a Contents entry nor an alternative descriptionEvery non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
• 13-004 Figure tag alternative or replacement text missingA Figure element has neither /Alt nor /ActualText. Every Figure must have one or the other; if the image is decorative it should be an artifact instead of a Figure.
• 28-002 An annotation is not a direct child of an Annot structure elementNon-widget, non-link annotations must sit inside an Annot structure element so they have a place in the reading order.

Other conditions in checkpoint 28

Checkpoint 28 covers annotations. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.

• 28-001 An annotation is not in correct reading orderThe annotation's position in the structure tree does not match where it appears on the page.
• 28-002 An annotation is not a direct child of an Annot structure elementNon-widget, non-link annotations must sit inside an Annot structure element so they have a place in the reading order.
• 28-003 An annotation is used for visual formatting but is not tagged according to its semantic functionA Square or Line annotation used to draw a box round a callout is decoration and should be artifacted, or tagged for what it actually means.
• 28-004 An annotation has neither a Contents entry nor an alternative descriptionEvery non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
• 28-005 A form field has neither a TU entry nor an alternative descriptionThe /TU tooltip is the accessible name of a PDF form field. Without it the field has no name at all — the visible label printed next to it is not connected to the control.
• 28-006 An annotation with subtype undefined in ISO 32000 does not meet 7.18.1A custom annotation subtype still has to be placed in the structure tree and described.
• 28-007 An annotation of subtype TrapNet existsTrapNet annotations are prepress artefacts and are forbidden in PDF/UA-1.
• 28-008 A page containing an annotation does not contain a Tabs entryAny page carrying annotations must declare a tab order. PDF/UA-1 requires /Tabs /S — tab order follows the structure tree.
• 28-009 A page containing an annotation has a Tabs entry with a value other than S/Tabs is present but set to /R (row order) or /C (column order) rather than /S (structure order).
• 28-010 A widget annotation is not nested within a Form tagEvery form control must sit inside a Form structure element.
• 28-011 A link annotation is not nested within a Link tagA link annotation must be a child of a Link structure element containing the link's text, joined by an object reference (/OBJR).
• 28-012 A link annotation does not include an alternate description in its Contents entryLink annotations need /Contents describing where the link goes.
• 28-013 An IsMap entry is true but the functionality is not provided in some other wayA server-side image map requires pointing at a pixel, which is not possible without a mouse.
• 28-014 CT entry is missing from the media clip data dictionaryThe media clip's content type (/CT) is required so a processor knows what it is being asked to play.
• 28-016 File attachment annotations do not conform to 7.11The file specification referenced by a FileAttachment annotation must carry both /F and /UF.
• 28-017 A PrinterMark annotation is included in the logical structureCrop marks and registration targets are production artefacts and must not appear in the structure tree.
• 28-018 The appearance stream of a PrinterMark annotation is not marked as ArtifactThe content inside a PrinterMark's appearance stream must itself be artifacted.

Checked with Taggart on a generated file that fails this condition on 2026-10-02. The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated 2026-10-02.