1/* GStreamer
2 * Copyright (C) 2005 Wim Taymans <wim@fluendo.com>
3 *
4 * gstsegment.h: Header for GstSegment subsystem
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_SEGMENT_H__
24#define __GST_SEGMENT_H__
25
26#include <gst/gstformat.h>
27
28G_BEGIN_DECLS
29
30#define GST_TYPE_SEGMENT (gst_segment_get_type())
31
32typedef struct _GstSegment GstSegment;
33
34/**
35 * GstSeekType:
36 * @GST_SEEK_TYPE_NONE: no change in position is required
37 * @GST_SEEK_TYPE_SET: absolute position is requested
38 * @GST_SEEK_TYPE_END: relative position to duration is requested
39 *
40 * The different types of seek events. When constructing a seek event with
41 * gst_event_new_seek() or when doing gst_segment_do_seek ().
42 */
43typedef enum {
44 /* one of these */
45 GST_SEEK_TYPE_NONE = 0,
46 GST_SEEK_TYPE_SET = 1,
47 GST_SEEK_TYPE_END = 2
48} GstSeekType;
49
50/**
51 * GstSeekFlags:
52 * @GST_SEEK_FLAG_NONE: no flag
53 * @GST_SEEK_FLAG_FLUSH: flush pipeline
54 * @GST_SEEK_FLAG_ACCURATE: accurate position is requested, this might
55 * be considerably slower for some formats.
56 * @GST_SEEK_FLAG_KEY_UNIT: seek to the nearest keyframe. This might be
57 * faster but less accurate.
58 * @GST_SEEK_FLAG_SEGMENT: perform a segment seek.
59 * @GST_SEEK_FLAG_TRICKMODE: when doing fast forward or fast reverse playback, allow
60 * elements to skip frames instead of generating all
61 * frames. (Since: 1.6)
62 * @GST_SEEK_FLAG_SNAP_BEFORE: go to a location before the requested position,
63 * if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at or before
64 * the requested position the one at or before the seek target.
65 * @GST_SEEK_FLAG_SNAP_AFTER: go to a location after the requested position,
66 * if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe at of after the
67 * requested position.
68 * @GST_SEEK_FLAG_SNAP_NEAREST: go to a position near the requested position,
69 * if %GST_SEEK_FLAG_KEY_UNIT this means the keyframe closest
70 * to the requested position, if both keyframes are at an equal
71 * distance, behaves like %GST_SEEK_FLAG_SNAP_BEFORE.
72 * @GST_SEEK_FLAG_TRICKMODE_KEY_UNITS: when doing fast forward or fast reverse
73 * playback, request that elements only decode keyframes
74 * and skip all other content, for formats that have
75 * keyframes. (Since: 1.6)
76 * @GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED: When doing fast forward or fast reverse
77 * playback, request that elements only decode keyframes and
78 * forward predicted frames and skip all other content (for example
79 * B-Frames), for formats that have keyframes and forward predicted
80 * frames. (Since: 1.18)
81 * @GST_SEEK_FLAG_TRICKMODE_NO_AUDIO: when doing fast forward or fast reverse
82 * playback, request that audio decoder elements skip
83 * decoding and output only gap events or silence. (Since: 1.6)
84 * @GST_SEEK_FLAG_INSTANT_RATE_CHANGE: Signals that a rate change should be
85 * applied immediately. Only valid if start/stop position
86 * are GST_CLOCK_TIME_NONE, the playback direction does not change
87 * and the seek is not flushing. (Since: 1.18)
88 * @GST_SEEK_FLAG_SKIP: Deprecated backward compatibility flag, replaced
89 * by %GST_SEEK_FLAG_TRICKMODE
90 *
91 * Flags to be used with gst_element_seek() or gst_event_new_seek(). All flags
92 * can be used together.
93 *
94 * A non flushing seek might take some time to perform as the currently
95 * playing data in the pipeline will not be cleared.
96 *
97 * An accurate seek might be slower for formats that don't have any indexes
98 * or timestamp markers in the stream. Specifying this flag might require a
99 * complete scan of the file in those cases.
100 *
101 * When performing a segment seek: after the playback of the segment completes,
102 * no EOS will be emitted by the element that performed the seek, but a
103 * %GST_MESSAGE_SEGMENT_DONE message will be posted on the bus by the element.
104 * When this message is posted, it is possible to send a new seek event to
105 * continue playback. With this seek method it is possible to perform seamless
106 * looping or simple linear editing.
107 *
108 * When only changing the playback rate and not the direction, the
109 * %GST_SEEK_FLAG_INSTANT_RATE_CHANGE flag can be used for a non-flushing seek
110 * to signal that the rate change should be applied immediately. This requires
111 * special support in the seek handlers (e.g. demuxers) and any elements
112 * synchronizing to the clock, and in general can't work in all cases (for example
113 * UDP streaming where the delivery rate is controlled by a remote server). The
114 * instant-rate-change mode supports changing the trickmode-related GST_SEEK_ flags,
115 * but can't be used in conjunction with other seek flags that affect the new
116 * playback position - as the playback position will not be changing.
117 *
118 * When doing fast forward (rate > 1.0) or fast reverse (rate < -1.0) trickmode
119 * playback, the %GST_SEEK_FLAG_TRICKMODE flag can be used to instruct decoders
120 * and demuxers to adjust the playback rate by skipping frames. This can improve
121 * performance and decrease CPU usage because not all frames need to be decoded.
122 *
123 * Beyond that, the %GST_SEEK_FLAG_TRICKMODE_KEY_UNITS flag can be used to
124 * request that decoders skip all frames except key units, and
125 * %GST_SEEK_FLAG_TRICKMODE_NO_AUDIO flags can be used to request that audio
126 * decoders do no decoding at all, and simple output silence.
127 *
128 * The %GST_SEEK_FLAG_SNAP_BEFORE flag can be used to snap to the previous
129 * relevant location, and the %GST_SEEK_FLAG_SNAP_AFTER flag can be used to
130 * select the next relevant location. If %GST_SEEK_FLAG_KEY_UNIT is specified,
131 * the relevant location is a keyframe. If both flags are specified, the nearest
132 * of these locations will be selected. If none are specified, the implementation is
133 * free to select whichever it wants.
134 *
135 * The before and after here are in running time, so when playing backwards,
136 * the next location refers to the one that will played in next, and not the
137 * one that is located after in the actual source stream.
138 *
139 * Also see part-seeking.txt in the GStreamer design documentation for more
140 * details on the meaning of these flags and the behaviour expected of
141 * elements that handle them.
142 */
143typedef enum {
144 GST_SEEK_FLAG_NONE = 0,
145 GST_SEEK_FLAG_FLUSH = (1 << 0),
146 GST_SEEK_FLAG_ACCURATE = (1 << 1),
147 GST_SEEK_FLAG_KEY_UNIT = (1 << 2),
148 GST_SEEK_FLAG_SEGMENT = (1 << 3),
149 GST_SEEK_FLAG_TRICKMODE = (1 << 4),
150 /* FIXME 2.0: Remove _SKIP flag,
151 * which was kept for backward compat when _TRICKMODE was added */
152 GST_SEEK_FLAG_SKIP = (1 << 4),
153 GST_SEEK_FLAG_SNAP_BEFORE = (1 << 5),
154 GST_SEEK_FLAG_SNAP_AFTER = (1 << 6),
155 GST_SEEK_FLAG_SNAP_NEAREST = GST_SEEK_FLAG_SNAP_BEFORE | GST_SEEK_FLAG_SNAP_AFTER,
156 /* Careful to restart next flag with 1<<7 here */
157 GST_SEEK_FLAG_TRICKMODE_KEY_UNITS = (1 << 7),
158 GST_SEEK_FLAG_TRICKMODE_NO_AUDIO = (1 << 8),
159 GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED = (1 << 9),
160 GST_SEEK_FLAG_INSTANT_RATE_CHANGE = (1 << 10),
161} GstSeekFlags;
162
163/**
164 * GstSegmentFlags:
165 * @GST_SEGMENT_FLAG_NONE: no flags
166 * @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment
167 * running_time
168 * @GST_SEGMENT_FLAG_TRICKMODE: perform skip playback (Since: 1.6)
169 * @GST_SEGMENT_FLAG_SEGMENT: send SEGMENT_DONE instead of EOS
170 * @GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS: Decode only keyframes, where
171 * possible (Since: 1.6)
172 * @GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED: Decode only keyframes or forward
173 * predicted frames, where possible (Since: 1.18)
174 * @GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO: Do not decode any audio, where
175 * possible (Since: 1.6)
176 * @GST_SEGMENT_FLAG_SKIP: Deprecated backward compatibility flag, replaced
177 * by @GST_SEGMENT_FLAG_TRICKMODE
178 *
179 * Flags for the GstSegment structure. Currently mapped to the corresponding
180 * values of the seek flags.
181 */
182/* Note: update gst_segment_do_seek() when adding new flags here */
183typedef enum { /*< flags >*/
184 GST_SEGMENT_FLAG_NONE = GST_SEEK_FLAG_NONE,
185 GST_SEGMENT_FLAG_RESET = GST_SEEK_FLAG_FLUSH,
186 GST_SEGMENT_FLAG_TRICKMODE = GST_SEEK_FLAG_TRICKMODE,
187 /* FIXME 2.0: Remove _SKIP flag,
188 * which was kept for backward compat when _TRICKMODE was added */
189 GST_SEGMENT_FLAG_SKIP = GST_SEEK_FLAG_TRICKMODE,
190 GST_SEGMENT_FLAG_SEGMENT = GST_SEEK_FLAG_SEGMENT,
191 GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS = GST_SEEK_FLAG_TRICKMODE_KEY_UNITS,
192 GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED = GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED,
193 GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO = GST_SEEK_FLAG_TRICKMODE_NO_AUDIO
194} GstSegmentFlags;
195
196/* Flags that are reflected for instant-rate-change seeks */
197#define GST_SEGMENT_INSTANT_FLAGS \
198 (GST_SEGMENT_FLAG_TRICKMODE|GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS|GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED|GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO)
199
200/**
201 * GstSegment:
202 * @flags: flags for this segment
203 * @rate: the playback rate of the segment is set in response to a seek
204 * event and, without any seek, the value should be `1.0`. This
205 * value is used by elements that synchronize buffer [running
206 * times](additional/design/synchronisation.md#running-time) on
207 * the clock (usually the sink elements), leading to consuming
208 * buffers faster (for a value `> 1.0`) or slower (for `0.0 <
209 * value < 1.0`) than normal playback speed. The rate also
210 * defines the playback direction, meaning that when the value is
211 * lower than `0.0`, the playback happens in reverse, and the
212 * [stream-time](additional/design/synchronisation.md#stream-time)
213 * is going backward. The `rate` value should never be `0.0`.
214 * @applied_rate: The applied rate is the rate that has been applied to the stream.
215 * The effective/resulting playback rate of a stream is
216 * `rate * applied_rate`.
217 * The applied rate can be set by source elements when a server is
218 * sending the stream with an already modified playback speed
219 * rate. Filter elements that modify the stream in a way that
220 * modifies the playback speed should also modify the applied
221 * rate. For example the #videorate element when its
222 * #videorate:rate property is set will set the applied rate of
223 * the segment it pushed downstream. Also #scaletempo applies the
224 * input segment rate to the stream and outputs a segment with
225 * rate=1.0 and applied_rate=<inputsegment.rate>.
226 * @format: the unit used for all of the segment's values.
227 * @base: the running time (plus elapsed time, see offset) of the
228 * segment [start](GstSegment.start) ([stop](GstSegment.stop) if
229 * rate < 0.0).
230 * @offset: the offset expresses the elapsed time (in buffer timestamps)
231 * before a seek with its start (stop if rate < 0.0) seek type
232 * set to #GST_SEEK_TYPE_NONE, the value is set to the position
233 * of the segment at the time of the seek.
234 * @start: the start time of the segment (in buffer timestamps)
235 * [(PTS)](GstBuffer.pts), that is the timestamp of the first
236 * buffer to output inside the segment (last one during
237 * reverse playback). For example decoders will
238 * [clip](gst_segment_clip) out the buffers before the start
239 * time.
240 * @stop: the stop time of the segment (in buffer timestamps)
241 * [(PTS)](GstBuffer.pts), that is the timestamp of the last
242 * buffer to output inside the segment (first one during
243 * reverse playback). For example decoders will
244 * [clip](gst_segment_clip) out buffers after the stop time.
245 * @time: the stream time of the segment [start](GstSegment.start)
246 * ([stop](GstSegment.stop) if rate < 0.0).
247 * @position: the buffer timestamp position in the segment is supposed to be
248 * updated by elements such as sources, demuxers or parsers to
249 * track progress by setting it to the last pushed buffer' end time
250 * ([timestamp](GstBuffer.pts) + #GstBuffer.duration) for that
251 * specific segment. The position is used when reconfiguring the
252 * segment with #gst_segment_do_seek when the seek is only
253 * updating the segment (see [offset](GstSegment.offset)).
254 * @duration: the duration of the segment is the maximum absolute difference
255 * between #GstSegment.start and #GstSegment.stop if stop is not
256 * set, otherwise it should be the difference between those
257 * two values. This should be set by elements that know the
258 * overall stream duration (like demuxers) and will be used when
259 * seeking with #GST_SEEK_TYPE_END.
260 *
261 * The structure that holds the configured region of interest in a media file.
262 */
263struct _GstSegment {
264 /*< public >*/
265 GstSegmentFlags flags;
266
267 gdouble rate;
268 gdouble applied_rate;
269
270 GstFormat format;
271 guint64 base;
272 guint64 offset;
273 guint64 start;
274 guint64 stop;
275 guint64 time;
276
277 guint64 position;
278 guint64 duration;
279
280 /* < private > */
281 gpointer _gst_reserved[GST_PADDING];
282};
283
284GST_API
285GType gst_segment_get_type (void);
286
287GST_API
288GstSegment * gst_segment_new (void) G_GNUC_MALLOC;
289
290GST_API
291GstSegment * gst_segment_copy (const GstSegment *segment) G_GNUC_MALLOC;
292
293GST_API
294void gst_segment_copy_into (const GstSegment *src, GstSegment *dest);
295
296GST_API
297void gst_segment_free (GstSegment *segment);
298
299GST_API
300void gst_segment_init (GstSegment *segment, GstFormat format);
301
302GST_API
303gint gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time);
304
305GST_API
306guint64 gst_segment_to_stream_time (const GstSegment *segment, GstFormat format, guint64 position);
307
308GST_API
309gint gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position);
310
311GST_API
312guint64 gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time);
313
314GST_API
315guint64 gst_segment_to_running_time (const GstSegment *segment, GstFormat format, guint64 position);
316
317GST_API
318gint gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position,
319 guint64 * running_time);
320
321GST_DEPRECATED_FOR(gst_segment_position_from_running_time)
322guint64 gst_segment_to_position (const GstSegment *segment, GstFormat format, guint64 running_time);
323
324GST_API
325gint gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position);
326
327GST_API
328guint64 gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time);
329
330GST_API
331gboolean gst_segment_set_running_time (GstSegment *segment, GstFormat format, guint64 running_time);
332
333GST_API
334gboolean gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset);
335
336GST_API
337gboolean gst_segment_clip (const GstSegment *segment, GstFormat format, guint64 start,
338 guint64 stop, guint64 *clip_start, guint64 *clip_stop);
339GST_API
340gboolean gst_segment_do_seek (GstSegment * segment, gdouble rate,
341 GstFormat format, GstSeekFlags flags,
342 GstSeekType start_type, guint64 start,
343 GstSeekType stop_type, guint64 stop, gboolean * update);
344GST_API
345gboolean gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1);
346
347G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free)
348
349G_END_DECLS
350
351#endif /* __GST_SEGMENT_H__ */
352

source code of include/gstreamer-1.0/gst/gstsegment.h