From 6c7dfe592131eb95fd760ef2db83387966b250f0 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Fri, 21 Apr 2023 16:20:29 -0400 Subject: [PATCH] docs: add new fields to webcam documentation Signed-off-by: Eric Callahan --- docs/configuration.md | 16 +++++- docs/web_api.md | 117 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 120 insertions(+), 13 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index bee885e..8c589af 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -302,7 +302,7 @@ may be configured directly through front-ends and added to the database, however it is also possible for users to configure one or more webcams in `moonraker.conf`. If a webcam is configured in `moonraker.conf` it takes precedent over a webcam in the database by the same name. The options -available may not apply to all front-ends, refer to your front-end's +available may not apply to all front ends, refer to your front end's documentation for details on camera configuration. ```ini @@ -310,12 +310,20 @@ documentation for details on camera configuration. location: printer # A description of the webcam location, ie: what the webcam is observing. # The default is "printer". +icon: +# A name of the icon to use for the camera. The default is mdiWebcam. +enabled: True +# An optional boolean value to indicate if this webcam should be enabled. +# Default is True. service: mjpegstreamer # The name of the application or service hosting the webcam stream. Front- # ends may use this configuration to determine how to launch or start the # program. The default is "mjpegstreamer". target_fps: 15 # An integer value specifying the target framerate. The default is 15 fps. +target_fps_idle: 5 +# An integer value specifying the target framerate when the printer is idle. +# The default is 5 fps. stream_url: # The url for the camera stream request. This may be a full url or a # relative path (ie: /webcam?action=stream) if the stream is served on the @@ -323,7 +331,7 @@ stream_url: snapshot_url: # The url for the camera snapshot request. This may be a full url or a # relative path (ie: /webcam?action=stream) if the stream is served on the -# same host as Moonraker at port 80. This parameter must be provided. +# same host as Moonraker at port 80. The default is an empty url. flip_horizontal: False # A boolean value indicating whether the stream should be flipped # horizontally. The default is false. @@ -333,6 +341,10 @@ flip_vertical: False rotation: 0 # An integer value indicating the amount of clockwise rotation to apply # to the stream. May be 0, 90, 180, or 270. The default is 0. +aspect_ratio: 4:3 +# The aspect ratio to display for the camera. Note that this option +# is specific to certain services, otherwise it is ignored. +# The default is 4:3. ``` ## Optional Components diff --git a/docs/web_api.md b/docs/web_api.md index bff4344..eddfccf 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -3736,36 +3736,51 @@ A list of configured webcams: "name": "testcam3", "location": "door", "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", "target_fps": 20, + "target_fps_idle": 5, "stream_url": "http://camera.lan/webcam?action=stream", "snapshot_url": "http://camera.lan/webcam?action=snapshot", "flip_horizontal": false, "flip_vertical": true, "rotation": 90, + "aspect_ratio": "4:3", + "extra_data": {}, "source": "config" }, { "name": "tc2", "location": "printer", "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", "target_fps": 15, + "target_fps_idle": 5, "stream_url": "http://printer.lan/webcam?action=stream", "snapshot_url": "http://printer.lan/webcam?action=snapshot", "flip_horizontal": false, "flip_vertical": false, "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, "source": "database" }, { "name": "TestCam", "location": "printer", "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", "target_fps": 15, + "target_fps_idle": 5, "stream_url": "/webcam/?action=stream", "snapshot_url": "/webcam/?action=snapshot", "flip_horizontal": false, "flip_vertical": false, "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, "source": "database" } ] @@ -3806,18 +3821,26 @@ The full configuration for the requested webcam: "name": "TestCam", "location": "printer", "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", "target_fps": 15, + "target_fps_idle": 5, "stream_url": "/webcam/?action=stream", "snapshot_url": "/webcam/?action=snapshot", "flip_horizontal": false, "flip_vertical": false, "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, "source": "database" } } ``` #### Add or update a webcam +Adds a new webcam entry or updates an existing entry. When updating +an entry only the fields provided will be modified. + !!! Note A webcam configured via `moonraker.conf` cannot be updated or overwritten using this API. @@ -3851,30 +3874,42 @@ JSON-RPC request: Parameters: - `name`: The name of the camera to add or update. This parameter must - be provided. + be provided for new entries. - `location`: A description of the webcam location, ie: what the webcam is - observing. The default is "printer". + observing. The default is `printer` for new entries. +- `icon`: The name of the icon to use for the camera. The default is `mdiWebcam` + for new entries. +- `enabled`: A boolean value to indicate if this webcam should be enabled. + Default is True for new entries. - `service`: The name of the webcam application streaming service. The default - is "mjpegstreamer". -- `target_fps`: The target framerate. The default is 15 + is "mjpegstreamer" for new entries. +- `target_fps`: The target framerate. The default is 15 for new entries. +- `target_fps_idle`: The target framerate when the printer is idle. + The default is 5 for new entries. - `stream_url`: The url for the camera stream request. This may be a full url or a url relative to Moonraker's host machine. If the url is relative it is assumed that the stream is available over http on port 80. This parameter - must be provided. + must be provided for new entries. - `snapshot_url`: The url for the camera snapshot request. This may be a full url or a url relative to Moonraker's host machine. If the url is relative - it is assumed that the snapshot is available over http on port 80. This - parameter must be provided. + it is assumed that the snapshot is available over http on port 80. The + default is an empty string for new entries. - `flip_horizontal`: A boolean value indicating whether the stream should be - flipped horizontally. The default is false. + flipped horizontally. The default is false for new entries. - `flip_vertical`: A boolean value indicating whether the stream should be - flipped vertically. The default is false. + flipped vertically. The default is false for new entries. - `rotation`: An integer value indicating the amount of clockwise rotation to - apply to the stream. May be 0, 90, 180, or 270. The default is 0. + apply to the stream. May be 0, 90, 180, or 270. The default is 0 for new entries. +- `aspect_ratio`: The aspect ratio to display for the camera. Note that this option + is specific to certain services, otherwise it is ignored. The default is `4:3` + for new entries. +- `extra_data`: Additional webcam data set by the front end in the form of a json + object. This may be used to store any additional webcam options and/or data. The + default is an empty object for new entries. Returns: -The full configuration for the added webcam: +The full configuration for the added/updated webcam: ```json { @@ -3882,12 +3917,17 @@ The full configuration for the added webcam: "name": "TestCam", "location": "printer", "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", "target_fps": 15, + "target_fps_idle": 5, "stream_url": "/webcam/?action=stream", "snapshot_url": "/webcam/?action=snapshot", "flip_horizontal": false, "flip_vertical": false, "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, "source": "database" } } @@ -6503,6 +6543,61 @@ The `params` array contains an object with the following fields: a pending sudo request. The array will be empty if no sudo requests are pending. +#### Webcams changed event + +Moonraker will emit the `notify_webcams_changed` event when a configured +webcam is added, removed, or updated. + +```json +{ + "jsonrpc": "2.0", + "method": "notify_webcams_changed", + "params": [ + { + "webcams": [ + { + "name": "tc2", + "location": "printer", + "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", + "target_fps": 15, + "target_fps_idle": 5, + "stream_url": "http://printer.lan/webcam?action=stream", + "snapshot_url": "http://printer.lan/webcam?action=snapshot", + "flip_horizontal": false, + "flip_vertical": false, + "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, + "source": "database" + }, + { + "name": "TestCam", + "location": "printer", + "service": "mjpegstreamer", + "enabled": true, + "icon": "mdiWebcam", + "target_fps": 15, + "target_fps_idle": 5, + "stream_url": "/webcam/?action=stream", + "snapshot_url": "/webcam/?action=snapshot", + "flip_horizontal": false, + "flip_vertical": false, + "rotation": 0, + "aspect_ratio": "4:3", + "extra_data": {}, + "source": "database" + } + ] + } + ] +} +``` + +The `webcams` field contans an array of objects like those returned by the +[list webcams](#list-webcams) API. + #### Agent Events Moonraker will emit the `notify_agent_event` notification when it an agent event is received.