mobile/docs/design/part-segments.txt

   1 Segments
   2 --------
   3
   4 A segment in GStreamer denotes a set of media samples that must be
   5 processed. A segment has a start time, a stop time and a processing
   6 rate.
   7
   8 A media stream has a start and a stop time. The start time is
   9 always 0 and the stop time is the total duration (or -1 if unknown,
  10 for example a live stream). We call this the complete media stream.
  11
  12 The segment of the complete media stream can be played by issuing a seek
  13 on the stream. The seek has a start time, a stop time and a processing rate.
  14
  15
  16                complete stream
  17   +------------------------------------------------+
  18   0                                              duration
  19          segment
  20      |--------------------------|
  21    start                       stop
  22
  23
  24 The playback of a segment starts with a source or demuxer element pushing a
  25 newsegment event containing the start time, stop time and rate of the segment.
  26 The purpose of this newsegment is to inform downstream elements of the
  27 requested segment positions. Some elements might produce buffers that fall
  28 outside of the segment and that might therefore be discarded or clipped.
  29
  30
  31 Use case: FLUSHING seek
  32 ~~~~~~~~~~~~~~~~~~~~~~~
  33
  34   ex.
  35
  36     filesrc ! avidemux ! videodecoder ! videosink
  37
  38     When doing a seek in this pipeline for a segment 1 to 5 seconds, avidemux
  39     will perform the seek.
  40
  41     Avidemux starts by sending a FLUSH_START event downstream and upstream. This
  42     will cause its streaming task to PAUSED because _pad_pull_range() and
  43     _pad_push() will return WRONG_STATE. It then waits for the STREAM_LOCK,
  44     which will be unlocked when the streaming task pauses. At this point no
  45     streaming is happening anymore in the pipeline and a FLUSH_STOP is sent
  46     upstream and downstream.
  47
  48     When avidemux starts playback of the segment from second 1 to 5, it pushes
  49     out a newsegment with 1 and 5 as start and stop times. The stream_time in
  50     the newsegment is also 1 as this is the position we seek to.
  51
  52     The video decoder stores these values internally and forwards them to the
  53     next downstream element (videosink, which also stores the values)
  54
  55     Since second 1 does not contain a keyframe, the avi demuxer starts sending
  56     data from the previous keyframe which is at timestamp 0.
  57
  58     The video decoder decodes the keyframe but knows it should not push the
  59     video frame yet as it falls outside of the configured segment.
  60
  61     When the video decoder receives the frame with timestamp 1, it is able to
  62     decode this frame as it received and decoded the data up to the previous
  63     keyframe. It then continues to decode and push frames with timestamps >= 1.
  64     When it reaches timestamp 5, it does not decode and push frames anymore.
  65
  66     The video sink receives a frame of timestamp 1. It takes the start value of
  67     the previous newsegment and aplies the folowing (simplified) formula:
  68
  69         render_time = BUFFER_TIMESTAMP - segment_start + element->base_time
  70
  71     It then syncs against the clock with this render_time. Note that
  72     BUFFER_TIMESTAMP is always >= segment_start or else it would fall outside of
  73     the configure segment.
  74
  75     Videosink reports its current position as (simplified):
  76
  77         current_position = clock_time - element->base_time + segment_time
  78
  79     See part-synchronisation.txt for a more detailed and accurate explanation of
  80     synchronisation and position reporting.
  81
  82     Since after a flushing seek the stream_time is reset to 0, the new buffer
  83     will be rendered immediately after the seek and the current_position will be
  84     the stream_time of the seek that was performed.
  85
  86     The stop time is important when the video format contains B frames. The
  87     video decoder receives a P frame first, which is can decode but not push yet.
  88     When it receives a B frame, it can decode the B frame and push the B frame
  89     followed by the previously decoded P frame. If the P frame is outside of the
  90     segment, the decoder knows it should not send the P frame.
  91
  92     Avidemux stops sending data after pushing a frame with timestamp 5 and
  93     returns GST_FLOW_UNEXPECTED from the chain function to make the upstream
  94     elements perform the EOS logic.
  95
  96
  97 Use case: live stream
  98 ~~~~~~~~~~~~~~~~~~~~~
  99
 100
 101
 102
 103 Use case: segment looping
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106   Consider the case of a wav file with raw audio.
 107
 108     filesrc ! wavparse ! alsasink
 109