mjpegparse

Problem

Many cameras provide output in MJPEG format, without providing option to acquire single JPEG frames.

Decoding MJPEG streams can be annoying. Debugging the same streams, especially when fiddling with their generation and making the headers, can also be annoying. There is a general lack of lightweight tools. Especially when piping data stream from eg. curl is desired.

Solution approach

• Try to look around the net for some utility, find either nothing or heavyweights, fail
• Write it in good ol' C

Command

mjpegparse - MJPEG stream parser
Reads MJPEG stream from a file, or from stdin ("-")

Usage: mjpegparse [options] <input file>
Options:
   -n <frames>  stop reading after n frames (0=never stop, default=10)
   -o <fname>   name of output file, default frame.jpg; prefix-only with numbers and timestamps, - for stdout
   -q           quiet; do not show headers
   -qq          quieter, do not show anything
   -sa          save all frames, implies numbering of filenames
   -s           save last frame, needs -n
   -N           do not save any file, just output messages
   -xts         use timestamps from X-Timestamp: headers
   -se          output messages to stderr (implied with -o -)
   -skip <n>    skip n frames in the beginning
   -nth <n>     output only each n-th frame
   -h           this help

Example:
curl http://webcam:8000/stream | parsemjpeg -n 5 -o snapsnot.jpg -s
fetches MJPEG stream, saves 5th image to snapshot.jpg

Features

stdin

Data can be fed to the process from a file, or from stdin. The "filename" for stdin is -.

output file names

For single file output, the filename can be directly set.

For multiple filenames, the initial "prefix" part of the filename is provided, with dash, frame number, and .jpg extension appended for each file.

remote timestamps

Some custom systems provide precision timestamps for each frame (X-Timestamp: header). These can be appended to the file name, if chosen by -xts option.

local timestamps

Frame filenames can be timestamped by the local time-of-arrival, using -lts option. Useful with realtime stdin input.

stdout

If - is specified as output filename, the jpeg frames are output to stdout. All other output is automatically sent to stderr.

stderr

Normally, non-error output data are sent to stdout. With -se option they can be sent to stderr instead.

verbosity

Normally, the tool outputs copious amount of messages about what it is doing, to provide operator awareness. This can be suppressed with -q and -qq options, for quiet and quieter, which first won't output the headers, then nothing else.

dry run

To see what will happen, without creating or overwriting files, -N option can be used.

total number of frames

Often it's not desirable to save an unlimited amount of the stream. Often only first few frames are enough, or even just one, but after skipping the first couple (to give the camera some time to run autoexposure and other amenities, if not already having done so), then the process exits. For this, -n <num> option is provided.

By default, n=10.

If n is set as 0,there is no limit.

skip initial frames

Sometimes the camera needs some time to adjust properly - set ADC, brightness... for that, some beginning frames can be skipped by -skip <n>.

skip intermediate frames

Full framerate may also not be desirable. For previews, timelapses, or just plain lowering amount of data to store, only each n-th frame can be saved. For that, use -nth <num>.

Examples

Receive stream from espcam, an ESP32 based wifi camera, on espcam.local; skip first frames, save 20th one to file.jpg and exit

Receive stream from espcam.local, save first 5 frames to files fileX.jpg, then exit

Receive stream from espcam.local, pipe 5th frame to jpegtopnm and convert to png

Receive stream from espcam.local, save first 100 frames to timestamped files in subdirectory f

Receive stream from espcam.local, use first 50 frames, skip first 3 frames, save each fifth frame (but do not actually save), local output to stderr, use both remote and local timestamp (remote clock is one hour less than local)

Download

Sources:

• mjpegparse.c - main source itself
• Makefile - compiling

Binaries (may not run on earlier or later systems, due to .so dependencies):

• mjpegparse - binary for x86 linux

TODO

• for stdin mode, use total run, skip and nth frames also in seconds instead of just raw frame count