File and Multimedia Annotations

• Jul 21, 2026
• 3 minutes to read

File Attachment Annotations

A file attachment annotation embeds a file into a PDF document and displays an icon that users can click to open or extract the attached file.

Use the FileAttachmentAnnotation class to create a file attachment annotation. Specify annotation bounds, assign the embedded file with the FileSpecification object, and optionally change the annotation icon.

The following code snippet attaches a file to a PDF page and displays it with a paper clip icon:

package pdf;

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;

import java.nio.channels.*;
import java.nio.file.*;
import java.io.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (FileChannel fileChannel = FileChannel.open(Path.of("Document.pdf"));
             PdfDocument pdfDocument = new PdfDocument(fileChannel)) {

            Page page = pdfDocument.getPages().getFirst();

            createFileAttachmentAnnotation(page);

            try (WritableByteChannel channel =
                         FileChannel.open(Path.of("Result.pdf"),
                                 StandardOpenOption.CREATE,
                                 StandardOpenOption.WRITE,
                                 StandardOpenOption.TRUNCATE_EXISTING)) {

                pdfDocument.save(channel);
            }
        }
    }

    static void createFileAttachmentAnnotation(Page page) {
        FileAttachmentAnnotation annotation =
                new FileAttachmentAnnotation(
                        new RectangleF(50, 420, 20, 20));

        annotation.setTitle("John Smith");
        annotation.setContent("Project specification");
        annotation.setIconName(FileAttachmentAnnotationIconName.PAPER_CLIP);

        try {
            FileSpecification fileSpecification = new FileSpecification();
            fileSpecification.setFileName("Specification.pdf");
            fileSpecification.setFileData(
                    Files.readAllBytes(Path.of("Specification.pdf")));
            fileSpecification.setDescription("Project specification");

            annotation.setFileSpecification(fileSpecification);

            page.getAnnotations().add(annotation);
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to read the attachment file.", e);
        }
    }
}

Customize the Annotation Icon

Use the FileAttachmentAnnotation.setIconName() method to specify the icon displayed for the attachment.

The PDF Document API supports the following icon names:

• Push Pin (default)
• Graph
• Paper Clip
• Tag

Attach a File

Use the FileAttachmentAnnotation.setFileSpecification() method to attach a file to the annotation.

Create a FileSpecification object, specify the file name, load the file data, and assign the file specification to the annotation.

FileSpecification fileSpecification = new FileSpecification();
fileSpecification.setFileName("Specification.pdf");
fileSpecification.setFileData(Files.readAllBytes(Path.of("Specification.pdf")));
fileSpecification.setDescription("Project specification");

annotation.setFileSpecification(fileSpecification);

Sound Annotations

A sound annotation embeds an audio clip into a PDF document and displays an icon that users can click to play the sound in a compatible PDF viewer.

Use the SoundAnnotation class to create a sound annotation. Specify annotation bounds, assign a Sound object that contains the audio data, and optionally change the annotation icon.

The following code snippet creates a sound annotation and embeds a WAV audio file:

static void createSoundAnnotation(Page page) {
    SoundAnnotation annotation =
            new SoundAnnotation(
                    new RectangleF(50, 420, 20, 20));

    annotation.setTitle("John Smith");
    annotation.setContent("Voice note");
    annotation.setIconName(SoundAnnotationIconName.MIC);

    try {
        Sound sound = new Sound();
        sound.setSamplingRate(44100);
        sound.setSoundChannels(2);
        sound.setBitsPerSample(16);
        sound.setEncoding(SoundEncoding.RAW);
        sound.setData(Files.readAllBytes(Path.of("VoiceNote.wav")));

        annotation.setSound(sound);

        page.getAnnotations().add(annotation);
    } catch (IOException e) {
        throw new UncheckedIOException("Failed to read the audio file.", e);
    }
}

Attach Audio Data

Use the SoundAnnotation.setSound() method to associate audio data with the annotation.

Create a Sound object, configure the audio format, load the sound data, and assign the object to the annotation.

Sound sound = new Sound();
sound.setSamplingRate(44100);
sound.setSoundChannels(2);
sound.setBitsPerSample(16);
sound.setEncoding(SoundEncoding.RAW);
sound.setData(Files.readAllBytes(Path.of("VoiceNote.wav")));

annotation.setSound(sound);

Configure the Sound object to match the format of the embedded audio file. For example, an uncompressed CD-quality WAV file uses a sampling rate of 44,100 Hz, two channels (stereo), 16 bits per sample, and SoundEncoding.RAW.

Customize the Annotation Icon

Use the SoundAnnotation.setIconName() method to specify the icon displayed for the sound annotation.

The PDF Document API supports the following icon names:

• Speaker (default)
• Microphone
• Headphone

Refer to the following help topic for additional information: SoundAnnotationIconName.