001/*
002 *   Copyright 2024 Vonage
003 *
004 *   Licensed under the Apache License, Version 2.0 (the "License");
005 *   you may not use this file except in compliance with the License.
006 *   You may obtain a copy of the License at
007 *
008 *        http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *   Unless required by applicable law or agreed to in writing, software
011 *   distributed under the License is distributed on an "AS IS" BASIS,
012 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *   See the License for the specific language governing permissions and
014 *   limitations under the License.
015 */
016package com.vonage.client.video;
017
018import com.fasterxml.jackson.annotation.JsonProperty;
019import java.util.Arrays;
020import java.util.Collection;
021import java.util.Map;
022
023/**
024 * Defines properties used for Audio Connector.
025 *
026 * @since 8.5.0
027 */
028public final class ConnectRequest extends AbstractSessionTokenRequest {
029    private Websocket websocket;
030
031    private ConnectRequest() {}
032
033    private ConnectRequest(Builder builder) {
034        super(builder);
035        websocket = new Websocket(builder);
036    }
037
038    /**
039     * WebSocket parameters.
040     *
041     * @return The websocket properties.
042     */
043    @JsonProperty("websocket")
044    public Websocket getWebsocket() {
045        return websocket;
046    }
047
048    /**
049     * Entry point for constructing an instance of this class.
050     *
051     * @return A new Builder.
052     */
053    public static Builder builder() {
054        return new Builder();
055    }
056
057    /**
058     * Builder for defining the fields in a ConnectRequest object.
059     */
060    public static final class Builder extends AbstractSessionTokenRequest.Builder<ConnectRequest, Builder> {
061        String uri;
062        Collection<String> streams;
063        Map<String, String> headers;
064        Websocket.AudioRate audioRate;
065
066        private Builder() {
067        }
068
069        /**
070         * (REQUIRED)
071         * A valid Vonage Video token for the Audio Connector connection to the Vonage Video Session.
072         * You can add additional data to the JWT to identify that the connection is the Audio Connector
073         * endpoint or for any other identifying data.
074         *
075         * @param token The Base64-encoded JWT as a string.
076         *
077         * @return This builder.
078         */
079        @Override
080        public Builder token(String token) {
081            return super.token(token);
082        }
083
084        /**
085         * The Vonage Video session ID that includes the Vonage Video streams you want to include in the
086         * WebSocket stream. The Audio Connector feature is only supported in routed sessions.
087         *
088         * @param sessionId The session ID as a string.
089         *
090         * @return This builder.
091         */
092        @Override
093        public Builder sessionId(String sessionId) {
094            return super.sessionId(sessionId);
095        }
096
097        /**
098         * (REQUIRED)
099         * A publicly reachable WebSocket URI to be used for the destination of the audio stream.
100         * This must start with the {@code ws://} or {@code wss://} protocol.
101         *
102         * @param uri The WebSocket URI as a string.
103         *
104         * @return This builder.
105         */
106        public Builder uri(String uri) {
107            this.uri = uri;
108            return this;
109        }
110
111        /**
112         * (OPTIONAL)
113         * An array of stream IDs for the Vonage Video streams you want to include in the WebSocket audio.
114         * If you omit this property, all streams in the session will be included.
115         *
116         * @param streams The stream IDs to include in the audio.
117         *
118         * @return This builder.
119         */
120        public Builder streams(String... streams) {
121            return streams(Arrays.asList(streams));
122        }
123
124        /**
125         * A collection of stream IDs for the Vonage Video streams you want to include in the WebSocket audio.
126         * If you omit this property, all streams in the session will be included.
127         *
128         * @param streams The stream IDs to include in the audio connection.
129         *
130         * @return This builder.
131         */
132        public Builder streams(Collection<String> streams) {
133            this.streams = streams;
134            return this;
135        }
136
137        /**
138         * Key-value pairs of headers to be sent to your WebSocket server with each message,
139         * with a maximum length of 512 bytes.
140         *
141         * @param headers The custom request headers as a Map.
142         *
143         * @return This builder.
144         */
145        public Builder headers(Map<String, String> headers) {
146            this.headers = headers;
147            return this;
148        }
149
150        /**
151         * A number representing the audio sampling rate in Hz.
152         *
153         * @param audioRate The sampling rate as an enum.
154         *
155         * @return This builder.
156         */
157        public Builder audioRate(Websocket.AudioRate audioRate) {
158            this.audioRate = audioRate;
159            return this;
160        }
161
162        /**
163         * Builds the ConnectRequest object.
164         *
165         * @return The ConnectRequest object with this builder's settings.
166         */
167        @Override
168        public ConnectRequest build() {
169            return new ConnectRequest(this);
170        }
171    }
172}