Attachments, layers & media

TeX Live 2024 ships a file called VPlayer.swf: 483,412 bytes of Flash, last modified on 19 January 2018. Use \includemedia from LaTeX’s media9 package and that file is embedded wholesale into your PDF — nearly half a megabyte of player, for one video, that nothing can run any more. Flash reached end of life on 31 December 2020, and from 12 January 2021 Adobe itself began blocking Flash content from playing. A PDF can carry far more than static pages — attached files, layers, annotations, animation, video — but each of those degrades very differently in the wild. This page sorts out which is which, checking the claims with pdfdetach and pdftotext.

Embedding a file in a PDF: attachfile2 versus embedfile

The difference is where in the PDF the file is put. attachfile2’s \attachfile{data.csv} places a /FileAttachment annotation — the paperclip icon — on the page. embedfile’s \embedfile{data.csv} puts nothing on the page and instead registers the file in the document-wide /EmbeddedFiles tree under /Names. The measurement splits cleanly: the attachfile2 output contains two /FileAttachment annotations (one for \attachfile, one for \textattachfile) and no /EmbeddedFiles at all; the embedfile output is the exact reverse. A viewer’s “Attachments” panel reads that name tree, so a PDF built with \attachfile alone shows nothing in the panel — the reader has to spot the icon on the page. Using both is the safe answer.

\usepackage{attachfile2}
\usepackage{embedfile}

% visible on the page: a clickable paperclip, and custom link text
\attachfile[icon=Paperclip,author={Ada}]{data.csv}
\textattachfile{data.csv}{download the data}

% invisible, but listed in the viewer's Attachments panel
\embedfile[desc={Source data},mimetype=text/csv]{data.csv}

Which to choose is answered by the packages themselves. attachfile2 is Heiko Oberdiek’s development of Scott Pakin’s attachfile (TeX Live 2024 ships v2.12, dated 2024-01-18), adding dvips support and automatic metadata about the attached file. Sure enough, a PDF built with attachfile2 carried /Size 12 — the byte count of the original — and /CheckSum <178ba857…>, while the old attachfile output has no /CheckSum at all. And its own README says plainly: “See the embedfile package for a newer package supporting this feature.” For new work, choose by whether you want a visible icon; if you do not, embedfile is the straightforward answer.

Whether the attachment really landed is easy to confirm with poppler’s pdfdetach. pdfdetach -list paper.pdf lists the embedded files and pdfdetach -saveall -o out paper.pdf extracts them — measured, the recovered data.csv came back byte for byte identical to the original. One thing worth noticing there: attaching the same file twice embeds it twice. Putting \attachfile and \textattachfile side by side is enough for pdfdetach -list to answer 2 embedded files. If you want to link to a large dataset from several places, embed it once with embedfile and point at it from the text instead.

$ pdfdetach -list paper.pdf
2 embedded files
1: data.csv
2: data.csv

$ pdfdetach -saveall -o out paper.pdf && diff out/data.csv data.csv && echo identical
identical

Layers (OCG) with ocgx2 — and why hidden content is not hidden

A PDF’s OCG (Optional Content Groups) are layers that can be shown or hidden. Alexander Grahn’s ocgx2 wraps content in \begin{ocg}{name}{id}{initial visibility}…\end{ocg} and supplies \switchocg, \toggleocgs, \showocgs and \hideocgs as clickable switches. The generated PDF does carry an /OCProperties dictionary, and the technique suits progressive reveals or stacking alternative versions of one figure. But the switching mostly works in Acrobat; other viewers may simply display the initial state.

\usepackage{ocgx2}
Question: what is $2+2$?
\begin{ocg}{Answer}{ans}{0}   % 0 = hidden when the file opens
  The answer is 4.
\end{ocg}

\switchocg{ans}{Show or hide the answer}

And there is a far more important trap. Text on a hidden layer is not hidden. Compile the example above and run pdftotext on it, and the extracted text reads Question: what is 2 + 2? The answer is 4. — the answer comes out in full despite starting invisible. An OCG says whether something is drawn; it is neither encryption nor deletion. So hiding content you do not want seen behind an OCG is pointless: exercise solutions, redactions for reviewers, an alternative price list — anyone who copies the text or runs an extractor once can read all of it. If something must not be seen, do not put it in the PDF.

Annotations and comments: sticky notes, highlights and tooltips with pdfcomment

Josef Kleber’s pdfcomment (TeX Live 2024 ships v2.4a) builds PDF annotations from LaTeX source. \pdfcomment{…} makes a sticky note (/Subtype /Text), \pdfmarkupcomment[markup=Highlight]{the text}{the comment} highlights a phrase and attaches a note to it (/Subtype /Highlight), and \pdftooltip{text}{explanation} produces a tooltip on hover. The author={Reviewer} key becomes /T in the PDF and shows up as the commenter’s name in a viewer’s comment list. It lets you keep review remarks in the LaTeX source and surface them as annotations in the distributed PDF.

Two practical notes. First, colours: writing color=yellow without loading xcolor stops the run with ! Package pdfcomment Error: This color specification is not supported. Put \usepackage{xcolor} first and it goes through. Second, passes: markup annotations do not appear on the first run, and only the second brings in the /Subtype /Highlight (the log even says Rerun to get outlines right or use package bookmark.). pdfcomment is one of the survivors, though — rendering a page to an image with poppler and counting colours showed the highlight yellow (RGB 255,242,0) genuinely drawn. And the body of an annotation does not show up in pdftotext output, so comments never contaminate the extracted text.

\usepackage{xcolor}       % must come before pdfcomment for named colours
\usepackage{pdfcomment}

A sentence.\pdfcomment[author={Reviewer},icon=Note,color=yellow]{Check this reference.}
A \pdfmarkupcomment[markup=Highlight,color=yellow,author={Reviewer}]%
  {highlighted phrase}{needs a citation}.
A \pdftooltip{term}{shown when the pointer rests on it}.

Animation: animate runs on JavaScript

Alexander Grahn’s animate is the one moving-picture mechanism that does not lean on Flash. Write \animategraphics[controls,autoplay]{12}{frame-}{0}{59} and you get a figure that plays frame-0.png through frame-59.png at twelve frames per second. To animate frames drawn in TikZ or PSTricks directly, use the animateinline environment with \multiframe. The engine is JavaScript embedded in the PDF — pdfinfo’s JavaScript field duly flips to yes. Any viewer that runs JavaScript can play it, which makes it far more portable than embedded video. The cost is that every frame is embedded, so frame count and resolution translate directly into file size.

\usepackage{animate}
% a numbered image series: frame-0.png ... frame-59.png at 12 fps
\animategraphics[controls,autoplay,width=6cm]{12}{frame-}{0}{59}

% or animate TikZ frames drawn on the fly
\begin{animateinline}[controls,loop]{6}
  \multiframe{12}{i=0+30}{%
    \begin{tikzpicture}\draw[->,thick] (0,0)--(\i:1.5);\end{tikzpicture}}
\end{animateinline}

Multimedia: media9 and the legacy of Flash

media9’s \includemedia embeds video, audio and 3D in a PDF; movie15 is its obsolete predecessor. Technically it still runs — the measurement produced a /Subtype /RichMedia annotation and a /Subtype /Video object. The problem is the playback side. The VPlayer.swf you name in \includemedia’s second argument is a Flash file, still shipped with TeX Live 2024, and Flash itself was retired at the end of 2020. Tried with a 14-byte dummy video, the output PDF came to 493,989 bytes — almost all of it a player that will never run again. For new documents, link to external media, or use animate for frame-based motion. Treating media9 as legacy is the right call.

Which features actually survive, and how far

The short answer: attachments and annotations are safe to use; layers and video are not. The table below records what a PDF built on TeX Live 2024 looks like to the poppler tools (pdfinfo, pdfdetach, pdftotext, pdftoppm). What that establishes is whether the right objects are inside the PDF and how poppler treats them; behaviour in Adobe Acrobat was not verified here. For the features widely reported to depend on Acrobat — OCG switching, \includemedia playback — test them yourself in the environment your readers will actually use before committing.