From ecbe86153d438d5f6be943e2813eb1ef0f35ad71 Mon Sep 17 00:00:00 2001 From: Scott Lamb Date: Sun, 10 Oct 2021 15:58:55 -0700 Subject: [PATCH] improve API docs, including caveats and bugs For #178 --- design/api.md | 32 +++++++++++++++++++++++++------- design/glossary.md | 9 +++++++++ 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/design/api.md b/design/api.md index 7911a1c..726f241 100644 --- a/design/api.md +++ b/design/api.md @@ -438,8 +438,26 @@ It's normal for `/view.mp4` to return a media presentation with a length slightly different from the *wall duration* of the backing recording or portion that was requested. -TODO: error behavior on missing segment. It should be a 404, likely with an -`application/json` body describing what portion if any (still) exists. +Bugs and limitations: + +* If the `s=` parameter references a recording id that doesn't exist when the + server starts processing the `/view.mp4` request, the server will return a + `404` with a text error message. This commonly happens when the oldest + recording was deleted between the `/recordings` request and the `/view.mp4` + request. The server probably should return a structured JSON document + describing exactly which recordings have been deleted. For now, the client + will have to retry from `/recordings` and again race against deletion. +* If a recording is deleted after the server starts processing `/view.mp4` + but before the request advances to the recording's byte position, the server + will abruptly drop the HTTP connection. The client must then retry to see + a proper 404 error. It'd be better if the server would prevent recordings + from being deleted while there are `/view.mp4` requests in progress which + reference them. +* The final recording in every "run" ends with a frame that has duration 0. + It's not possible to append additional segments after such a frame; + the server will return an error like `Invalid argument: unable to append + recording 2/16672 after recording 2/16671 with trailing zero`. + (See [#178](https://github.com/scottlamb/moonfire-nvr/issues/178).) ### `GET /api/cameras///view.mp4.txt` @@ -477,11 +495,11 @@ Expected query parameters: * `s` (one or more): as with the `.mp4` URL. It's recommended that each `.m4s` retrieval be for at most one Moonfire NVR -recording segment. The fundamental reason is that the Media Source Extension -API appears structured for adding a complete segment at a time. Large media -segments thus impose significant latency on seeking. Additionally, because of -this fundamental reason Moonfire NVR makes no effort to make multiple-segment -`.m4s` requests practical: +recording. The fundamental reason is that the Media Source Extension API appears +structured for adding a complete segment at a time. Large media segments thus +impose significant latency on seeking. Additionally, because of this fundamental +reason Moonfire NVR makes no effort to make multiple-segment `.m4s` requests +practical: * There is currently a hard limit of 4 GiB of data because the `.m4s` uses a single `moof` followed by a single `mdat`; the former references the diff --git a/design/glossary.md b/design/glossary.md index 86d1d46..d44bc7b 100644 --- a/design/glossary.md +++ b/design/glossary.md @@ -1,5 +1,14 @@ # Moonfire NVR Glossary +*GOP:* Group of Pictures, as +[described](https://en.wikipedia.org/wiki/Group_of_pictures) on wikipedia. +Each GOP starts with an "IDR" or "key" frame which can be decoded by itself. +Commonly all other frames in the GOP are encoded in terms of the frames before, +so decoding frame 5 requires decoding frame 1, 2, 3, and 4. Many security +cameras produce a new IDR frame (thus start a new GOP) at a fixed interval of +1 or 2 seconds. Some cameras that use "smart encoding" or "H.264+" may produce +GOPs that vary in length, up to several seconds. + *media duration:* the total duration of the actual samples in a recording. These durations are based on the camera's clock. Camera clocks can be quite inaccurate, so this may not match the *wall duration*. See [time.md](time.md)