Multipage and Animated Images

By default, libvips usually reads only the first page or frame. Pass {:n -1} to load every page, or use {:page …​ :n …​} to load a single page or a range.

Points to note:

You can also load a subset of frames:

Be careful interpreting metadata on partial loads. The loaded strip height reflects the selected range, but some loaders can still preserve source metadata such as the original total n-pages. For frame slicing logic, rely on the loaded image dimensions together with page-height, not only on the reported source page count.

The same loader options apply to other multipage-capable loaders such as ops/webpload and ops/tiffload, or to the generic v/from-file path when you want format autodetection.

For PDF input, remember that ol.vips blocks libvips operations marked as untrusted during initialization. If you have a trusted PDF input path and need to load it, opt in first with v/set-block-untrusted-operations! set to false.

If an image already has the right strip layout and metadata, writing an animated or multipage image is just a normal save. For example, you can load a GIF animation and write it back as animated WebP:

That works because the loaded image already carries the n-pages, page-height, loop, and delay metadata that the saver needs.

The same pattern applies to multipage TIFF output with ops/tiffsave or to generic saves through v/write-to-file when libvips can infer the target format from the filename.

The upstream libvips examples build a vertical strip and then set metadata by hand. In ol.vips, prefer v/assemble-pages when you already have a sequence of equal-sized frames. It joins the frames into one strip and sets the page metadata for you.

Here, frame-a, frame-b, and frame-c are just ordinary image handles. v/assemble-pages does not require a special frame type. The frames argument is simply a non-empty collection of same-sized images, with each image becoming one animation frame in the output.

In practice, those images can come from any image-producing operation, not only from ops/extract-area. You can resize, crop, composite, render text, or load separate files first, then pass the resulting image handles to v/assemble-pages.

If you already have a tall strip and need to annotate or adjust it, use v/assoc-pages, v/assoc-page-height, v/assoc-page-delays, and v/assoc-loop-count.

For uniform-height multipage images, the page-aware helpers apply ordinary operations frame by frame and keep the metadata consistent.

The main helpers are:

For single-page inputs, these helpers fall back to the ordinary single-image behavior. For true multipage work, they assume that the image can be divided cleanly into equal-height pages.