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
31 import java.util.List;
32 import java.util.Map;
33 import java.util.Optional;
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 * Mux multiple tracks into a new Track.
85 *
86 * @param sourceTracks
87 * The source tracks
88 * @param profileId
89 * The profile to use for encoding
90 * @return The receipt for this encoding job
91 * @throws EncoderException
92 * if encoding fails
93 * @throws MediaPackageException
94 * if the mediapackage is invalid
95 */
96 Job mux(Map<String, Track> sourceTracks, String profileId) throws EncoderException, MediaPackageException;
97
98 /**
99 * Compose two videos into one with an optional watermark.
100 *
101 * @param outputDimension
102 * The composite track dimension
103 * @param option
104 * upper track element from mediapackage (optional)
105 * @param lowerLaidOutElement
106 * lower track element from mediapackage
107 * @param watermarkOption
108 * watermark element (optional)
109 * @param identifier
110 * Encoding profile name
111 * @param outputBackground
112 * The background color
113 * @param sourceAudioName
114 * Use audio from only lower or upper track or both, use both when available if omitted
115 * @return The receipt for this composite job
116 * @throws EncoderException
117 * if encoding fails
118 * @throws MediaPackageException
119 * if the mediapackage is invalid
120 */
121
122 Job composite(Dimension outputDimension, Optional<LaidOutElement<Track>> option,
123 LaidOutElement<Track> lowerLaidOutElement, Optional<LaidOutElement<Attachment>> watermarkOption,
124 String identifier, String outputBackground, String sourceAudioName)
125 throws EncoderException, MediaPackageException;
126
127 /**
128 * Concat multiple tracks to a single track.
129 *
130 * @param profileId
131 * The encoding profile to use
132 * @param outputDimension
133 * The output dimensions
134 * @param sameCodec Defines if lossless concat should be used
135 * @param tracks
136 * an array of track to concat in order of the array
137 * @return The receipt for this concat job
138 * @throws EncoderException
139 * if encoding fails
140 * @throws MediaPackageException
141 * if the mediapackage is invalid
142 */
143 Job concat(String profileId, Dimension outputDimension, boolean sameCodec, Track... tracks) throws EncoderException,
144 MediaPackageException;
145
146 /**
147 * Concat multiple tracks to a single track. Required ffmpeg version 1.1
148 *
149 * @param profileId The encoding profile to use
150 * @param outputDimension The output dimensions
151 * @param outputFrameRate The output frame rate
152 * @param sameCodec Defines if lossless concat should be used
153 * @param tracks an array of track to concat in order of the array
154 * @return The receipt for this concat job
155 * @throws EncoderException if encoding fails
156 * @throws MediaPackageException if the mediapackage is invalid
157 */
158 Job concat(String profileId, Dimension outputDimension, float outputFrameRate, boolean sameCodec, Track... tracks)
159 throws EncoderException, MediaPackageException;
160
161 /**
162 * Transforms an image attachment to a video track
163 *
164 * @param sourceImageAttachment
165 * The source image attachment
166 * @param profileId
167 * The profile to use for encoding
168 * @param duration
169 * the length of the resulting video track in seconds
170 * @return The receipt for this image to video job
171 * @throws EncoderException
172 * if encoding fails
173 * @throws MediaPackageException
174 * if the mediapackage is invalid
175 */
176 Job imageToVideo(Attachment sourceImageAttachment, String profileId, double duration) throws EncoderException,
177 MediaPackageException;
178
179 /**
180 * Trims the given track to the given start time and duration.
181 *
182 * @param sourceTrack
183 * The source track
184 * @param profileId
185 * The profile to use for trimming
186 * @param start
187 * start time in miliseconds
188 * @param duration
189 * duration in miliseconds
190 * @return The receipt for this encoding job. The receipt can be used with ComposerService#getJob to
191 * obtain the status of an encoding job.
192 * @throws EncoderException
193 * if trimming fails
194 * @throws MediaPackageException
195 * if the mediapackage is invalid
196 */
197 Job trim(Track sourceTrack, String profileId, long start, long duration) throws EncoderException,
198 MediaPackageException;
199
200 /**
201 * Extracts an image from the media package element identified by <code>sourceVideoTrackId</code>. The image is taken
202 * at the timepoint <code>time</code> seconds into the movie.
203 *
204 * @param sourceTrack
205 * the source video track
206 * @param profileId
207 * identifier of the encoding profile
208 * @param time
209 * number of seconds into the video
210 * @return the extracted image as an attachment
211 * @throws EncoderException
212 * if image extraction fails
213 * @throws MediaPackageException
214 * if the mediapackage is invalid
215 */
216 // TODO revise
217 Job image(Track sourceTrack, String profileId, double... time) throws EncoderException, MediaPackageException;
218
219 /**
220 * Synchronously extracts images from the source track. The images are taken at the given timepoints (seconds into
221 * the movie). Please note that synchronously doing this means, that the workload cannot be distributed amongst all
222 * nodes. This should be used rarely.
223 *
224 * @param sourceTrack
225 * the source video track
226 * @param profileId
227 * identifier of the encoding profile
228 * @param time
229 * number of seconds into the video
230 * @return the extracted images as attachments
231 * @throws EncoderException
232 * if image extraction fails
233 * @throws MediaPackageException
234 * if the mediapackage is invalid
235 */
236 List<Attachment> imageSync(Track sourceTrack, String profileId, double... time) throws EncoderException,
237 MediaPackageException;
238
239 /**
240 * Extracts an image from the media package element identified by <code>sourceTrack</code>. The image is taken by the
241 * given properties and the corresponding encoding profile.
242 *
243 * @param sourceTrack
244 * the source video track
245 * @param profileId
246 * identifier of the encoding profile
247 * @param properties
248 * the properties applied to the encoding profile
249 * @return the extracted image as an attachment
250 * @throws EncoderException
251 * if image extraction fails
252 * @throws MediaPackageException
253 * if the mediapackage is invalid
254 */
255 Job image(Track sourceTrack, String profileId, Map<String, String> properties) throws EncoderException,
256 MediaPackageException;
257
258 /**
259 * Converts the given image to a different image format using the specified image profiles.
260 *
261 * @param image
262 * the image
263 * @param profileIds
264 * the profiles to use for conversion
265 * @return the job for the image conversion
266 * @throws EncoderException
267 * if image conversion fails
268 * @throws MediaPackageException
269 * if the mediapackage is invalid
270 */
271 Job convertImage(Attachment image, String... profileIds) throws EncoderException, MediaPackageException;
272
273
274 /**
275 * Synchronously converts the given image to different image formats using the specified encoding profiles. Please
276 * note that synchronously doing this means that the workload cannot be distributed amongst all nodes.
277 *
278 * @param image
279 * the image
280 * @param profileIds
281 * the profiles to use for conversion
282 * @return the converted images
283 * @throws EncoderException
284 * if image conversion fails
285 * @throws MediaPackageException
286 * if the mediapackage is invalid
287 */
288 List<Attachment> convertImageSync(Attachment image, String... profileIds) throws EncoderException,
289 MediaPackageException;
290
291
292 /**
293 * @return All registered {@link EncodingProfile}s.
294 */
295 EncodingProfile[] listProfiles();
296
297 /**
298 * Gets a profile by its ID
299 *
300 * @param profileId
301 * The profile ID
302 * @return The encoding profile, or null if no profile is registered with that ID
303 */
304 EncodingProfile getProfile(String profileId);
305
306 /**
307 * Encode one track to multiple other tracks in one encoding operation, using that track's audio and video streams.
308 *
309 * @param sourceTrack
310 * The source track
311 * @param profileId
312 * The profile to use for encoding
313 * @throws EncoderException
314 * @throws MediaPackageException
315 */
316 Job parallelEncode(Track sourceTrack, String profileId) throws EncoderException, MediaPackageException;
317
318 /**
319 * Demux a multi-track source into 2 media as defined by the encoding profile, the results are flavored and tagged
320 * positionally. eg: One ffmpeg operation to produce presenter/work and presentation/work
321 *
322 * @param sourceTrack
323 * @param profileId
324 * @return Receipt for this demux based on the profile
325 * @throws EncoderException
326 * @throws MediaPackageException
327 */
328 Job demux(Track sourceTrack, String profileId) throws EncoderException, MediaPackageException;
329
330 /**
331 * Reads a smil definition and create one media track in multiple delivery formats. The track in the smil is selected
332 * by "trackParamGroupId" which is the paramGroup in the smil The multiple delivery formats are determined by a list
333 * of encoding profiles by name. The resultant tracks will be tagged by profile name. The smil file can contain more
334 * than one source track but they must have the same dimension. This is used mainly on smil.xml from the editor. There
335 * is a configurable fadein/fadeout between each clip (default is 2s).
336 *
337 * @param smil
338 * - Describes one media (can contain multiple source in ws) and editing instructions (in out points of video
339 * clips) for concatenation into one video with transitions
340 * @param trackParamGroupId
341 * - track group id to process, if missing, will process first track found in smil
342 * @param mediaType
343 * - v for videoOnly, a for audioOnly, anything else is AudioVisual
344 * @param profileIds
345 * - Encoding profiles for each output from this media
346 * @return Receipt for this processing based on the smil file and the list of profiles
347 * @throws EncoderException
348 * @throws MediaPackageException
349 */
350
351 Job processSmil(Smil smil, String trackParamGroupId, String mediaType, List<String> profileIds)
352 throws EncoderException, MediaPackageException;
353
354 /**
355 * Encodes a track to set of media targets as defined by a list of encoding profiles
356 *
357 * @param track
358 * - video or audio track
359 * @param profileIds
360 * - a list of encoding profiles by name
361 * @return Receipt for this processing based on the inputs
362 * @throws EncoderException
363 * if it fails
364 * @throws MediaPackageException
365 * if adding files to a mediapackage produces errors
366 */
367 Job multiEncode(Track track, List<String> profileIds) throws EncoderException, MediaPackageException;
368
369 }