subprojects/gstreamer/gst/gstsegment.h

   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 } 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 */
 183 typedef 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  */
 263 struct _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
 284 GST_API
 285 GType        gst_segment_get_type            (void);
 286
 287 GST_API
 288 GstSegment * gst_segment_new                 (void) G_GNUC_MALLOC;
 289
 290 GST_API
 291 GstSegment * gst_segment_copy                (const GstSegment *segment) G_GNUC_MALLOC;
 292
 293 GST_API
 294 void         gst_segment_copy_into           (const GstSegment *src, GstSegment *dest);
 295
 296 GST_API
 297 void         gst_segment_free                (GstSegment *segment);
 298
 299 GST_API
 300 void         gst_segment_init                (GstSegment *segment, GstFormat format);
 301
 302 GST_API
 303 gint         gst_segment_to_stream_time_full (const GstSegment *segment, GstFormat format, guint64 position, guint64 * stream_time);
 304
 305 GST_API
 306 guint64      gst_segment_to_stream_time      (const GstSegment *segment, GstFormat format, guint64 position);
 307
 308 GST_API
 309 gint         gst_segment_position_from_stream_time_full (const GstSegment * segment, GstFormat format, guint64 stream_time, guint64 * position);
 310
 311 GST_API
 312 guint64      gst_segment_position_from_stream_time (const GstSegment * segment, GstFormat format, guint64 stream_time);
 313
 314 GST_API
 315 guint64      gst_segment_to_running_time     (const GstSegment *segment, GstFormat format, guint64 position);
 316
 317 GST_API
 318 gint         gst_segment_to_running_time_full (const GstSegment *segment, GstFormat format, guint64 position,
 319                                                guint64 * running_time);
 320
 321 GST_DEPRECATED_FOR(gst_segment_position_from_running_time)
 322 guint64      gst_segment_to_position         (const GstSegment *segment, GstFormat format, guint64 running_time);
 323
 324 GST_API
 325 gint         gst_segment_position_from_running_time_full (const GstSegment *segment, GstFormat format, guint64 running_time, guint64 * position);
 326
 327 GST_API
 328 guint64      gst_segment_position_from_running_time (const GstSegment *segment, GstFormat format, guint64 running_time);
 329
 330 GST_API
 331 gboolean     gst_segment_set_running_time    (GstSegment *segment, GstFormat format, guint64 running_time);
 332
 333 GST_API
 334 gboolean     gst_segment_offset_running_time (GstSegment *segment, GstFormat format, gint64 offset);
 335
 336 GST_API
 337 gboolean     gst_segment_clip                (const GstSegment *segment, GstFormat format, guint64 start,
 338                                               guint64 stop, guint64 *clip_start, guint64 *clip_stop);
 339 GST_API
 340 gboolean     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);
 344 GST_API
 345 gboolean     gst_segment_is_equal            (const GstSegment * s0, const GstSegment * s1);
 346
 347 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstSegment, gst_segment_free)
 348
 349 G_END_DECLS
 350
 351 #endif /* __GST_SEGMENT_H__ */