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 28 G_BEGIN_DECLS 29 30 #define GST_TYPE_SEGMENT (gst_segment_get_type()) 31 32 typedef 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 */ 43 typedef 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 */ 143 typedef 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 #ifdef OHOS_OPT_PERFORMANCE 162 // ohos.opt.performance.0006: the pts segment of the first frame is calibrated to improve the performance 163 GST_SEEK_FLAG_FIRST_FRAME = (1 << 11), 164 #endif 165 } GstSeekFlags; 166 167 /** 168 * GstSegmentFlags: 169 * @GST_SEGMENT_FLAG_NONE: no flags 170 * @GST_SEGMENT_FLAG_RESET: reset the pipeline running_time to the segment 171 * running_time 172 * @GST_SEGMENT_FLAG_TRICKMODE: perform skip playback (Since: 1.6) 173 * @GST_SEGMENT_FLAG_SEGMENT: send SEGMENT_DONE instead of EOS 174 * @GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS: Decode only keyframes, where 175 * possible (Since: 1.6) 176 * @GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED: Decode only keyframes or forward 177 * predicted frames, where possible (Since: 1.18) 178 * @GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO: Do not decode any audio, where 179 * possible (Since: 1.6) 180 * @GST_SEGMENT_FLAG_SKIP: Deprecated backward compatibility flag, replaced 181 * by @GST_SEGMENT_FLAG_TRICKMODE 182 * 183 * Flags for the GstSegment structure. Currently mapped to the corresponding 184 * values of the seek flags. 185 */ 186 /* Note: update gst_segment_do_seek() when adding new flags here */ 187 typedef enum { /*< flags >*/ 188 GST_SEGMENT_FLAG_NONE = GST_SEEK_FLAG_NONE, 189 GST_SEGMENT_FLAG_RESET = GST_SEEK_FLAG_FLUSH, 190 GST_SEGMENT_FLAG_TRICKMODE = GST_SEEK_FLAG_TRICKMODE, 191 /* FIXME 2.0: Remove _SKIP flag, 192 * which was kept for backward compat when _TRICKMODE was added */ 193 GST_SEGMENT_FLAG_SKIP = GST_SEEK_FLAG_TRICKMODE, 194 GST_SEGMENT_FLAG_SEGMENT = GST_SEEK_FLAG_SEGMENT, 195 GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS = GST_SEEK_FLAG_TRICKMODE_KEY_UNITS, 196 GST_SEGMENT_FLAG_TRICKMODE_FORWARD_PREDICTED = GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED, 197 GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO = GST_SEEK_FLAG_TRICKMODE_NO_AUDIO, 198 #ifdef OHOS_OPT_PERFORMANCE 199 // ohos.opt.performance.0006: the pts segment of the first frame is calibrated to improve the performance 200 GST_SEGMENT_FLAG_FIRST_FRAME = GST_SEEK_FLAG_FIRST_FRAME, 201 #endif 202 } GstSegmentFlags; 203 204 /* Flags that are reflected for instant-rate-change seeks */ 205 #define GST_SEGMENT_INSTANT_FLAGS \ 206 (GST_SEGMENT_FLAG_TRICKMODE|GST_SEGMENT_FLAG_TRICKMODE_KEY_UNITS|GST_SEEK_FLAG_TRICKMODE_FORWARD_PREDICTED|GST_SEGMENT_FLAG_TRICKMODE_NO_AUDIO) 207 208 /** 209 * GstSegment: 210 * @flags: flags for this segment 211 * @rate: the playback rate of the segment is set in response to a seek 212 * event and, without any seek, the value should be `1.0`. This 213 * value is used by elements that synchronize buffer [running 214 * times](additional/design/synchronisation.md#running-time) on 215 * the clock (usually the sink elements), leading to consuming 216 * buffers faster (for a value `> 1.0`) or slower (for `0.0 < 217 * value < 1.0`) than normal playback speed. The rate also 218 * defines the playback direction, meaning that when the value is 219 * lower than `0.0`, the playback happens in reverse, and the 220 * [stream-time](additional/design/synchronisation.md#stream-time) 221 * is going backward. The `rate` value should never be `0.0`. 222 * @applied_rate: The applied rate is the rate that has been applied to the stream. 223 * The effective/resulting playback rate of a stream is 224 * `rate * applied_rate`. 225 * The applied rate can be set by source elements when a server is 226 * sending the stream with an already modified playback speed 227 * rate. Filter elements that modify the stream in a way that 228 * modifies the playback speed should also modify the applied 229 * rate. For example the #videorate element when its 230 * #videorate:rate property is set will set the applied rate of 231 * the segment it pushed downstream. Also #scaletempo applies the 232 * input segment rate to the stream and outputs a segment with 233 * rate=1.0 and applied_rate=<inputsegment.rate>. 234 * @format: the unit used for all of the segment's values. 235 * @base: the running time (plus elapsed time, see offset) of the 236 * segment [start](GstSegment.start) ([stop](GstSegment.stop) if 237 * rate < 0.0). 238 * @offset: the offset expresses the elapsed time (in buffer timestamps) 239 * before a seek with its start (stop if rate < 0.0) seek type 240 * set to #GST_SEEK_TYPE_NONE, the value is set to the position 241 * of the segment at the time of the seek. 242 * @start: the start time of the segment (in buffer timestamps) 243 * [(PTS)](GstBuffer.pts), that is the timestamp of the first 244 * buffer to output inside the segment (last one during 245 * reverse playback). For example decoders will 246 * [clip](gst_segment_clip) out the buffers before the start 247 * time. 248 * @stop: the stop time of the segment (in buffer timestamps) 249 * [(PTS)](GstBuffer.pts), that is the timestamp of the last 250 * buffer to output inside the segment (first one during 251 * reverse playback). For example decoders will 252 * [clip](gst_segment_clip) out buffers after the stop time. 253 * @time: the stream time of the segment [start](GstSegment.start) 254 * ([stop](GstSegment.stop) if rate < 0.0). 255 * @position: the buffer timestamp position in the segment is supposed to be 256 * updated by elements such as sources, demuxers or parsers to 257 * track progress by setting it to the last pushed buffer' end time 258 * ([timestamp](GstBuffer.pts) + #GstBuffer.duration) for that 259 * specific segment. The position is used when reconfiguring the 260 * segment with #gst_segment_do_seek when the seek is only 261 * updating the segment (see [offset](GstSegment.offset)). 262 * @duration: the duration of the segment is the maximum absolute difference 263 * between #GstSegment.start and #GstSegment.stop if stop is not 264 * set, otherwise it should be the difference between those 265 * two values. This should be set by elements that know the 266 * overall stream duration (like demuxers) and will be used when 267 * seeking with #GST_SEEK_TYPE_END. 268 * 269 * The structure that holds the configured region of interest in a media file. 270 */ 271 struct _GstSegment { 272 /*< public >*/ 273 GstSegmentFlags flags; 274 275 gdouble rate; 276 gdouble applied_rate; 277 278 GstFormat format; 279 guint64 base; 280 guint64 offset; 281 guint64 start; 282 guint64 stop; 283 guint64 time; 284 285 guint64 position; 286 guint64 duration; 287 288 /* < private > */ 289 gpointer _gst_reserved[GST_PADDING]; 290 }; 291 292 GST_API 293 GType gst_segment_get_type (void); 294 295 GST_API 296 GstSegment * gst_segment_new (void) G_GNUC_MALLOC; 297 298 GST_API 299 GstSegment * gst_segment_copy (const GstSegment *segment) G_GNUC_MALLOC; 300 301 GST_API 302 void gst_segment_copy_into (const GstSegment *src, GstSegment *dest); 303 304 GST_API 305 void gst_segment_free (GstSegment *segment); 306 307 GST_API 308 void gst_segment_init (GstSegment *segment, GstFormat format); 309 310 GST_API 311 gint gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time); 312 313 GST_API 314 guint64 gst_segment_to_stream_time (const GstSegment *segment, GstFormat format, guint64 position); 315 316 GST_API 317 gint gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position); 318 319 GST_API 320 guint64 gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time); 321 322 GST_API 323 guint64 gst_segment_to_running_time (const GstSegment *segment, GstFormat format, guint64 position); 324 325 GST_API 326 gint gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position, 327 guint64 * running_time); 328 329 GST_DEPRECATED_FOR(gst_segment_position_from_running_time) 330 guint64 gst_segment_to_position (const GstSegment *segment, GstFormat format, guint64 running_time); 331 332 GST_API 333 gint gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position); 334 335 GST_API 336 guint64 gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time); 337 338 GST_API 339 gboolean gst_segment_set_running_time (GstSegment *segment, GstFormat format, guint64 running_time); 340 341 GST_API 342 gboolean gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset); 343 344 GST_API 345 gboolean gst_segment_clip (const GstSegment *segment, GstFormat format, guint64 start, 346 guint64 stop, guint64 *clip_start, guint64 *clip_stop); 347 GST_API 348 gboolean gst_segment_do_seek (GstSegment * segment, gdouble rate, 349 GstFormat format, GstSeekFlags flags, 350 GstSeekType start_type, guint64 start, 351 GstSeekType stop_type, guint64 stop, gboolean * update); 352 GST_API 353 gboolean gst_segment_is_equal (const GstSegment * s0, const GstSegment * s1); 354 355 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free) 356 357 G_END_DECLS 358 359 #endif /* __GST_SEGMENT_H__ */ 360