Open-source project
s60sc/ESP32-CAM_MJPEG2SD avatar
s60sc/ESP32-CAM_MJPEG2SD

ESP32-CAM_MJPEG2SD lists 22 features for a 4MB heap and asks you not to file issues

ESP32 Camera motion capture application to record JPEGs to SD card as AVI files and stream to browser as MJPEG. If a microphone is installed then a WAV file is also created. Files can be uploaded via FTP or downloaded to browser.

1,788 stars377 forksC++AGPL-3.0

At a glance

What is it?
An ESP32 firmware application that wraps camera JPEGs into AVI files on an SD card and streams them to a browser. The interesting parts are the budget it runs against, the frame rate table that prices two separate costs, and a maintainer note explaining that most of the incoming issues are the app working correctly.
Who is it for?
This is a serious piece of firmware for a device with 4MB of RAM, and the documentation is unusually direct about where that leads. Read the frame table before enabling anything: the throughput cost of the application is not spread evenly across frame sizes, and the detection latency grows by a factor of thirty from the smallest format to the largest.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • s60sc/ESP32-CAM_MJPEG2SD1,788 ★ · +67
Star history
Repository2026-09-112026-11-15
s60sc/ESP32-CAM_MJPEG2SD1.7k1.8k

67 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The app distinguishes its own errors from its own warnings, and users keep confusing them

The README carries a note in bold explaining that users are raising issues when the app reports a warning, and that this is the app telling the user there is a problem with their setup which only the user can fix. The request is to raise issues only for actual bugs, defined in parentheses as `ERR` messages, an unhandled library error, or a crash. Anything else belongs in Discussions.

So there is a convention here worth knowing before you start reading logs. A message prefixed `ERR` is the application's own signal that this is a genuine fault. Everything else it prints at warning level is configuration advice, and the maintainer is receiving tickets about it often enough to have written this paragraph.

The same note names the most common root cause: some clone boards have different specifications from the original, with PSRAM size given as the example. That is the thread running through the rest of the documentation, because the external memory is what the whole recording design is sized against.

There is also a grammar slip in that paragraph, an `an` where `a` belongs, which is worth noting only because it dates the note.

Twenty-two features competing for 4MB of external memory

The supported list runs to twenty-two items: motion detection by camera or by PIR, radar, or accelerometer, continuous time lapse and dashcam recording, audio from I2S or PDM microphones, pan and tilt servos with lamp control, an RTSP server carrying video, audio, and subtitles, telemetry recording, remote control of a camera-mounted vehicle, Telegram and email alerts, concurrent streaming to a browser and a remote NVR over HTTP or RTSP, transfer by FTP, HTTPS, WebDAV, or browser download, MQTT with Home Assistant, an external heartbeat, a list of named peripherals, a list of I2C devices, an interface for machine learning, a camera hub for reaching other devices, photogrammetry capture, an auxiliary board for extra pins, an intercom using the device and the browser, and an Ethernet option.

Then the caveat that governs all of it: the ESP32 cannot support all of the features, because it will run out of heap space.

The memory figure is specific. The ESP32 Cam module has 4MB of PSRAM, 8MB on most ESP32S3, and that is what buffers camera frames and the AVI file under construction. So the feature list is a menu rather than a specification, and which entries you can actually enable is decided by a memory budget you cannot see from the documentation.

The board advice follows from the same constraint. It points at the Freenove ESP32S3 Cam, the ESP32S3 XIAO Sense, and the AI Thinker style ESP32-S3-Cam, and tells you to avoid no-name boards marked `ESPS3 RE:1.0`.

The frame rate table prices two different costs, and the SD card label is not the ordering

The table sets the camera's maximum against what the application achieves, with detection time as a third column. At the small formats the two track closely: 96x96 and QQVGA both record 45 of the camera's 50 frames per second, with detection at 15ms and 20ms. From QVGA onward the application starts giving up frames, 40 against 50. At VGA it is 20 against 25. Then the gap opens: XGA, HD, SXGA, and UXGA all record 5 frames per second against a camera capable of 12.5, and detection time climbs from 180ms to 450ms.

So detection latency grows by a factor of thirty across the range while throughput loses a factor of two and a half, and the two costs do not peak in the same place. The middle formats pay the detection cost with latency. The large formats pay it with frame rate.

The measurements are tied to a stated configuration: a freshly formatted genuine Sandisk 4GB SDHC Class 2, an AI Thinker OV2640 board, maximum JPEG quality, and a 20MHz clock. The comparison offered alongside is that a no-name 4GB SDHC labelled Class 6 ran three times slower than that Class 2 card. The higher class number on the label, which is the figure a buyer would sort by, describes the slower card.

Raising the clock on the ESP32S3 to 24MHz moves the ceilings from 50 to 60 and 25 to 30, with the stated caveat that it may be necessary to reduce JPEG quality to hold those rates.

The default SD mode trades speed for two free pins, and that trade is wrong on the S3

By default the SD card is used in single-line MMC mode. The stated reason is that on the ESP32 it is practically as fast as four-line mode, and that it frees pin 4, which is wired to the onboard lamp, and pin 12, which can be used for something like a PIR sensor.

So the default is a pin-allocation decision, not a throughput decision. That is a reasonable call on the original ESP32, where the two modes measure the same. On the ESP32S3 the same default leaves performance on the table: tests contributed by a user indicate that four-line mode doubles the speed, with the result linked to a comment on issue 529.

Two things are worth noting about that finding. It is a measurement by a third party rather than something the project ran, and it is expressed as a doubling with no table behind it, unlike the frame rate figures which are given per format.

The paragraph also opens with a typo, dewdefault, which is a small indicator of how much editing that section has had.

AVI exists to make the flash write fewer and larger writes

The container choice is explained rather than assumed. The AVI format allows recordings to replay at the correct frame rate on media players, and saving a set of JPEGs as a single file is faster than as individual files and easier to manage, particularly at small image sizes.

The mechanism is buffer-oriented. PSRAM holds the camera frames and the AVI file being assembled, which minimises the number of SD writes, and those writes are aligned to the SD card's sector size. Playback reverses it: the file is read from the card into a buffer sized in multiples of a sector and sent to the browser as individually timed frames.

Filenames encode the recording parameters rather than just a timestamp. The format is `YYYYMMDD_HHMMSS` with the frame size, the recording rate in frames per second, and the duration in seconds appended, giving something like `20200130_201015_VGA_15_60.avi`, stored in a folder named for the day. Audio adds a trailing `_S` and telemetry adds a trailing `_M`, so the two are tracked as separate suffixes on the same base name. That example filename is dated January 2020, in documentation whose newest entry is for a 2026 release.

Timestamps come from an NTP server or from a connected browser client. Neither is required by the instructions, which for a motion-capture application means the filename can be the only thing wrong with an otherwise good recording.

Two tags six days apart with no commit between them, and a network server under AGPL

The release record has an odd shape. v10.8.3 is dated 2025-09-21. v10.9.7 is dated 2026-09-25T17:49:13Z, and the repository's last push is recorded at 2026-09-25T17:49:12Z, one second earlier. v10.9.8 is dated 2026-10-01, six days after the last push, with no commit in between.

So the newest release tag sits on a tree that has not moved since the previous one. The changelog header covers changes up to and including 10.9.8 in a single list of sixteen items, which is consistent with a bundled release, but the tag itself carries no new code. A year also separates 10.8.3 from 10.9.7, so the numbering moved a long way with one gap and then two releases landed within a week.

The licensing deserves a note rather than advice. The terms are AGPL-3.0 with a LICENSE file at the root. The application runs a web interface, serves an MJPEG stream, and offers an RTSP server to a remote NVR, which puts it squarely in the situation the AGPL network clause was written about, and it is also the kind of project most likely to be modified and put on a network rather than shipped as a binary.

One change in the newest entry touches certificates: remote server certificate handling was simplified to use the ESP-IDF bundled x509 certificate bundle, which trades a pinned certificate for a large shared trust store.

Installation is an Arduino sketch with a board define you edit by hand

There is no package manager, no PlatformIO manifest, and no build matrix in the tree. What is there is a header, a sketch, a LICENSE, the README, and four directories named `data/`, `extras/`, `src/`, and `ESP32-CAM_MJPEG2SD.h` alongside the `.ino` file.

The installation steps follow from that. Download the files into the Arduino IDE sketch folder, removing `-master` from the application folder name, which is a consequence of the default branch being called `master` so that GitHub's downloaded archive arrives as a folder the Arduino IDE will not recognise. Compile with at least arduino-esp32 core v3.1.1, cited as containing network fixes and frame selection changes. Then select the board by uncommenting exactly one of the `CAMERA_MODEL_*` defines in the header, with two defaults named: the AI Thinker model and the Freenove ESP32S3 Cam.

The instruction to uncomment one and only one is a compile-time constraint expressed as a manual edit, so a mismatch between the define and the actual board produces one of the setup warnings the maintainer has asked not to be reported.

Everything the application does on the network, then, runs from a sketch that was configured by editing a preprocessor line: alerts by Telegram and email, MQTT for Home Assistant, FTP, HTTPS, and WebDAV transfers, and the two streaming servers.

Editorial conclusion

This is a serious piece of firmware for a device with 4MB of RAM, and the documentation is unusually direct about where that leads. Read the frame table before enabling anything: the throughput cost of the application is not spread evenly across frame sizes, and the detection latency grows by a factor of thirty from the smallest format to the largest. Buy a board with the PSRAM the app assumes, since a clone that lies about it will produce setup warnings the maintainer has explicitly asked not to be reported. Verify your SD card against the Class 2 baseline rather than the class number on the label, and expect to build this in the Arduino IDE with a hand-edited board define rather than through a build system.

Frequently asked questions

What does ESP32-CAM_MJPEG2SD actually record?

Camera JPEG frames written to an SD card wrapped as AVI files, so that they replay at the correct frame rate in media players, plus an MJPEG stream to a browser. If an I2S or PDM microphone is fitted, a WAV is created and stored inside the AVI.

Why does ESP32-CAM_MJPEG2SD record 5 fps when the camera does 12.5?

The table separates the camera maximum from what the application reaches. At 96x96 it records 45 of 50 fps, while at XGA, HD, SXGA, and UXGA it records 5 of 12.5. Motion detection time also grows from 15ms at 96x96 to 450ms at UXGA.

Do I need the Arduino IDE to build ESP32-CAM_MJPEG2SD?

The instructions are to download the files into the Arduino IDE sketch folder, removing `-master` from the folder name, and compile with at least arduino-esp32 core v3.1.1. You then uncomment one of the `#define CAMERA_MODEL_*` values in `ESP32-CAM_MJPEG2SD.h`.

Can ESP32-CAM_MJPEG2SD use Ethernet instead of WiFi?

Yes, added in v10.9.8 as a network selection option instead of Wifi, with pins defined for the Waveshare ESP32-S3-ETH board and for an external W5500 Ethernet controller.

What license is ESP32-CAM_MJPEG2SD under?

AGPL-3.0, with a LICENSE file at the repository root. The application serves a web interface and an RTSP stream over the network, which is the deployment shape the AGPL network clause addresses.

Official sources

  1. Issues
  2. License: AGPL-3.0
  3. README
  4. Releases
  5. s60sc/ESP32-CAM_MJPEG2SD on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/s60sc-esp32-cam-mjpeg2sd.svg)](https://hysenlabs.com/projects/s60sc-esp32-cam-mjpeg2sd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/s60sc-esp32-cam-mjpeg2sd.svg)](https://hysenlabs.com/projects/s60sc-esp32-cam-mjpeg2sd)

Was this useful?