player: handle rebasing start time differently

Most of this is explained in the DOCS additions.

This gives us slightly more sanity, because there is less interaction
between the various parts. The goal is getting rid of the video_offset
entirely.

The simplification extends to the user API. In particular, we don't need
to fix missing parts in the API, such as the lack for a seek command
that seeks relatively to the start time. All these things are now
transparent.

(If someone really wants to know the real timestamps/start time, new
properties would have to be added.)

3 files changed, 24 insertions, 6 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index dd42895203..2dd2e052ac 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -21,6 +21,12 @@ Interface changes
 
  --- mpv 0.14.0 ---
     - add "vsync-ratio" property
+    - add --rebase-start-time option
+      This is a breaking change to start time handling. Instead of making start
+      time handling an aspect of different options and properties (like
+      "time-pos" vs. "playback-time"), make it dependent on the new option. For
+      compatibility, the "time-start" property now always returns 0, so code
+      which attempted to handle rebasing manually will not break.
  --- mpv 0.13.0 ---
     - remove VO opengl-cb frame queue suboptions (no replacement)
  --- mpv 0.12.0 ---
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 0233dbf057..b581c5a8ad 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -943,8 +943,9 @@ Property list
     Position in current file in seconds.
 
 ``time-start``
-    Return the start time of the file. (Usually 0, but some kind of files,
-    especially transport streams, can have a different start time.)
+    Deprecated. Always returns 0. Before mpv 0.14, this used to return the start
+    time of the file (could affect e.g. transport streams). See
+    ``--rebase-start-time`` option.
 
 ``time-remaining``
     Remaining length of the file in seconds. Note that the file duration is not
@@ -954,9 +955,11 @@ Property list
     ``time-remaining`` scaled by the current ``speed``.
 
 ``playback-time`` (RW)
-    The playback time, which is the time relative to playback start. (This can
-    be different from the ``time-pos`` property if the file does not start at
-    position ``0``, in which case ``time-pos`` is the source timestamp.)
+    Position in current file in seconds. Unlike ``time-pos``, the time is
+    clamped to the range of the file. (Inaccurate file durations etc. could
+    make it go out of range. Also helpful when the user attempts to seek
+    outside of the file, as the seek target time is considered the current
+    position during seeking.)
 
 ``chapter`` (RW)
     Current chapter number. The number of the first chapter is 0.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 76a4e5a33b..fe76296d5f 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -69,7 +69,8 @@ Playback Control
 
     The general format for absolute times is ``[[hh:]mm:]ss[.ms]``. If the time
     is given with a prefix of ``+`` or ``-``, the seek is relative from the start
-    or end of the file.
+    or end of the file. (Since mpv 0.14, the start of the file is always
+    considered 0.)
 
     ``pp%`` seeks to percent position pp (0-100).
 
@@ -101,6 +102,14 @@ Playback Control
     Stop after a given time relative to the start time.
     See ``--start`` for valid option values and examples.
 
+``--rebase-start-time=<yes|no>``
+    Whether to move the file start time to ``00:00:00`` (default: yes). This
+    is less awkward for files which start at a random timestamp, such as
+    transport streams. On the other hand, if there are timestamp resets, the
+    resulting behavior can be rather weird. For this reason, and in case you
+    are actually interested in the real timestamps, this behavior can be
+    disabled with ``no``.
+
 ``--speed=<0.01-100>``
     Slow down or speed up playback by the factor given as parameter.