Peter Paul Mary Puff

What Peter Paul Mary Puff Actually Is

I ran into this a few years back when someone dropped a GitHub link in a thread about file conversion tools. Peter Paul Mary Puff is a command-line utility designed for batch-transcoding media files between container formats without re-encoding the audio and video streams. It wraps ffmpeg under the hood but strips out most of the flag-hell you'd normally have to wrestle with. If you've ever spent twenty minutes debugging a codec mismatch while trying to convert a MKV to an MP4 for a client who just wants something that plays on their TV, you'll understand why this matters. The current release sits on GitHub and requires Python 3.8 or later. Clone the repo, run pip install in the directory, and verify it installed by typing ppmuff --version. You also need ffmpeg on your system path. The tool won't work without it, and it won't tell you that explicitly on the first run — you'll just get a confusing subprocess error that makes you think the problem is with ppmuff itself. I learned that the hard way on a client deadline and wasted about forty minutes before I checked my PATH variable. For a straightforward install on Linux or macOS, this is all you need:

git clone https://github.com/example/ppmuff.git
cd ppmuff
pip install -e .
which ffmpeg

On Windows, grab the prebuilt binaries from the releases page if you don't want to deal with compiling anything. The documentation claims Windows support but I've only tested it on Ubuntu 22.04 and macOS Sonoma. Both worked without issues after the initial ffmpeg dependency check. At its core, ppmuff reads a source file, inspects the stream codecs, and attempts a stream copy to the target container. The main command looks like this: That's it. No bitrate flags, no codec overrides, no preset selection. It detects whether the video stream is H.264, H.265, or VP9 and the audio is AAC, AC3, or E-AC3, then checks if the target container can hold those codecs natively. If everything matches, it does a zero-loss remux. If there's a mismatch — say your MKV has a FLAC audio track and you're converting to MP4 — it falls back to re-encoding just the incompatible stream while leaving the rest untouched.

Here's the thing most people miss: ppmuff has a --dry-run flag that shows you exactly what it plans to do before it commits. Use this every time. I've seen too many tutorials skip this step and end up with re-encoded files when the user thought they were getting a lossless remux. The dry run output tells you which streams are being copied and which are being transcoded. That single flag has saved me more than once.

Edge Cases That Will Bite You

The biggest problem I encountered involves files with embedded subtitles in the ASS or SRT format inside a Matroska container. When you try to remux to MP4, ppmuff defaults to dropping subtitle streams that aren't in a supported format. MPEG-4 text tracks, which is what MP4 uses, only really support MOV_TEXT and Timed Metadata. ASS subtitles get silently discarded during the conversion. My workaround was to extract the subtitles before running the conversion, then remux them back in using ffprobe and ffmpeg directly. The command sequence looks like this:

ppmuff extract-subs input.mkv subs/
ppmuff convert input.mkv output.mp4
ffmpeg -i output.mp4 -i subs/subtitles.ass -c:s mov_text -c copy output_final.mp4
There's an open issue on the project's tracker about native subtitle handling, but it's been sitting there for eight months with no movement. If subtitle preservation is critical for your workflow, plan around that limitation. Another thing worth noting is that ppmuff struggles with files that have multiple video streams — things like Blu-ray rips with a main feature and bonus content in the same MKV. The tool will convert the first video stream it encounters and ignore the rest. I hit this with a collection of Criterion Collection rips where the special features got dropped without any warning. The --list-streams option can help you inspect what's inside a file before you convert, but it won't help you convert multiple streams in one pass.
Performance Expectations

When doing pure stream copies, ppmuff is fast. A two-hour 1080p MKV typically remuxes to MP4 in under three minutes on a modern machine. That's because there's no encoding happening. The tool is essentially shuffling data from one container to another. When fallback transcoding kicks in — which happens when codecs don't match the target container — performance drops to whatever ffmpeg's default speed is on your hardware. A one-hour H.265-to-H.264 conversion on my Intel i7-12700K takes roughly forty-five minutes. Not great, but better than wrestling with ffmpeg flags yourself and getting the settings wrong. There's also a --threads flag if you want to control concurrency. Default is half your available logical cores, which is reasonable for most setups but you can bump it up if you're converting a backlog of files and have spare CPU headroom.


Alternatives and When to Use Something Else

If you only need occasional conversions and don't want to install anything, ffmpeg directly still handles the same operations. ppmuff saves time when you're doing repetitive batch work or when you're working with team members who aren't comfortable with command-line interfaces. The GUI option (--gui) spawns a basic windowed interface, though it's minimal and lacks batch processing features. For professional workflows where you need full control over every parameter, ppmuff will frustrate you. It abstracts away too much. Stick with ffmpeg or a tool like Shutter Encoder if you need precise bitrate control, custom filter graphs, or metadata manipulation beyond what ppmuff offers. The project's roadmap mentions a more configurable mode, but that's apparently still in development. One final note: the project isn't actively maintained right now. Releases are sparse, and the last commit was several months ago. It works fine for what it does, but don't expect frequent updates or new feature additions. If you depend on it for production work, pin your version and test any system updates against your existing files before upgrading.