Media Annotations in PDF
Contents
[
Hide
]
This article shows how to work with media annotations in PDF documents using Aspose.PDF for Python via .NET.
The example script demonstrates several multimedia workflows:
- add a sound annotation
- create a 3D annotation from a U3D model
- add a screen annotation from a media file
- add and delete rich media annotations
- inspect existing multimedia annotations
Add Sound Annotations
This example adds a sound annotation to the first page of an existing PDF and links it to a WAV media file stored in the input directory.
Open the PDF and define the media file
media_dir = path.dirname(infile)
document = ap.Document(infile)
page = document.pages[1]
media_file = path.join(media_dir, "file_example_WAV_1MG.wav")
Create and configure the sound annotation
Set the annotation rectangle, color, title, and subject. Then add a popup annotation to provide extra details when the annotation is selected.
sound_annotation = ann.SoundAnnotation(
page,
ap.Rectangle(20, 700, 60, 740, True),
media_file,
)
sound_annotation.color = ap.Color.blue
sound_annotation.title = "John Smith"
sound_annotation.subject = "Sound Annotation demo"
sound_annotation.popup = ann.PopupAnnotation(
page,
ap.Rectangle(20, 700, 60, 740, True),
)
Add the annotation and save the PDF
page.annotations.append(sound_annotation)
document.save(outfile)
Complete example
def sound_annotation_add(infile, outfile):
media_dir = path.dirname(infile)
document = ap.Document(infile)
page = document.pages[1]
media_file = path.join(media_dir, "file_example_WAV_1MG.wav")
sound_annotation = ann.SoundAnnotation(
page,
ap.Rectangle(20, 700, 60, 740, True),
media_file,
)
sound_annotation.color = ap.Color.blue
sound_annotation.title = "John Smith"
sound_annotation.subject = "Sound Annotation demo"
sound_annotation.popup = ann.PopupAnnotation(
page,
ap.Rectangle(20, 700, 60, 740, True),
)
page.annotations.append(sound_annotation)
document.save(outfile)
Add 3D Annotations
This workflow creates a new PDF and embeds a 3D model from a U3D file. It also defines preset views and rendering settings for the 3D content.
Create the PDF document and 3D content
model_file = infile
document = ap.Document()
pdf3d_content = ann.PDF3DContent(model_file)
pdf3d_artwork = ann.PDF3DArtwork(document, pdf3d_content)
pdf3d_artwork.lighting_scheme = ann.PDF3DLightingScheme(type_name="CAD")
pdf3d_artwork.render_mode = ann.PDF3DRenderMode(type_name="Solid")
Define the 3D view matrices
These matrices describe how the 3D model is displayed from different viewpoints.
top_matrix = ap.Matrix3D(
1,
0,
0,
0,
-1,
0,
0,
0,
-1,
0.10271,
0.08184,
0.273836,
)
front_matrix = ap.Matrix3D(
0,
-1,
0,
0,
0,
1,
-1,
0,
0,
0.332652,
0.08184,
0.085273,
)
Add named views to the artwork
pdf3d_artwork.view_array.add(ann.PDF3DView(document, top_matrix, 0.188563, "Top"))
pdf3d_artwork.view_array.add(ann.PDF3DView(document, front_matrix, 0.188563, "Left"))
Create the annotation and save the document
page = document.pages.add()
pdf3d_annotation = ann.PDF3DAnnotation(
page,
ap.Rectangle(100, 500, 300, 700, True),
pdf3d_artwork,
)
pdf3d_annotation.border = ann.Border(pdf3d_annotation)
pdf3d_annotation.set_default_view_index(1)
pdf3d_annotation.flags = ann.AnnotationFlags.NO_ZOOM
pdf3d_annotation.name = path.basename(model_file)
page.annotations.append(pdf3d_annotation)
document.save(outfile)
Complete example
def annotation_3d_add(infile, outfile):
model_file = infile
document = ap.Document()
pdf3d_content = ann.PDF3DContent(model_file)
pdf3d_artwork = ann.PDF3DArtwork(document, pdf3d_content)
pdf3d_artwork.lighting_scheme = ann.PDF3DLightingScheme(type_name="CAD")
pdf3d_artwork.render_mode = ann.PDF3DRenderMode(type_name="Solid")
top_matrix = ap.Matrix3D(
1,
0,
0,
0,
-1,
0,
0,
0,
-1,
0.10271,
0.08184,
0.273836,
)
front_matrix = ap.Matrix3D(
0,
-1,
0,
0,
0,
1,
-1,
0,
0,
0.332652,
0.08184,
0.085273,
)
pdf3d_artwork.view_array.add(ann.PDF3DView(document, top_matrix, 0.188563, "Top"))
pdf3d_artwork.view_array.add(
ann.PDF3DView(document, front_matrix, 0.188563, "Left")
)
page = document.pages.add()
pdf3d_annotation = ann.PDF3DAnnotation(
page,
ap.Rectangle(100, 500, 300, 700, True),
pdf3d_artwork,
)
pdf3d_annotation.border = ann.Border(pdf3d_annotation)
pdf3d_annotation.set_default_view_index(1)
pdf3d_annotation.flags = ann.AnnotationFlags.NO_ZOOM
pdf3d_annotation.name = path.basename(model_file)
page.annotations.append(pdf3d_annotation)
document.save(outfile)
Add Screen Annotations
Screen annotations let you attach playable media to a PDF page. This example creates a new PDF and adds a screen annotation based on a SWF file.
Create the PDF and page
media_file = infile
document = ap.Document()
page = document.pages.add()
Create the screen annotation
screen_annotation = ann.ScreenAnnotation(
page,
ap.Rectangle(170, 190, 470, 380, True),
media_file,
)
Add the annotation and save the PDF
page.annotations.append(screen_annotation)
document.save(outfile)
Complete example
def screen_annotation_with_media_add(infile, outfile):
media_file = infile
document = ap.Document()
page = document.pages.add()
screen_annotation = ann.ScreenAnnotation(
page,
ap.Rectangle(170, 190, 470, 380, True),
media_file,
)
page.annotations.append(screen_annotation)
document.save(outfile)
Rich Media Annotations
Add Rich Media Annotations
Rich media annotations can embed advanced interactive content such as video players with posters, skins, and custom playback settings.
Prepare the media and player resources
The sample loads the video, poster image, and player skin files from predefined locations.
media_dir = path.dirname(infile)
path_to_adobe_app = (
r"C:\\Program Files (x86)\\Adobe\\Acrobat 2017\\Acrobat\\Multimedia Skins"
)
document = ap.Document()
page = document.pages.add()
video_name = "file_example_MP4_480_1_5MG.mp4"
poster_name = "file_example_MP4_480_1_5MG_poster.jpg"
skin_name = "SkinOverAllNoFullNoCaption.swf"
Create the rich media annotation
rich_media_annotation = ann.RichMediaAnnotation(
page,
ap.Rectangle(100, 500, 300, 600, True),
)
Attach the custom player, skin, poster, and video
player_path = os.path.join(path_to_adobe_app, "Players", "Videoplayer.swf")
rich_media_annotation.custom_player = open(player_path, "rb")
rich_media_annotation.custom_flash_variables = f"source={video_name}&skin={skin_name}"
skin_path = os.path.join(path_to_adobe_app, skin_name)
rich_media_annotation.add_custom_data(skin_name, open(skin_path, "rb"))
poster_path = os.path.join(media_dir, poster_name)
rich_media_annotation.set_poster(open(poster_path, "rb"))
video_path = os.path.join(media_dir, video_name)
with open(video_path, "rb") as video_file:
rich_media_annotation.set_content(video_name, video_file)
Set playback behavior and save the PDF
The annotation is configured as video content and activated when the user clicks it.
rich_media_annotation.type = ann.RichMediaAnnotation.ContentType.VIDEO
rich_media_annotation.activate_on = ann.RichMediaAnnotation.ActivationEvent.CLICK
rich_media_annotation.update()
page.annotations.append(rich_media_annotation)
document.save(outfile)
Complete example
def rich_media_annotations_add(infile, outfile):
media_dir = path.dirname(infile)
path_to_adobe_app = (
r"C:\\Program Files (x86)\\Adobe\\Acrobat 2017\\Acrobat\\Multimedia Skins"
)
document = ap.Document()
page = document.pages.add()
video_name = "file_example_MP4_480_1_5MG.mp4"
poster_name = "file_example_MP4_480_1_5MG_poster.jpg"
skin_name = "SkinOverAllNoFullNoCaption.swf"
rich_media_annotation = ann.RichMediaAnnotation(
page,
ap.Rectangle(100, 500, 300, 600, True),
)
player_path = os.path.join(path_to_adobe_app, "Players", "Videoplayer.swf")
rich_media_annotation.custom_player = open(player_path, "rb")
rich_media_annotation.custom_flash_variables = (
f"source={video_name}&skin={skin_name}"
)
skin_path = os.path.join(path_to_adobe_app, skin_name)
rich_media_annotation.add_custom_data(skin_name, open(skin_path, "rb"))
poster_path = os.path.join(media_dir, poster_name)
rich_media_annotation.set_poster(open(poster_path, "rb"))
video_path = os.path.join(media_dir, video_name)
with open(video_path, "rb") as video_file:
rich_media_annotation.set_content(video_name, video_file)
rich_media_annotation.type = ann.RichMediaAnnotation.ContentType.VIDEO
rich_media_annotation.activate_on = ann.RichMediaAnnotation.ActivationEvent.CLICK
rich_media_annotation.update()
page.annotations.append(rich_media_annotation)
document.save(outfile)
Delete Rich Media Annotations
This workflow removes all rich media annotations from the first page of an existing PDF.
Open the PDF and collect rich media annotations
document = ap.Document(infile)
page = document.pages[1]
to_delete = [
annotation
for annotation in page.annotations
if annotation.annotation_type == ann.AnnotationType.RICH_MEDIA
]
Delete the annotations and save the document
for annotation in to_delete:
page.annotations.delete(annotation)
document.save(outfile)
Complete example
def rich_media_annotations_delete(infile, outfile):
document = ap.Document(infile)
page = document.pages[1]
to_delete = [
annotation
for annotation in page.annotations
if annotation.annotation_type == ann.AnnotationType.RICH_MEDIA
]
for annotation in to_delete:
page.annotations.delete(annotation)
document.save(outfile)
Get Multimedia_annotations
To inspect multimedia content already stored in a PDF, filter the annotations collection for screen, sound, and rich media annotation types.
Open the document and define target annotation types
document = ap.Document(infile)
target_types = {
ann.AnnotationType.SCREEN,
ann.AnnotationType.SOUND,
ann.AnnotationType.RICH_MEDIA,
}
Print multimedia annotation rectangles
for annotation in document.pages[1].annotations:
if annotation.annotation_type in target_types:
print(f"{annotation.annotation_type} [{annotation.rect}]")
Complete example
def multimedia_annotations_get(infile, outfile):
document = ap.Document(infile)
target_types = {
ann.AnnotationType.SCREEN,
ann.AnnotationType.SOUND,
ann.AnnotationType.RICH_MEDIA,
}
for annotation in document.pages[1].annotations:
if annotation.annotation_type in target_types:
print(f"{annotation.annotation_type} [{annotation.rect}]")