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