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
23 package org.opencastproject.metadata.mpeg7;
24
25 import org.opencastproject.mediapackage.XmlElement;
26
27 import java.util.Iterator;
28
29 /**
30 * A video segment represents a temporal decomposition of the video stream that may have properties like text
31 * annotations attached to it.
32 *
33 * <pre>
34 * <complexType name="SegmentType" abstract="true">
35 * <complexContent>
36 * <extension base="mpeg7:DSType">
37 * <sequence>
38 * <choice minOccurs="0">
39 * <element name="MediaInformation" type="mpeg7:MediaInformationType"/>
40 * <element name="MediaInformationRef" type="mpeg7:ReferenceType"/>
41 * <element name="MediaLocator" type="mpeg7:MediaLocatorType"/>
42 * </choice>
43 * <element name="StructuralUnit" type="mpeg7:ControlledTermUseType" minOccurs="0"/>
44 * <choice minOccurs="0">
45 * <element name="CreationInformation" type="mpeg7:CreationInformationType"/>
46 * <element name="CreationInformationRef" type="mpeg7:ReferenceType"/>
47 * </choice>
48 * <choice minOccurs="0">
49 * <element name="UsageInformation" type="mpeg7:UsageInformationType"/>
50 * <element name="UsageInformationRef" type="mpeg7:ReferenceType"/>
51 * </choice>
52 * <element name="TextAnnotation" minOccurs="0" maxOccurs="unbounded">
53 * <complexType>
54 * <complexContent>
55 * <extension base="mpeg7:TextAnnotationType">
56 * <attribute name="type" use="optional">
57 * <simpleType>
58 * <union memberTypes="mpeg7:termReferenceType string"/>
59 * </simpleType>
60 * </attribute>
61 * </extension>
62 * </complexContent>
63 * </complexType>
64 * </element>
65 * <choice minOccurs="0" maxOccurs="unbounded">
66 * <element name="Semantic" type="mpeg7:SemanticType"/>
67 * <element name="SemanticRef" type="mpeg7:ReferenceType"/>
68 * </choice>
69 * <element name="MatchingHint" type="mpeg7:MatchingHintType" minOccurs="0" maxOccurs="unbounded"/>
70 * <element name="PointOfView" type="mpeg7:PointOfViewType" minOccurs="0" maxOccurs="unbounded"/>
71 * <element name="Relation" type="mpeg7:RelationType" minOccurs="0" maxOccurs="unbounded"/>
72 * </sequence>
73 * </extension>
74 * </complexContent>
75 * </complexType>
76 * </pre>
77 */
78 public interface Segment extends XmlElement {
79
80 /** The segment type */
81 enum Type {
82 AudioSegment, VideoSegment, AudioVisualSegment
83 };
84
85 /**
86 * Returns the segment identifier.
87 *
88 * @return the identifier
89 */
90 String getIdentifier();
91
92 /**
93 * Sets the segment's media time constraints.
94 *
95 * @param mediaTime
96 * the media time
97 */
98 void setMediaTime(MediaTime mediaTime);
99
100 /**
101 * Returns the segment's time constraints.
102 *
103 * @return the media time
104 */
105 MediaTime getMediaTime();
106
107 /**
108 * Returns <code>true</code> if the segment contains any text annotations.
109 *
110 * @return <code>true</code> if there are text annotations
111 */
112 boolean hasTextAnnotations();
113
114 /**
115 * Returns the number of text annotations. Note that text annotations are containers themselves, containing a number
116 * of keywords and free text entries.
117 *
118 * @return the number of text annotations
119 */
120 int getTextAnnotationCount();
121
122 /**
123 * Returns <code>true</code> if the segment contains text annotations in the specified language.
124 *
125 * @return <code>true</code> if there are text annotations
126 */
127 boolean hasTextAnnotations(String language);
128
129 /**
130 * Returns <code>true</code> if the segment contains text annotations that satisfy the given relevance and confidence
131 * values.
132 *
133 * @return <code>true</code> if there are text annotations
134 */
135 boolean hasTextAnnotations(float relevance, float confidence);
136
137 /**
138 * Returns <code>true</code> if the segment contains text annotations that satisfy the given relevance, confidence and
139 * language constraints.
140 *
141 * @return <code>true</code> if there are text annotations
142 */
143 boolean hasTextAnnotations(float relevance, float confidence, String language);
144
145 /**
146 * Creates a new text annotation that will hold keywords and free text comments.
147 *
148 * @param relevance
149 * the relevance value
150 * @param confidence
151 * the confidence
152 * @param language
153 * the language identifier
154 * @return the new text annotation
155 */
156 TextAnnotation createTextAnnotation(float relevance, float confidence, String language);
157
158 /**
159 * Returns this segment's text annotations.
160 *
161 * @return the text annotations
162 */
163 Iterator<TextAnnotation> textAnnotations();
164
165 /**
166 * Returns this segment's text annotations, sorted by relevance.
167 *
168 * @return the text annotations
169 */
170 Iterator<TextAnnotation> textAnnotationsByRelevance();
171
172 /**
173 * Returns this segment's text annotations, sorted by relevance.
174 *
175 * @return the text annotations
176 */
177 Iterator<TextAnnotation> textAnnotationsByConfidence();
178
179 }