Encode PPM Frames to MPEG-1 with ppmtompeg

You will finish with a small MPEG-1 file made from a numbered sequence of PPM images, plus a parameter file you can adapt for a real sequence. The examples use the installed Netpbm 11.5.2 command on Debian or Ubuntu. Allow about fifteen minutes for a first test, plus the actual encoding time for your frames.

You need ppmtompeg, readable input images in a format Netpbm can convert, and a writable output directory. This guide uses PPM input directly, so it does not need elevated privileges. Do not use sudo for an encode merely because the output is a video file. If either the input or destination is protected, fix the file permissions or choose a user-owned working directory instead.

1. Check the installed command

Confirm which executable will run and record its version. These are ordinary, read-only commands:

$ command -v ppmtompeg
/usr/bin/ppmtompeg
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ ppmtompeg --version 2>&1 | head -n 1
ppmtompeg: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The installed manual is dated 23 July 2006, while the binary reports Netpbm 11.5.2. Keep that distinction in mind when comparing another machine. The parameter names in this guide come from the installed manual, and the small encode below was run successfully with this binary.

2. Put the frames in display order

Make a directory containing the images in a predictable sequence. The parameter file reads them in the order produced by its INPUT block. For four frames named frame0.ppm through frame3.ppm, check the names and dimensions before encoding:

$ file /path/to/frames/frame*.ppm
$ identify /path/to/frames/frame0.ppm 2>/dev/null || true
$ test -r /path/to/frames/frame0.ppm && echo readable
readable

identify is optional and belongs to ImageMagick, not Netpbm. Replace it with an installed image inspection tool, or omit it. The useful checks are that every file exists, is readable, and has the same dimensions. If the sequence has gaps, use explicit file names in the input block or adjust the numeric range. Do not assume that shell glob order is the order you want in the finished video.

3. Write a parameter file

ppmtompeg takes one parameter-file argument. The file is case-sensitive. Lines beginning with # are comments, but the keywords themselves must be upper case. This working example uses a repeated IBP frame pattern, 25 frames per second, and a 16 by 16 test sequence:

PATTERN IBP
OUTPUT /path/to/output/movie.mpg
INPUT_DIR /path/to/frames
INPUT
frame*.ppm [0-3]
END_INPUT
BASE_FILE_FORMAT PPM
INPUT_CONVERT *
SIZE 16x16
GOP_SIZE 3
SLICES_PER_FRAME 1
PIXEL HALF
RANGE 4
PSEARCH_ALG TWOLEVEL
BSEARCH_ALG SIMPLE
IQSCALE 8
PQSCALE 10
BQSCALE 12
REFERENCE_FRAME DECODED
FRAME_RATE 25
BIT_RATE 1150000
BUFFER_SIZE 327680

Change OUTPUT, INPUT_DIR, the filename range, and SIZE for your own files. INPUT_CONVERT * means that the input is already in the selected base format. For GIF or another source format, the conversion command must write the converted image to standard output, for example INPUT_CONVERT giftopnm *.

The four qscale values deserve care. They are integers from 1 to 31; larger values improve compression but reduce quality. The example deliberately keeps the values moderate rather than promising a particular visual result. GOP_SIZE is a target number of frames, but a GOP can be longer when needed to begin the next GOP with an I frame. The pattern and GOP size do not have to be identical, although matching them is usually easier to reason about.

4. Run one encode without overwriting an old file

Use a temporary output name while testing. -realquiet suppresses normal screen output and leaves errors visible, which makes a scripted smoke test easier to read:

$ sed 's#movie\.mpg#movie.mpg.new#' /path/to/encode.par > /tmp/ppmtompeg-test.par
$ ppmtompeg -realquiet /tmp/ppmtompeg-test.par
$ test -s /path/to/frames/movie.mpg.new && echo 'non-empty MPEG output'
non-empty MPEG output

The first command creates a temporary copy of the parameter file. It does not alter the original, but adjust the replacement if your output name contains a different string. A zero exit status means the encode completed. A non-zero status means you should read the error before trying another option.

If you prefer progress messages, omit -realquiet. The default -quiet 0 reports an estimate after each frame. That estimate does not include time spent reading frames, so a quiet period is not proof that the process has stopped.

5. Verify the result and promote it

Check that the output is present and non-empty before replacing a final destination:

$ file /path/to/frames/movie.mpg.new
$ stat --format='bytes=%s' /path/to/frames/movie.mpg.new
bytes=... 

The exact file description and byte count vary with the frames and settings. A non-empty file only proves that the encoder wrote data, not that every player will accept the stream. Open it with a player or inspect it with a suitable media tool installed on your system.

When the result is correct, replace the old destination in one deliberate step. This is the only state-changing command in the workflow:

$ mv -- /path/to/frames/movie.mpg.new /path/to/frames/movie.mpg
$ test -s /path/to/frames/movie.mpg && echo 'final output ready'
final output ready

If the encode failed, remove only the temporary .new file after checking its path. The original output remains untouched. Do not use a broad wildcard such as rm *.mpg as a recovery step.

6. Use staged encoding when a long run needs recovery

For a long sequence, -gop encodes one numbered Group of Pictures, with the first GOP numbered 0, and writes a file with a .gop.N suffix. The options -gop, -frames, -combine_gops, and -combine_frames are mutually exclusive.

$ ppmtompeg -gop 0 /path/to/encode.par
$ ls -l /path/to/frames/movie.mpg.gop.0
$ ppmtompeg -combine_gops /path/to/combine.par

For combining GOPs, the parameter file needs SIZE and OUTPUT. With no explicit GOP_INPUT block, the program looks for the output name with .gop.N suffixes, starting at zero. Keep the same parameter file when possible so that the generated names and dimensions agree. If you mix files from separate encodes, specify them explicitly and check that they belong to compatible sequences.

-frames first last is a separate diagnostic workflow. It writes individual .frame.N files without GOP headers; -combine_frames then needs SIZE, GOP_SIZE, and OUTPUT. These intermediate files can consume substantial disk space. Check available space before starting, and remove only the known temporary files after the final stream has been checked.

7. Diagnose the usual failures

• A missing or unreadable image usually means that INPUT_DIR, a filename range, or file permissions are wrong. Check the exact path with ls -l and test -r.
• A malformed parameter file is often caused by lower-case keywords, a missing END_INPUT, or a conversion command that does not write an image to standard output. Compare the file with the working example rather than adding flags at random.
• YUV input needs SIZE because YUV files do not carry dimensions. Parallel mode also requires SIZE, with the same dimensions on every machine.
• A stream can encode successfully and still play incorrectly. Check the frame dimensions, frame rate, pattern, and qscale values before changing the output file extension.