res/ari/resource_bridges: Add the ability to manipulate the video source

In multi-party bridges, Asterisk currently supports two video modes:
 * Follow the talker, in which the speaker with the most energy is shown
   to all participants but the speaker, and the speaker sees the
   previous video source
 * Explicitly set video sources, in which all participants see a locked
   video source

Prior to this patch, ARI had no ability to manipulate the video source.
This isn't important for two-party bridges, in which Asterisk merely
relays the video between the participants. However, in a multi-party
bridge, it can be advantageous to allow an external application to
manipulate the video source.

This patch provides two new routes to accomplish this:
(1) setVideoSource: POST /bridges/{bridgeId}/videoSource/{channelId}
    Sets a video source to an explicit channel
(2) clearVideoSource: DELETE /bridges/{bridgeId}/videoSource
    Removes any explicit video source, and sets the video mode to talk
    detection

ASTERISK-26595 #close

Change-Id: I98e455d5bffc08ea5e8d6b84ccaf063c714e6621

2 files changed, 97 insertions, 0 deletions

diff --git a/rest-api/api-docs/bridges.json b/rest-api/api-docs/bridges.json
index ab2c6c2d5..8289b43e1 100644
--- a/rest-api/api-docs/bridges.json
+++ b/rest-api/api-docs/bridges.json
@@ -241,6 +241,78 @@
 			]
 		},
 		{
+			"path": "/bridges/{bridgeId}/videoSource/{channelId}",
+			"description": "Set a channel as the video source in a multi-party bridge",
+			"operations": [
+				{
+					"httpMethod": "POST",
+					"summary": "Set a channel as the video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants.",
+					"nickname": "setVideoSource",
+					"responseClass": "void",
+					"parameters": [
+						{
+							"name": "bridgeId",
+							"description": "Bridge's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						},
+						{
+							"name": "channelId",
+							"description": "Channel's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 404,
+							"reason": "Bridge or Channel not found"
+						},
+						{
+							"code": 409,
+							"reason": "Channel not in Stasis application"
+						},
+						{
+							"code": 422,
+							"reason": "Channel not in this Bridge"
+						}
+					]
+				}
+			]
+		},
+		{
+			"path": "/bridges/{bridgeId}/videoSource",
+			"description": "Removes any explicit video source",
+			"operations": [
+				{
+					"httpMethod": "DELETE",
+					"summary": "Removes any explicit video source in a multi-party mixing bridge. This operation has no effect on bridges with two or fewer participants. When no explicit video source is set, talk detection will be used to determine the active video stream.",
+					"nickname": "clearVideoSource",
+					"responseClass": "void",
+					"parameters": [
+						{
+							"name": "bridgeId",
+							"description": "Bridge's id",
+							"paramType": "path",
+							"required": true,
+							"allowMultiple": false,
+							"dataType": "string"
+						}
+					],
+					"errorResponses": [
+						{
+							"code": 404,
+							"reason": "Bridge not found"
+						}
+					]
+				}
+			]
+		},
+		{
 			"path": "/bridges/{bridgeId}/moh",
 			"description": "Play music on hold to a bridge",
 			"operations": [
@@ -649,6 +721,16 @@
 					"type": "List[string]",
 					"description": "Ids of channels participating in this bridge",
 					"required": true
+				},
+				"video_mode": {
+					"type": "string",
+					"description": "The video mode the bridge is using. One of 'none', 'talker', or 'single'.",
+					"required": false
+				},
+				"video_source_id": {
+					"type": "string",
+					"description": "The ID of the channel that is the source of video in this bridge, if one exists.",
+					"required": false
 				}
 			}
 		}
diff --git a/rest-api/api-docs/events.json b/rest-api/api-docs/events.json
index 4ef1d21a4..f99f52e67 100644
--- a/rest-api/api-docs/events.json
+++ b/rest-api/api-docs/events.json
@@ -162,6 +162,7 @@
 				"BridgeMerged",
 				"BridgeBlindTransfer",
 				"BridgeAttendedTransfer",
+				"BridgeVideoSourceChanged",
 				"ChannelCreated",
 				"ChannelDestroyed",
 				"ChannelEnteredBridge",
@@ -370,6 +371,20 @@
 				}
 			}
 		},
+		"BridgeVideoSourceChanged": {
+			"id": "BridgeVideoSourceChanged",
+			"description": "Notification that the source of video in a bridge has changed.",
+			"properties": {
+				"bridge": {
+					"required": true,
+					"type": "Bridge"
+				},
+				"old_video_source_id": {
+					"required": false,
+					"type": "string"
+				}
+			}
+		},
 		"BridgeBlindTransfer": {
 			"id": "BridgeBlindTransfer",
 			"description": "Notification that a blind transfer has occurred.",