com.twilio.rest.video.v1.CompositionCreator Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of twilio Show documentation
Show all versions of twilio Show documentation
Twilio Java Helper Library
/**
* This code was generated by
* \ / _ _ _| _ _
* | (_)\/(_)(_|\/| |(/_ v1.0.0
* / /
*/
package com.twilio.rest.video.v1;
import com.twilio.base.Creator;
import com.twilio.converter.Converter;
import com.twilio.converter.Promoter;
import com.twilio.exception.ApiConnectionException;
import com.twilio.exception.ApiException;
import com.twilio.exception.RestException;
import com.twilio.http.HttpMethod;
import com.twilio.http.Request;
import com.twilio.http.Response;
import com.twilio.http.TwilioRestClient;
import com.twilio.rest.Domains;
import java.net.URI;
import java.util.List;
import java.util.Map;
/**
* PLEASE NOTE that this class contains preview products that are subject to
* change. Use them with caution. If you currently do not have developer preview
* access, please contact [email protected].
*/
public class CompositionCreator extends Creator {
private final String roomSid;
private Map videoLayout;
private List audioSources;
private List audioSourcesExcluded;
private String resolution;
private Composition.Format format;
private URI statusCallback;
private HttpMethod statusCallbackMethod;
private Boolean trim;
/**
* Construct a new CompositionCreator.
*
* @param roomSid The SID of the Group Room with the media tracks to be used as
* composition sources
*/
public CompositionCreator(final String roomSid) {
this.roomSid = roomSid;
}
/**
* An object that describes the video layout of the composition in terms of
* regions. See Specifying
* Video Layouts for more info. Please, be aware that either video_layout or
* audio_sources have to be provided to get a valid creation request.
*
* @param videoLayout An object that describes the video layout of the
* composition
* @return this
*/
public CompositionCreator setVideoLayout(final Map videoLayout) {
this.videoLayout = videoLayout;
return this;
}
/**
* An array of track names from the same group room to merge into the new
* composition. Can include zero or more track names. The new composition
* includes all audio sources specified in `audio_sources` except for those
* specified in `audio_sources_excluded`. The track names in this parameter can
* include an asterisk as a wild card character, which will match zero or more
* characters in a track name. For example, `student*` includes `student` as
* well as `studentTeam`. Please, be aware that either video_layout or
* audio_sources have to be provided to get a valid creation request.
*
* @param audioSources An array of track names from the same group room to merge
* @return this
*/
public CompositionCreator setAudioSources(final List audioSources) {
this.audioSources = audioSources;
return this;
}
/**
* An array of track names from the same group room to merge into the new
* composition. Can include zero or more track names. The new composition
* includes all audio sources specified in `audio_sources` except for those
* specified in `audio_sources_excluded`. The track names in this parameter can
* include an asterisk as a wild card character, which will match zero or more
* characters in a track name. For example, `student*` includes `student` as
* well as `studentTeam`. Please, be aware that either video_layout or
* audio_sources have to be provided to get a valid creation request.
*
* @param audioSources An array of track names from the same group room to merge
* @return this
*/
public CompositionCreator setAudioSources(final String audioSources) {
return setAudioSources(Promoter.listOfOne(audioSources));
}
/**
* An array of track names to exclude. The new composition includes all audio
* sources specified in `audio_sources` except for those specified in
* `audio_sources_excluded`. The track names in this parameter can include an
* asterisk as a wild card character, which will match zero or more characters
* in a track name. For example, `student*` excludes `student` as well as
* `studentTeam`. This parameter can also be empty..
*
* @param audioSourcesExcluded An array of track names to exclude
* @return this
*/
public CompositionCreator setAudioSourcesExcluded(final List audioSourcesExcluded) {
this.audioSourcesExcluded = audioSourcesExcluded;
return this;
}
/**
* An array of track names to exclude. The new composition includes all audio
* sources specified in `audio_sources` except for those specified in
* `audio_sources_excluded`. The track names in this parameter can include an
* asterisk as a wild card character, which will match zero or more characters
* in a track name. For example, `student*` excludes `student` as well as
* `studentTeam`. This parameter can also be empty..
*
* @param audioSourcesExcluded An array of track names to exclude
* @return this
*/
public CompositionCreator setAudioSourcesExcluded(final String audioSourcesExcluded) {
return setAudioSourcesExcluded(Promoter.listOfOne(audioSourcesExcluded));
}
/**
* A string that describes the columns (width) and rows (height) of the
* generated composed video in pixels. Defaults to `640x480`.
* The string's format is `{width}x{height}` where:
*
* * 16 <= `{width}` <= 1280
* * 16 <= `{height}` <= 1280
* * `{width}` * `{height}` <= 921,600
*
* Typical values are:
*
* * HD = `1280x720`
* * PAL = `1024x576`
* * VGA = `640x480`
* * CIF = `320x240`
*
* Note that the `resolution` imposes an aspect ratio to the resulting
* composition. When the original video tracks are constrained by the aspect
* ratio, they are scaled to fit. See Specifying
* Video Layouts for more info..
*
* @param resolution A string that describes the columns (width) and rows
* (height) of the generated composed video in pixels
* @return this
*/
public CompositionCreator setResolution(final String resolution) {
this.resolution = resolution;
return this;
}
/**
* The container format of the composition's media files. Can be: `mp4` or
* `webm` and the default is `webm`. If you specify `mp4` or `webm`, you must
* also specify one or more `audio_sources` and/or a `video_layout` element that
* contains a valid `video_sources` list, otherwise an error occurs..
*
* @param format The container format of the composition's media files
* @return this
*/
public CompositionCreator setFormat(final Composition.Format format) {
this.format = format;
return this;
}
/**
* The URL we should call using the `status_callback_method` to send status
* information to your application on every composition event. If not provided,
* status callback events will not be dispatched..
*
* @param statusCallback The URL we should call to send status information to
* your application
* @return this
*/
public CompositionCreator setStatusCallback(final URI statusCallback) {
this.statusCallback = statusCallback;
return this;
}
/**
* The URL we should call using the `status_callback_method` to send status
* information to your application on every composition event. If not provided,
* status callback events will not be dispatched..
*
* @param statusCallback The URL we should call to send status information to
* your application
* @return this
*/
public CompositionCreator setStatusCallback(final String statusCallback) {
return setStatusCallback(Promoter.uriFromString(statusCallback));
}
/**
* The HTTP method we should use to call `status_callback`. Can be: `POST` or
* `GET` and the default is `POST`..
*
* @param statusCallbackMethod The HTTP method we should use to call
* status_callback
* @return this
*/
public CompositionCreator setStatusCallbackMethod(final HttpMethod statusCallbackMethod) {
this.statusCallbackMethod = statusCallbackMethod;
return this;
}
/**
* Whether to clip the intervals where there is no active media in the
* composition. The default is `true`. Compositions with `trim` enabled are
* shorter when the Room is created and no Participant joins for a while as well
* as if all the Participants leave the room and join later, because those gaps
* will be removed. See Specifying
* Video Layouts for more info..
*
* @param trim Whether to clip the intervals where there is no active media in
* the composition
* @return this
*/
public CompositionCreator setTrim(final Boolean trim) {
this.trim = trim;
return this;
}
/**
* Make the request to the Twilio API to perform the create.
*
* @param client TwilioRestClient with which to make the request
* @return Created Composition
*/
@Override
@SuppressWarnings("checkstyle:linelength")
public Composition create(final TwilioRestClient client) {
Request request = new Request(
HttpMethod.POST,
Domains.VIDEO.toString(),
"/v1/Compositions"
);
addPostParams(request);
Response response = client.request(request);
if (response == null) {
throw new ApiConnectionException("Composition creation failed: Unable to connect to server");
} else if (!TwilioRestClient.SUCCESS.test(response.getStatusCode())) {
RestException restException = RestException.fromJson(response.getStream(), client.getObjectMapper());
if (restException == null) {
throw new ApiException("Server Error, no content");
}
throw new ApiException(restException);
}
return Composition.fromJson(response.getStream(), client.getObjectMapper());
}
/**
* Add the requested post parameters to the Request.
*
* @param request Request to add post params to
*/
private void addPostParams(final Request request) {
if (roomSid != null) {
request.addPostParam("RoomSid", roomSid);
}
if (videoLayout != null) {
request.addPostParam("VideoLayout", Converter.mapToJson(videoLayout));
}
if (audioSources != null) {
for (String prop : audioSources) {
request.addPostParam("AudioSources", prop);
}
}
if (audioSourcesExcluded != null) {
for (String prop : audioSourcesExcluded) {
request.addPostParam("AudioSourcesExcluded", prop);
}
}
if (resolution != null) {
request.addPostParam("Resolution", resolution);
}
if (format != null) {
request.addPostParam("Format", format.toString());
}
if (statusCallback != null) {
request.addPostParam("StatusCallback", statusCallback.toString());
}
if (statusCallbackMethod != null) {
request.addPostParam("StatusCallbackMethod", statusCallbackMethod.toString());
}
if (trim != null) {
request.addPostParam("Trim", trim.toString());
}
}
}