Video Annotations

This section is about embedded video annotations. For adding multimedia elements on-demand, see our Multimedia annotations guide instead.

RichMedia/Video Annotations

The default way to embed video into a PDF is by using RichMedia annotations. This annotation type can store and embed videos directly into the PDF and is supported on both iOS and Android. RichMedia annotations can be created with Adobe Acrobat and various similar tools.

PSPDFKit currently does not support creating RichMedia annotations. If you are interested in this feature, please contact us on support.

Download a sample file with an RichMedia video here. (Try with our free PDF Viewer apps)

Various customizations and RichMedia control actions are supported, such as show/hide controls.

Warning: Ensure the codec used is either a standard MPG/H264 or a similar type that is universally supported. Acrobat, in most cases, uses Flash for playing videos, as it supports some less common, outdated formats as well.

Showing/Hiding Video Controls

By default, video controls are always shown. There might be documents with a flag set on the video annotation, to explicitely hide video controls. If you still want to show controls, this can be altered in the document itself, by setting the Playback Control Skin to "All Controls" in Adobe Acrobat.

Or you can set the CONTROLS_ENABLED flag via setMediaOptions on the annotation object.

You can use the following code snippet after loading the PdfDocument to enable controls for all rich media annotations in the document.

    .subscribe { it.setMediaOptions(EnumSet.of(MediaOptions.CONTROLS_ENABLED)) }
    .subscribe(annotation -> {


The PDF format defines autoplay in the RichMediaSettings Dictionary as RichMediaActivation. Supported activation conditions are both PO and PV, PSPDFKit makes no difference in these autoplay conditions and will trigger start once the page has appearared. (XA defines manual start, this is also used if the value is omitted)

PSPDFKit exposes this as a flag on the annotation object.

Supported Audio/Video Formats

PSPDFKit passes the extracted audio or video material to the system player. Supported contex, bitrates and similar depend on your target platform and OS version. Both iOS and Android support most variations of mp3 audio and mp4 video formats, however please test content on an actual device. Support in Simulator/Emulator environments can be different.

Content Appearance

RichMedia (Video/Audio) annotations are usually displayed via embedded Flash controls, which is not supported on mobile. PSPDFKit will extract the content and has logic to interpret common parameters such as showing/hiding controls. There are a variety of different Flash players used, so it's not always possible to map all varianbles. Please ping support if you have a document that is not correctly interpreted.

RichMedia Annotations are defined in Adobe® Supplement to the ISO 32000 Specification, BaseVersion: 1.7 ExtensionLevel: 3.