Convert animated WebP to MP4 on your Mac, a folder at a time

Why a Mac will not simply turn one into a video

WebP is an image format that happens to be able to hold more than one frame. That single fact explains everything awkward about it. Every part of macOS that deals with the file treats it as a picture — because it is one — and pictures are converted into other pictures. Ask for a JPEG or a PNG and you get a JPEG or a PNG: one frame, the animation gone.

The video half of the system never sees it at all. Movie players and editors work from a list of container and codec formats they understand, and WebP is not on it, so there is nothing to open. This is also why an animated WebP makes a disappointing wallpaper: a program that wants a movie file cannot be given an image file instead, and one that accepts images will show it the way it shows any image, which is to say still.

So the conversion has to be done deliberately, by something that reads the frames out of the image side and writes them into the video side. That is all the converter in Emerald Tools is — but doing it for a folder rather than a file, and doing it without guessing at anything the source file already knows.

What it does with each file

Every animated WebP carries its own timing: each frame declares how long it should be held. The converter reads those delays and lays the frames out on the same schedule, so a slow animation stays slow and a fast one stays fast. Only where a frame declares no delay at all does it assume anything, and then it assumes a tenth of a second.

The picture is written at the source’s own size — no scaling, no cropping — except that an odd number of pixels is rounded down by one, because the encoder cannot accept odd dimensions. The result is HEVC video in an MP4 container with no audio track. The bitrate is worked out from the material rather than fixed: the frame area multiplied by the average frame rate, multiplied by the one quality control there is.

Files that are not animations are not a failure case. A folder downloaded from a website is usually a mixture, and the still WebP files in it are simply reported in the log and passed over. If it turns out there was nothing animated in the folder at all, the app says so plainly instead of ending on an empty result you would have to interpret.

None of this touches the folder you pointed at. The MP4s are assembled in a working area of their own, and the final step is where you decide whether they should land beside the originals — in a new subfolder stamped with the date and time, so nothing existing can be overwritten — or somewhere else entirely.

Clips that belong together

Animations pulled from a page are often one sequence cut into pieces. The converter looks for that: once everything is converted, it compares the last frame of each clip against the first frame of every other, and where two frames are close enough to be continuous it links them into a chain. A chain is written out as one file named after its pieces, joined by a plus sign.

Two things keep this from running away with your files. Where the names are plain numbers, a clip is only ever considered against the next number up, so an accidental match between the first and the twelfth piece cannot happen. And the pieces are never deleted — a joined file is an addition, not a replacement, so a join you did not want costs you nothing but a file you can throw away.

How willing it is to link is a setting, not a fixed rule. The threshold is a measure of how different two frames are allowed to be, and it can be tightened until only near-identical frames qualify or loosened until fairly different ones do.

Frame interpolation, and when it earns its cost

Animations meant for the web are often authored at eight or ten frames a second, which reads as a series of steps rather than movement once it is a video. Frame interpolation invents the frames in between: it estimates how the picture moved from one frame to the next and builds the intermediate stages, bisecting each gap until the result is somewhere near 32 frames a second. A source already at that rate is left alone.

It is off by default for two reasons, and the app says both of them on the settings page. The first is time — the estimation runs several times per gap, on every gap, and a long animation feels it. The second is that estimated motion is estimated: where the movement between two frames is large, or where something is hidden in one frame and revealed in the next, there is no correct in-between picture to build and what gets built can smear.

The compromise on offer is a limit on how much motion is worth attempting. Each gap is measured before anything is synthesised, and gaps whose motion exceeds the limit are left with their original frames — a moment of judder rather than a moment of smearing. The limit is expressed as a share of the shorter side of the picture and can be moved in either direction, which is really a choice about which of the two artefacts you would rather see. Clean, drawn animation with steady movement is where the technique looks its best; fast live-action footage is where it looks its worst.

The same settings serve the image collector

Emerald Tools converts animated WebP in two places. The converter described here is one; the other is the Safari extension and collector, which downloads the images on a web page and turns any animated WebP among them into MP4 on the way into Photos. Both use the same conversion settings — quality, similarity threshold, worker count, frame interpolation — from the same place in the app’s settings.

The two differ in what they do with the source file, and the difference is deliberate. The converter is a tool you point at your own folder, so it leaves that folder as it found it. The collector is working on files it downloaded itself a moment earlier into a temporary place of its own, so it replaces them. Changing a setting under Converter changes the behaviour of both; there is no second set of values to keep in step.

Specifications and limits

Everything below is the behaviour of the current release, not a plan.

• Input: files ending in .webp directly inside the chosen folder. Subfolders are not scanned. Files are processed in name order, with numbers compared as numbers.
• Animated only: a WebP with a single frame is logged as a static image and skipped. A folder with no WebP, or with no animated WebP, ends with a message saying so.
• Output: one MP4 per source, named after the source. HEVC video, no audio track.
• Size: the source’s own pixel size, rounded down to even dimensions where it is odd. No scaling or cropping.
• Timing: the per-frame delay declared in the WebP. A frame with no declared delay is held for 0.1 seconds.
• Bitrate: width × height × average frame rate × the Bitrate Multiplier, which runs from 0.1 to 1.0 in steps of 0.1 and starts at 0.5.
• Originals: read only. Nothing in the source folder is modified, moved or deleted.
• Results: held in a temporary working area until exported, then either written to a date-and-time-stamped subfolder inside the source folder or to a folder you choose.
• Joining: clips whose adjoining frames match within the Similarity Threshold are also written out as one combined file, named piece+piece.mp4. The pieces are kept. Numeric names are only compared with the next number up. The threshold runs from 0.01 to 0.5 and starts at 0.125. At least two converted clips in one run are needed for any join to happen.
• Frame interpolation: off by default. Targets roughly 32 frames a second by bisecting the gaps, up to three levels; sources at or above the target are skipped automatically.
• Motion Threshold: 4 to 30 per cent of the shorter side of the picture, starting at 12 per cent. Gaps with more motion than this keep their original frames instead of being interpolated.
• Workers: half of the reported cores by default, adjustable from one to all of them. Dynamic Workers, off by default, raises the count by about a quarter from twenty files and by half from fifty, never exceeding three quarters of the cores.
• Shared settings: the same Quality and Performance values are used by the automatic conversion the image collector performs on what it downloads.
• Permissions: none beyond access to the folder you select. No Photos library access, no screen recording, no accessibility.
• Transmission: none. Conversion is performed locally by the frameworks macOS ships with.
• System requirement: macOS 14.0 (Sonoma) or later.