feat(jpeg): Add keyframe caching with expiration mechanism to JPEG http handler (#1155)

* feat(mjpeg): add keyframe caching with expiration and cleanup goroutine * mjpeg: make keyframe cache duration and default usage configurable * mjpeg: document and add config options for MJPEG snapshot caching * mjpeg: fix errors after rebase * Code refactoring for frame.jpeg cache #1155 --------- Co-authored-by: Alex X <alexey.khit@gmail.com>
2026-01-18 14:23:50 +03:00
parent 8c457710bd
commit 38cc05c22d
3 changed files with 92 additions and 31 deletions
@@ -1,3 +1,45 @@
+# MJPEG
+
+**Important.** For stream in MJPEG format, your source MUST contain the MJPEG codec. If your stream has an MJPEG codec, you can receive **MJPEG stream** or **JPEG snapshots** via API.
+
+You can receive an MJPEG stream in several ways:
+
+- some cameras support MJPEG codec inside [RTSP stream](#source-rtsp) (ex. second stream for Dahua cameras)
+- some cameras have an HTTP link with [MJPEG stream](#source-http)
+- some cameras have an HTTP link with snapshots - go2rtc can convert them to [MJPEG stream](#source-http)
+- you can convert H264/H265 stream from your camera via [FFmpeg integraion](#source-ffmpeg)
+
+With this example, your stream will have both H264 and MJPEG codecs:
+
+```yaml
+streams:
+  camera1:
+    - rtsp://rtsp:12345678@192.168.1.123/av_stream/ch0
+    - ffmpeg:camera1#video=mjpeg
+```
+
+## API examples
+
+**MJPEG stream**
+
+```
+http://192.168.1.123:1984/api/stream.mjpeg?src=camera1`
+```
+
+**JPEG snapshots**
+
+```
+http://192.168.1.123:1984/api/frame.jpeg?src=camera1
+```
+
+- You can use `width`/`w` and/or `height`/`h` params.
+- You can use `rotate` param with `90`, `180`, `270` or `-90` values.
+- You can use `hardware`/`hw` param [read more](https://github.com/AlexxIT/go2rtc/wiki/Hardware-acceleration).
+- You can use `cache` param (`1m`, `10s`, etc.) to get a cached snapshot.
+  - The snapshot is cached only when requested with the `cache` parameter.
+  - A cached snapshot will be used if its time is not older than the time specified in the `cache` parameter.
+  - The `cache` parameter does not check the image sizes from the cache and those specified in the query.
+
 ## Stream as ASCII to Terminal

 [![](https://img.youtube.com/vi/sHj_3h_sX7M/mqdefault.jpg)](https://www.youtube.com/watch?v=sHj_3h_sX7M)