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.conversations;
017
018import com.fasterxml.jackson.annotation.JsonIgnore;
019import com.vonage.client.voice.TextToSpeechLanguage;
020import java.util.UUID;
021
022/**
023 * Represents an {@link EventType#AUDIO_SAY} event.
024 */
025public final class AudioSayEvent extends AudioOutEvent<AudioSayEventBody> {
026
027    AudioSayEvent() {}
028
029    private AudioSayEvent(Builder builder) {
030        super(builder);
031        body = new AudioSayEventBody(builder);
032    }
033
034    /**
035     * Unique audio say identifier.
036     *
037     * @return The say ID, or {@code null} if unknown.
038     */
039    @JsonIgnore
040    public UUID getSayId() {
041        return body != null ? body.sayId : null;
042    }
043
044    /**
045     * Text to be spoken.
046     *
047     * @return The speech text.
048     */
049    @JsonIgnore
050    public String getText() {
051        return body.text;
052    }
053
054    /**
055     * Text-to-speech voice style. See the
056     * <a href=https://developer.vonage.com/en/voice/voice-api/concepts/text-to-speech#supported-languagesVoice>
057     * Voice API documentation</a> for valid options.
058     *
059     * @return The TTS style as an Integer, or {@code null} if unspecified.
060     */
061    @JsonIgnore
062    public Integer getStyle() {
063        return body.style;
064    }
065
066    /**
067     * Language for the spoken text.
068     *
069     * @return The TTS language as an enum, or {@code null} if unspecified.
070     */
071    @JsonIgnore
072    public TextToSpeechLanguage getLanguage() {
073        return body.language;
074    }
075
076    /**
077     * Whether to use the premium version of the text-to-speech voice.
078     *
079     * @return {@code true} to use Premium TTS, or {@code null} if unspecified.
080     */
081    @JsonIgnore
082    public Boolean getPremium() {
083        return body.premium;
084    }
085
086    /**
087     * Whether to enable Synthesized Speech Markup Language (SSML).
088     *
089     * @return {@code true} to use SSML, or {@code null} if unspecified.
090     */
091    @JsonIgnore
092    public Boolean getSsml() {
093        return body.ssml;
094    }
095
096    /**
097     * Entry point for constructing an instance of this class.
098     *
099     * @return A new Builder.
100     */
101    public static Builder builder() {
102        return new Builder();
103    }
104
105    public static final class Builder extends AudioOutEvent.Builder<AudioSayEvent, Builder> {
106        String text;
107        Integer style;
108        TextToSpeechLanguage language;
109        Boolean premium, ssml;
110
111        Builder() {
112            super(EventType.AUDIO_SAY);
113        }
114
115        /**
116         * (REQUIRED) Text to be spoken.
117         *
118         * @param text The speech text.
119         * @return This builder.
120         */
121        public Builder text(String text) {
122            this.text = text;
123            return this;
124        }
125
126        /**
127         * Text-to-speech voice style. See the
128         * <a href=https://developer.vonage.com/en/voice/voice-api/concepts/text-to-speech#supported-languagesVoice>
129         * Voice API documentation</a> for valid options.
130         *
131         * @param style The TTS style as an int.
132         * @return This builder.
133         */
134        public Builder style(int style) {
135            this.style = style;
136            return this;
137        }
138
139        /**
140         * Language for the spoken text.
141         *
142         * @param language The TTS language as an enum.
143         * @return This builder.
144         */
145        public Builder language(TextToSpeechLanguage language) {
146            this.language = language;
147            return this;
148        }
149
150        /**
151         * Whether to use the premium version of the text-to-speech voice.
152         *
153         * @param premium {@code true} to use Premium TTS.
154         * @return This builder.
155         */
156        public Builder premium(boolean premium) {
157            this.premium = premium;
158            return this;
159        }
160
161        /**
162         * Whether to enable Synthesized Speech Markup Language (SSML).
163         *
164         * @param ssml {@code true} to use SSML.
165         * @return This builder.
166         */
167        public Builder ssml(boolean ssml) {
168            this.ssml = ssml;
169            return this;
170        }
171
172        @Override
173        public AudioSayEvent build() {
174            return new AudioSayEvent(this);
175        }
176    }
177}