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.smil.api;
23
24 import org.opencastproject.mediapackage.MediaPackage;
25 import org.opencastproject.mediapackage.Track;
26 import org.opencastproject.smil.entity.api.Smil;
27
28 import java.io.File;
29
30 /**
31 * {@link SmilService} provides {@link Smil} manipulation.
32 */
33 public interface SmilService {
34
35 /**
36 * Create a new {@link Smil}.
37 *
38 * @return a new {@link Smil}
39 */
40 SmilResponse createNewSmil();
41
42 /**
43 * Create a new {@link Smil} and store the {@link MediaPackage} Id as meta
44 * data.
45 *
46 * @param mediaPackage
47 * @return a new {@link Smil}
48 */
49 SmilResponse createNewSmil(MediaPackage mediaPackage);
50
51 /**
52 * Add new par element to {@link Smil}.
53 *
54 * @param smil {@link Smil} to edit
55 * @return edited {@link Smil} and the new SmilMediaContainer
56 * @throws SmilException
57 */
58 SmilResponse addParallel(Smil smil) throws SmilException;
59
60 /**
61 * Add new par element to {@link Smil} inside an element with given Id.
62 *
63 * @param smil {@link Smil} to edit
64 * @param parentId element id, where to add new par element
65 * @return edited {@link Smil} and the new SmilMediaContainer
66 * @throws SmilException if there is no element with given parentId
67 */
68 SmilResponse addParallel(Smil smil, String parentId) throws SmilException;
69
70 /**
71 * Add new seq element to {@link Smil}.
72 *
73 * @param smil {@link Smil} to edit
74 * @return edited {@link Smil} and the new SmilMediaContainer
75 * @throws SmilException
76 */
77 SmilResponse addSequence(Smil smil) throws SmilException;
78
79 /**
80 * Add new seq element to {@link Smil} inside an element with given Id.
81 *
82 * @param smil {@link Smil} to edit
83 * @param parentId element id, where to add new seq element
84 * @return edited {@link Smil} and the new SmilMediaContainer
85 * @throws SmilException if there is no element with given parentId
86 */
87 SmilResponse addSequence(Smil smil, String parentId) throws SmilException;
88
89 /**
90 * Add a SmilMediaElement based on given track and start/duration
91 * information.
92 *
93 * @param smil {@link Smil} to edit
94 * @param parentId element id, where to add new SmilMediaElement
95 * @param track {@link Track} to add as SmilMediaElement
96 * @param start start position in {@link Track} in milliseconds
97 * @param duration duration in milliseconds
98 * @return edited {@link Smil}, the new SmilMediaElement and generated
99 * meta data
100 * @throws SmilException if there is no element with the given parentId
101 */
102 SmilResponse addClip(Smil smil, String parentId, Track track, long start, long duration) throws SmilException;
103
104 /**
105 * Add a SmilMediaElement based on given track and start/duration
106 * information.
107 *
108 * @param smil {@link Smil} to edit
109 * @param parentId element id, where to add new SmilMediaElement
110 * @param track {@link Track} to add as SmilMediaElement
111 * @param start start position in {@link Track} in milliseconds
112 * @param duration duration in milliseconds
113 * @param paramGroupId clip should be added as a part of a previously created param group
114 * @return edited {@link Smil}, the new SmilMediaElement and generated
115 * meta data
116 * @throws SmilException if there is no element with the given parentId
117 */
118 SmilResponse addClip(Smil smil, String parentId, Track track, long start, long duration, String paramGroupId)
119 throws SmilException;
120
121 /**
122 * Add a list of SmilMediaElements based on given tracks and
123 * start/duration information.
124 *
125 * @param smil {@link Smil} to edit
126 * @param parentId element id, where to add new SmilMediaElements
127 * @param tracks {@link Track}s to add as SmilMediaElements
128 * @param start start position in {@link Track}s in milliseconds
129 * @param duration duration in milliseconds
130 * @return edited {@link Smil}, the new SmilMediaElements and tracks meta data
131 * @throws SmilException if there is no element with the given parentId
132 */
133 SmilResponse addClips(Smil smil, String parentId, Track[] tracks, long start, long duration) throws SmilException;
134
135 /**
136 * Add a meta element to {@link Smil} head.
137 *
138 * @param smil {@link Smil} to edit
139 * @param name meta name
140 * @param content meta content
141 * @return edited {@link Smil} and the new SmilMeta
142 */
143 SmilResponse addMeta(Smil smil, String name, String content);
144
145 /**
146 * Remove element (identified by elementId) from {@link Smil} if exists.
147 *
148 * @param smil {@link Smil} to edit
149 * @param elementId element Id to remove
150 * @return edited Smil and removed SmilMediaElement if {@link Smil} contains an element with given Id
151 */
152 SmilResponse removeSmilElement(Smil smil, String elementId);
153
154 /**
155 * Returns {@link Smil} from Xml {@code String}.
156 *
157 * @param smilXml Smil document Xml as {@code String}
158 * @return parsed {@link Smil}
159 * @throws SmilException if an error occures while parsing {@link Smil}
160 */
161 SmilResponse fromXml(String smilXml) throws SmilException;
162
163 /**
164 * Returns {@link Smil} from Xml {@code File}.
165 *
166 * @param smilXmlFile Smil document Xml as {@code File}
167 * @return parsed {@link Smil}
168 * @throws SmilException if an error occures while parsing {@link Smil}
169 */
170 SmilResponse fromXml(File smilXmlFile) throws SmilException;
171 }