1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.composer.api;
23
24 import org.opencastproject.composer.layout.Dimension;
25 import org.opencastproject.job.api.Job;
26 import org.opencastproject.mediapackage.Attachment;
27 import org.opencastproject.mediapackage.MediaPackageException;
28 import org.opencastproject.mediapackage.Track;
29 import org.opencastproject.smil.entity.api.Smil;
30 import org.opencastproject.util.data.Option;
31
32 import java.util.List;
33 import java.util.Map;
34
35 /**
36 * Encodes media and (optionally) periodically alerts a statusService endpoint of the status of this encoding job.
37 */
38 public interface ComposerService {
39
40 String JOB_TYPE = "org.opencastproject.composer";
41
42 /** Used as mediaType to mark the source to omit processing of audio or video stream for process smil */
43 String AUDIO_ONLY = "a";
44 String VIDEO_ONLY = "v";
45
46 /** sourceAudioName options for composite - use one or both, if null is passed, both will be used */
47 String UPPER = "upper";
48 String LOWER = "lower";
49 String BOTH = "both";
50
51 /**
52 * Encode one track, using that track's audio and video streams.
53 *
54 * @param sourceTrack
55 * The source track
56 * @param profileId
57 * The profile to use for encoding
58 * @return The receipt for this encoding job. The receipt can be used with ComposerService#getJob to
59 * obtain the status of an encoding job.
60 * @throws EncoderException
61 * @throws MediaPackageException
62 */
63 Job encode(Track sourceTrack, String profileId) throws EncoderException, MediaPackageException;
64
65 /**
66 * Encode the video stream from one track and the audio stream from another, into a new Track.
67 *
68 * @param sourceVideoTrack
69 * The source video track
70 * @param sourceAudioTrack
71 * The source audio track
72 * @param profileId
73 * The profile to use for encoding
74 * @return The receipt for this encoding job
75 * @throws EncoderException
76 * if encoding fails
77 * @throws MediaPackageException
78 * if the mediapackage is invalid
79 */
80 Job mux(Track sourceVideoTrack, Track sourceAudioTrack, String profileId) throws EncoderException,
81 MediaPackageException;
82
83 /**
84 * Compose two videos into one with an optional watermark.
85 *
86 * @param outputDimension
87 * The composite track dimension
88 * @param option
89 * upper track element from mediapackage (optional)
90 * @param lowerLaidOutElement
91 * lower track element from mediapackage
92 * @param watermarkOption
93 * watermark element (optional)
94 * @param identifier
95 * Encoding profile name
96 * @param outputBackground
97 * The background color
98 * @param sourceAudioName
99 * Use audio from only lower or upper track or both, use both when available if omitted
100 * @return The receipt for this composite job
101 * @throws EncoderException
102 * if encoding fails
103 * @throws MediaPackageException
104 * if the mediapackage is invalid
105 */
106
107 Job composite(Dimension outputDimension, Option<LaidOutElement<Track>> option,
108 LaidOutElement<Track> lowerLaidOutElement, Option<LaidOutElement<Attachment>> watermarkOption,
109 String identifier, String outputBackground, String sourceAudioName) throws EncoderException, MediaPackageException;
110
111 /**
112 * Concat multiple tracks to a single track.
113 *
114 * @param profileId
115 * The encoding profile to use
116 * @param outputDimension
117 * The output dimensions
118 * @param sameCodec Defines if lossless concat should be used
119 * @param tracks
120 * an array of track to concat in order of the array
121 * @return The receipt for this concat job
122 * @throws EncoderException
123 * if encoding fails
124 * @throws MediaPackageException
125 * if the mediapackage is invalid
126 */
127 Job concat(String profileId, Dimension outputDimension, boolean sameCodec, Track... tracks) throws EncoderException,
128 MediaPackageException;
129
130 /**
131 * Concat multiple tracks to a single track. Required ffmpeg version 1.1
132 *
133 * @param profileId The encoding profile to use
134 * @param outputDimension The output dimensions
135 * @param outputFrameRate The output frame rate
136 * @param sameCodec Defines if lossless concat should be used
137 * @param tracks an array of track to concat in order of the array
138 * @return The receipt for this concat job
139 * @throws EncoderException if encoding fails
140 * @throws MediaPackageException if the mediapackage is invalid
141 */
142 Job concat(String profileId, Dimension outputDimension, float outputFrameRate, boolean sameCodec, Track... tracks) throws EncoderException,
143 MediaPackageException;
144
145 /**
146 * Transforms an image attachment to a video track
147 *
148 * @param sourceImageAttachment
149 * The source image attachment
150 * @param profileId
151 * The profile to use for encoding
152 * @param duration
153 * the length of the resulting video track in seconds
154 * @return The receipt for this image to video job
155 * @throws EncoderException
156 * if encoding fails
157 * @throws MediaPackageException
158 * if the mediapackage is invalid
159 */
160 Job imageToVideo(Attachment sourceImageAttachment, String profileId, double duration) throws EncoderException,
161 MediaPackageException;
162
163 /**
164 * Trims the given track to the given start time and duration.
165 *
166 * @param sourceTrack
167 * The source track
168 * @param profileId
169 * The profile to use for trimming
170 * @param start
171 * start time in miliseconds
172 * @param duration
173 * duration in miliseconds
174 * @return The receipt for this encoding job. The receipt can be used with ComposerService#getJob to
175 * obtain the status of an encoding job.
176 * @throws EncoderException
177 * if trimming fails
178 * @throws MediaPackageException
179 * if the mediapackage is invalid
180 */
181 Job trim(Track sourceTrack, String profileId, long start, long duration) throws EncoderException,
182 MediaPackageException;
183
184 /**
185 * Extracts an image from the media package element identified by <code>sourceVideoTrackId</code>. The image is taken
186 * at the timepoint <code>time</code> seconds into the movie.
187 *
188 * @param sourceTrack
189 * the source video track
190 * @param profileId
191 * identifier of the encoding profile
192 * @param time
193 * number of seconds into the video
194 * @return the extracted image as an attachment
195 * @throws EncoderException
196 * if image extraction fails
197 * @throws MediaPackageException
198 * if the mediapackage is invalid
199 */
200 // TODO revise
201 Job image(Track sourceTrack, String profileId, double... time) throws EncoderException, MediaPackageException;
202
203 /**
204 * Synchronously extracts images from the source track. The images are taken at the given timepoints (seconds into
205 * the movie). Please note that synchronously doing this means, that the workload cannot be distributed amongst all
206 * nodes. This should be used rarely.
207 *
208 * @param sourceTrack
209 * the source video track
210 * @param profileId
211 * identifier of the encoding profile
212 * @param time
213 * number of seconds into the video
214 * @return the extracted images as attachments
215 * @throws EncoderException
216 * if image extraction fails
217 * @throws MediaPackageException
218 * if the mediapackage is invalid
219 */
220 List<Attachment> imageSync(Track sourceTrack, String profileId, double... time) throws EncoderException,
221 MediaPackageException;
222
223 /**
224 * Extracts an image from the media package element identified by <code>sourceTrack</code>. The image is taken by the
225 * given properties and the corresponding encoding profile.
226 *
227 * @param sourceTrack
228 * the source video track
229 * @param profileId
230 * identifier of the encoding profile
231 * @param properties
232 * the properties applied to the encoding profile
233 * @return the extracted image as an attachment
234 * @throws EncoderException
235 * if image extraction fails
236 * @throws MediaPackageException
237 * if the mediapackage is invalid
238 */
239 Job image(Track sourceTrack, String profileId, Map<String, String> properties) throws EncoderException,
240 MediaPackageException;
241
242 /**
243 * Converts the given image to a different image format using the specified image profiles.
244 *
245 * @param image
246 * the image
247 * @param profileIds
248 * the profiles to use for conversion
249 * @return the job for the image conversion
250 * @throws EncoderException
251 * if image conversion fails
252 * @throws MediaPackageException
253 * if the mediapackage is invalid
254 */
255 Job convertImage(Attachment image, String... profileIds) throws EncoderException, MediaPackageException;
256
257
258 /**
259 * Synchronously converts the given image to different image formats using the specified encoding profiles. Please
260 * note that synchronously doing this means that the workload cannot be distributed amongst all nodes.
261 *
262 * @param image
263 * the image
264 * @param profileIds
265 * the profiles to use for conversion
266 * @return the converted images
267 * @throws EncoderException
268 * if image conversion fails
269 * @throws MediaPackageException
270 * if the mediapackage is invalid
271 */
272 List<Attachment> convertImageSync(Attachment image, String... profileIds) throws EncoderException,
273 MediaPackageException;
274
275
276 /**
277 * @return All registered {@link EncodingProfile}s.
278 */
279 EncodingProfile[] listProfiles();
280
281 /**
282 * Gets a profile by its ID
283 *
284 * @param profileId
285 * The profile ID
286 * @return The encoding profile, or null if no profile is registered with that ID
287 */
288 EncodingProfile getProfile(String profileId);
289
290 /**
291 * Encode one track to multiple other tracks in one encoding operation, using that track's audio and video streams.
292 *
293 * @param sourceTrack
294 * The source track
295 * @param profileId
296 * The profile to use for encoding
297 * @throws EncoderException
298 * @throws MediaPackageException
299 */
300 Job parallelEncode(Track sourceTrack, String profileId) throws EncoderException, MediaPackageException;
301
302 /**
303 * Demux a multi-track source into 2 media as defined by the encoding profile, the results are flavored and tagged
304 * positionally. eg: One ffmpeg operation to produce presenter/work and presentation/work
305 *
306 * @param sourceTrack
307 * @param profileId
308 * @return Receipt for this demux based on the profile
309 * @throws EncoderException
310 * @throws MediaPackageException
311 */
312 Job demux(Track sourceTrack, String profileId) throws EncoderException, MediaPackageException;
313
314 /**
315 * Reads a smil definition and create one media track in multiple delivery formats. The track in the smil is selected
316 * by "trackParamGroupId" which is the paramGroup in the smil The multiple delivery formats are determined by a list
317 * of encoding profiles by name. The resultant tracks will be tagged by profile name. The smil file can contain more
318 * than one source track but they must have the same dimension. This is used mainly on smil.xml from the editor. There
319 * is a configurable fadein/fadeout between each clip (default is 2s).
320 *
321 * @param smil
322 * - Describes one media (can contain multiple source in ws) and editing instructions (in out points of video
323 * clips) for concatenation into one video with transitions
324 * @param trackParamGroupId
325 * - track group id to process, if missing, will process first track found in smil
326 * @param mediaType
327 * - v for videoOnly, a for audioOnly, anything else is AudioVisual
328 * @param profileIds
329 * - Encoding profiles for each output from this media
330 * @return Receipt for this processing based on the smil file and the list of profiles
331 * @throws EncoderException
332 * @throws MediaPackageException
333 */
334
335 Job processSmil(Smil smil, String trackParamGroupId, String mediaType, List<String> profileIds)
336 throws EncoderException, MediaPackageException;
337
338 /**
339 * Encodes a track to set of media targets as defined by a list of encoding profiles
340 *
341 * @param track
342 * - video or audio track
343 * @param profileIds
344 * - a list of encoding profiles by name
345 * @return Receipt for this processing based on the inputs
346 * @throws EncoderException
347 * if it fails
348 * @throws MediaPackageException
349 * if adding files to a mediapackage produces errors
350 */
351 Job multiEncode(Track track, List<String> profileIds) throws EncoderException, MediaPackageException;
352
353 }