Multimedia PDF Annotations Library on iOS

Along with rich media/video annotations, PSPDFKit supports a custom format to display multimedia/gallery annotations, which can be created with Adobe Acrobat or PDFpen. Create a URL annotation and use pspdfkit:// as the URL scheme instead of HTTP, and the system will auto-detect the correct endpoint.

The supported formats are:

• Video (M3U8, MOV, AVI, MPG, M4V — these are the only formats supported by iOS). Both local and remote content is supported.

• Audio (MP3, M4A, MP4)

• Images (JPG, JPEG, PNG, [animated] GIF, TIFF, TIF, BMP, BMPF, CUR, XMB)

• Inline webpages

• Modal webpages (e.g. pspdfkit://[modal:YES,size:500x500]http://apple.com). Size is optional and only honored on iPad. The inline web browser can also be enabled by changing linkAction in PDFConfiguration.

• Any custom UIView using the delegate methods.

For example, pspdfkit://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8 will show the Apple HTTP Live Streaming test page. There are delegate methods if you need more control (like manually setting autoplay or adding custom annotations).

ℹ️ Note: The %5B and %5D are URL encodings for [ and ].

If you want to display local files, use pspdfkit://localhost/file.xy. The path is automatically set to the same path as the displayed PDF. Supported folders include Bundle, Documents, and Cache, but you can easily extend that to support custom folders.

Adding a Gallery to Your Document

PSPDFKit has great support for adding interactive content to a PDF. We support local/remote images, video, and audio. Content can come from different sources and can be configured both locally and remotely via a PDF annotation or a JSON file.

While galleries can be added programmatically, the simplest approach is via a link annotation. A link annotation already defines a bounding box for the position, which the gallery will use.

Gallery annotations can be both created and saved in a file or in code. Here’s an example of how to create this in code:

// Dynamically add gallery annotation.
let galleryAnnotation = LinkAnnotation(url: URL(string: "pspdfkit://localhost/Bundle/sample.gallery")!)
let pageSize = document.pageInfoForPage(at: 0)!.size
let size = CGSize(width: 400, height: 300)
galleryAnnotation.boundingBox = CGRect(x: (pageSize.width - size.width) / 2, y: (pageSize.height - size.height) / 2, width: size.width, height: size.height)
document.add(annotations: [galleryAnnotation])

// Dynamically add gallery annotation.
PSPDFLinkAnnotation *galleryAnnotation = [[PSPDFLinkAnnotation alloc] initWithURL:[NSURL URLWithString:@"pspdfkit://localhost/Bundle/sample.gallery"]];
CGSize pageSize = [document pageInfoForPageAtIndex:0].size;
CGSize size = CGSizeMake(400, 300);
galleryAnnotation.boundingBox = CGRectMake((pageSize.width - size.width) / 2.0f, (pageSize.height - size.height) / 2.0f, size.width, size.height);
[document addAnnotations:@[galleryAnnotation] options:nil];

The target is a .gallery JSON file that defines the contents and title of each image. Its definition is straightforward and looks like this:

[
	{
		"contentURL": "http://www.link-to-image1.com/image1.jpg",
		"caption": "This is a small image."
	},
	{
		"contentURL": "http://localhost/Bundle/gallery-local-image.jpg",
		"caption": "This is a local image. Captions are optional."
	}
]

contentURL can point to a local or remote source, and you can use common tokens like Documents or Bundle, which will be resolved if they’re local. Image sources can be JPG, PNG, or GIF. The image caption is optional.

You can also define the JSON in a PDF by using the contents property of the annotation (the notes field). Since Adobe Acrobat doesn’t allow setting or changing the contents field, we’ve added a second way to configure the gallery via adding the content as a JavaScript action.

The image gallery uses a smart download manager and will cache results (we don’t rely on NSURLCache since not all servers are properly configured to send the correct ETag for images). If your images change dynamically, you need to update the URL to the JSON and use a new image URL. (Adding a timestamp like ?1381917561 at the end is a good way to force cache reloads.)

Video Item Options

The gallery also supports videos and certain other options:

"caption":"A local audio file.",
    "options": {
        "loop":true,
        "autoplay":true,
        "controls":false
    }

Video items support a wide range of options to control the way the gallery handles them.

coverMode

The following values are valid cover modes.

ℹ️ Note: To get a clear cover, you also need to set the backgroundColor of the GalleryEmbeddedBackgroundView to UIColor.clearColor. This can be done with UIAppearance.

Play Button Customization

You can change the play button image like this:

let image = UIImage(named: "someImage.png")
MediaPlayerCoverView.appearance().playButtonImage = image

UIImage *image = [UIImage imageNamed:@"someImage.png"];
[[PSPDFMediaPlayerCoverView appearance] setPlayButtonImage:image];

If you just want to change the color of the play button, do the following:

MediaPlayerCoverView.appearance().playButtonColor = .red

[[PSPDFMediaPlayerCoverView appearance] playButtonColor:UIColor.redColor];

Activatable Content

By default, the special link annotations mentioned above will show content within the annotation’s bounding box. This behavior can be changed as well:

• modal (Action.Option.modalKey) — This will show the content in a new controller, modally, when tapped.

• popover (Action.Option.popoverKey) — This content can also be displayed in a popover. This value is ignored on the iPhone.

• size (Action.Option.sizeKey) — If this is defined, the modal controller will be presented as a sheet hovering over the parent controller. This property also controls the popover target size, if set. This will be ignored on iPhone. The minimum size for the sheet is 200x200. A value of 550x550 is recommended for modal sheets.

• button (Action.Option.buttonKey) — Set this to @YES or to a local/remote destination to show a button instead of directly showing the inline content. This can be used to create multimedia buttons that will show a gallery or web content on tap. This can be combined with a modal/popover to create these actions on a button tap. For local button URLs, use pspdfkit://localhost/Bundle/image.png or similar.