MyFavMirrors/moonfire-nvr
1
0
Fork 0
mirror of https://github.com/scottlamb/moonfire-nvr.git synced 2025-01-11 15:03:23 -05:00
Code Issues Packages Projects Releases Wiki Activity

improve API docs, including caveats and bugs

Browse Source 
For #178
This commit is contained in:
Scott Lamb 2021-10-10 15:58:55 -07:00
parent 6671c3791f
commit ecbe86153d
2 changed files with 34 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
design/api.md
View File

@ -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/<uuid>/<stream>/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

9
design/glossary.md
View File

@ -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)