Download-Tools/mkvtoolnix
1
0
Fork 0
mirror of https://gitlab.com/mbunkus/mkvtoolnix.git synced 2025-01-12 13:14:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

man pages: use timestamps instead of timecodes

Browse Source 
Part of an ongoing effort to replace the use of the term `timecode`
with `timestamp`. Timecodes have a very specific meaning in the
audio/video world, and it's not what MKVToolNix has been using the
term for.
This commit is contained in:
Moritz Bunkus 2017-10-04 20:28:08 +02:00
parent ca67e757bb
commit ebb8031f86
2 changed files with 70 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/man/mkvextract.xml
View File

@ -63,7 +63,7 @@
&mkvextract; what to extract. Currently supported is the extraction of <link linkend="mkvextract.description.tracks">tracks</link>, <link
linkend="mkvextract.description.tags">tags</link>, <link linkend="mkvextract.description.attachments">attachments</link>, <link
linkend="mkvextract.description.chapters">chapters</link>, <link linkend="mkvextract.description.cuesheets">CUE sheets</link>, <link
linkend="mkvextract.description.timecodes_v2">timecodes</link> and <link
linkend="mkvextract.description.timestamps_v2">timestamps</link> and <link
linkend="mkvextract.description.cues">cues</link>. The second argument is the name of the source file. It must be a
&matroska; file. All following arguments are options and extraction specifications; both of which depend on the selected mode.
</para>
@ -400,15 +400,15 @@
</para>
</refsect2>
<refsect2 id="mkvextract.description.timecodes_v2">
<title>Timecode extraction mode</title>
<refsect2 id="mkvextract.description.timestamps_v2">
<title>Timestamp extraction mode</title>
<para>
Syntax: <command>mkvextract <option>timecodes_v2</option> <parameter>source-filename</parameter> <optional><parameter>options</parameter></optional> <parameter>TID1:dest-filename1</parameter> <optional><parameter>TID2:dest-filename2</parameter> ...</optional></command>
Syntax: <command>mkvextract <option>timestamps_v2</option> <parameter>source-filename</parameter> <optional><parameter>options</parameter></optional> <parameter>TID1:dest-filename1</parameter> <optional><parameter>TID2:dest-filename2</parameter> ...</optional></command>
</para>
<para>
The extracted timecodes are written to the console unless the output is redirected (see the section about <link
The extracted timestamps are written to the console unless the output is redirected (see the section about <link
linkend="mkvextract.output_redirection">output redirection</link> for details).
</para>
@ -417,7 +417,7 @@
<term><parameter>TID:outname</parameter></term>
<listitem>
<para>
Causes extraction of the timecodes for the track with the ID <parameter>TID</parameter> into the file <parameter>outname</parameter>
Causes extraction of the timestamps for the track with the ID <parameter>TID</parameter> into the file <parameter>outname</parameter>
if such a track exists in the source file. This option can be given multiple times. The track IDs are the same as the ones output by
&mkvmerge;'s <option>--identify</option> option.
</para>
@ -426,7 +426,7 @@
Example:
</para>
<screen>$ mkvextract timecodes_v2 input.mkv 1:tc-track1.txt 2:tc-track2.txt</screen>
<screen>$ mkvextract timestamps_v2 input.mkv 1:tc-track1.txt 2:tc-track2.txt</screen>
</listitem>
</varlistentry>
</variablelist>
@ -462,15 +462,15 @@
Example:
</para>
<screen>timecode=00:00:13.305000000 duration=- cluster_position=757741 relative_position=11</screen>
<screen>timestamp=00:00:13.305000000 duration=- cluster_position=757741 relative_position=11</screen>
<para>The possible keys are:</para>
<variablelist>
<varlistentry>
<term>timecode</term>
<term>timestamp</term>
<listitem>
<para>The cue point's timecode with nanosecond precision. The format is <literal>HH:MM:SS.nnnnnnnnn</literal>. This element is always set.</para>
<para>The cue point's timestamp with nanosecond precision. The format is <literal>HH:MM:SS.nnnnnnnnn</literal>. This element is always set.</para>
</listitem>
</varlistentry>
@ -673,7 +673,7 @@
<listitem>
<para>
<productname>TrueAudio</productname> tracks are written to <abbrev>TTA</abbrev> files. Please note that due to &matroska;'s limited
timecode precision the extracted file's header will be different regarding two fields: <varname>data_length</varname> (the total
timestamp precision the extracted file's header will be different regarding two fields: <varname>data_length</varname> (the total
number of samples in the file) and the <abbrev>CRC</abbrev>.
</para>
</listitem>
@ -865,10 +865,10 @@
</varlistentry>
<varlistentry>
<term>Timecodes</term>
<term>Timestamps</term>
<listitem>
<para>
Timecodes are first sorted and then output as a timecode v2 format compliant file ready to be fed to &mkvmerge;. The extraction to
Timestamps are first sorted and then output as a timestamp v2 format compliant file ready to be fed to &mkvmerge;. The extraction to
other formats (v1, v3 and v4) is not supported.
</para>
</listitem>

114
doc/man/mkvmerge.xml
View File

@ -481,18 +481,18 @@
</listitem>
</varlistentry>
<varlistentry id="mkvmerge.description.timecode_scale">
<term><option>--timecode-scale</option> <parameter>factor</parameter></term>
<varlistentry id="mkvmerge.description.timestamp_scale">
<term><option>--timestamp-scale</option> <parameter>factor</parameter></term>
<listitem>
<para>
Forces the timecode scale factor to <parameter>factor</parameter>. Valid values are in the range
Forces the timestamp scale factor to <parameter>factor</parameter>. Valid values are in the range
<constant>1000</constant>..<constant>10000000</constant> or the special value <constant>-1</constant>.
</para>
<para>
Normally &mkvmerge; will use a value of <constant>1000000</constant> which means that timecodes and durations will have a precision of
1ms. For files that will not contain a video track but at least one audio track &mkvmerge; will automatically chose a timecode scale
factor so that all timecodes and durations have a precision of one audio sample. This causes bigger overhead but allows precise
Normally &mkvmerge; will use a value of <constant>1000000</constant> which means that timestamps and durations will have a precision of
1ms. For files that will not contain a video track but at least one audio track &mkvmerge; will automatically chose a timestamp scale
factor so that all timestamps and durations have a precision of one audio sample. This causes bigger overhead but allows precise
seeking and extraction.
</para>
@ -576,31 +576,31 @@
<listitem>
<para>
Splitting after specific timecodes.
Splitting after specific timestamps.
</para>
<para>
Syntax: <option>--split</option> <literal>timecodes:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
Syntax: <option>--split</option> <literal>timestamps:</literal><parameter>A</parameter><optional>,<parameter>B</parameter><optional>,<parameter>C</parameter>...</optional></optional>
</para>
<para>
Example: <code>--split timecodes:00:45:00.000,01:20:00.250,6300s</code>
Example: <code>--split timestamps:00:45:00.000,01:20:00.250,6300s</code>
</para>
<para>
The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all have the same format as the
ones used for the duration (see above). The list of timecodes is separated by commas. After the input stream has reached the
current split point's timecode a new file is created. Then the next split point given in this list is used.
ones used for the duration (see above). The list of timestamps is separated by commas. After the input stream has reached the
current split point's timestamp a new file is created. Then the next split point given in this list is used.
</para>
<para>
The '<literal>timecodes:</literal>' prefix must not be omitted.
The '<literal>timestamps:</literal>' prefix must not be omitted.
</para>
</listitem>
<listitem>
<para>
Keeping specific parts by specifying timecode ranges while discarding others.
Keeping specific parts by specifying timestamp ranges while discarding others.
</para>
<para>
@ -617,26 +617,26 @@
</para>
<para>
The <literal>parts</literal> mode tells &mkvmerge; to keep certain ranges of timecodes while discarding others. The ranges to keep
The <literal>parts</literal> mode tells &mkvmerge; to keep certain ranges of timestamps while discarding others. The ranges to keep
have to be listed after the <literal>parts:</literal> keyword and be separated by commas. A range itself consists of a start and an
end timecode in the same format the other variations of <parameter>--split</parameter> accept (e.g. both
<literal>00:01:20</literal> and <literal>80s</literal> refer to the same timecode).
end timestamp in the same format the other variations of <parameter>--split</parameter> accept (e.g. both
<literal>00:01:20</literal> and <literal>80s</literal> refer to the same timestamp).
</para>
<para>
If a start timecode is left out then it defaults to the previous range's end timecode. If there was no previous range then it
If a start timestamp is left out then it defaults to the previous range's end timestamp. If there was no previous range then it
defaults to the start of the file (see example 3).
</para>
<para>
If an end timecode is left out then it defaults to the end of the source files which basically tells &mkvmerge; to keep the rest (see
If an end timestamp is left out then it defaults to the end of the source files which basically tells &mkvmerge; to keep the rest (see
example 3).
</para>
<para>
Normally each range will be written to a new file. This can be changed so that consecutive ranges are written to the same file. For
that the user has to prefix the start timecode with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and
instead append the range to the same file the previous range was written to. Timecodes will be adjusted so that there will be no
that the user has to prefix the start timestamp with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and
instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no
gap in the output file even if there was a gap in the two ranges in the input file.
</para>
@ -660,7 +660,7 @@
<note>
<para>
Note that &mkvmerge; only makes decisions about splitting at key frame positions. This applies to both the start and the end of
each range. So even if an end timecode is between two key frames &mkvmerge; will continue outputting the frames up to but
each range. So even if an end timestamp is between two key frames &mkvmerge; will continue outputting the frames up to but
excluding the following key frame.
</para>
</note>
@ -703,7 +703,7 @@
<para>
Normally each range will be written to a new file. This can be changed so that consecutive ranges are written to the same file. For
that the user has to prefix the start number with a <literal>+</literal>. This tells &mkvmerge; not to create a new file and
instead append the range to the same file the previous range was written to. Timecodes will be adjusted so that there will be no
instead append the range to the same file the previous range was written to. Timestamps will be adjusted so that there will be no
gap in the output file even if there was a gap in the two ranges in the input file.
</para>
@ -800,7 +800,7 @@
<para>
The parameters <parameter>A</parameter>, <parameter>B</parameter>, <parameter>C</parameter> etc must all be positive integers.
Numbering starts at 1. The list of chapter numbers is separated by commas. Splitting will occur right before the first key frame
whose timecode is equal to or bigger than the start timecode for the chapters whose numbers are listed. A chapter starting at 0s
whose timestamp is equal to or bigger than the start timestamp for the chapters whose numbers are listed. A chapter starting at 0s
is never considered for splitting and discarded silently.
</para>
@ -874,16 +874,16 @@
<term><option>--append-mode</option> <parameter>mode</parameter></term>
<listitem>
<para>
Determines how timecodes are calculated when appending files. The parameter <parameter>mode</parameter> can have two values:
Determines how timestamps are calculated when appending files. The parameter <parameter>mode</parameter> can have two values:
'<literal>file</literal>' which is also the default and '<literal>track</literal>'.
</para>
<para>
When mkvmerge appends a track (called '<literal>track2_1</literal>' from now on) from a second file (called
'<literal>file2</literal>') to a track (called '<literal>track1_1</literal>') from the first file (called '<literal>file1</literal>')
then it has to offset all timecodes for '<literal>track2_1</literal>' by an amount. For '<literal>file</literal>' mode this amount is
the highest timecode encountered in '<literal>file1</literal>' even if that timecode was from a different track than
'<literal>track1_1</literal>'. In track mode the offset is the highest timecode of '<literal>track1_1</literal>'.
then it has to offset all timestamps for '<literal>track2_1</literal>' by an amount. For '<literal>file</literal>' mode this amount is
the highest timestamp encountered in '<literal>file1</literal>' even if that timestamp was from a different track than
'<literal>track1_1</literal>'. In track mode the offset is the highest timestamp of '<literal>track1_1</literal>'.
</para>
<para>
@ -1303,7 +1303,7 @@ $ mkvmerge -o out.mkv '(' file.mkv ')'</screen>
<term><option>-y</option>, <option>--sync</option> <parameter>TID:d<optional>,o<optional>/p</optional></optional></parameter></term>
<listitem>
<para>
Adjust the timecodes of the track with the id <parameter>TID</parameter> by <parameter>d</parameter> ms. The track IDs are the same as
Adjust the timestamps of the track with the id <parameter>TID</parameter> by <parameter>d</parameter> ms. The track IDs are the same as
the ones given with <link linkend="mkvmerge.description.identify"><option>--identify</option></link> (see section <link
linkend="mkvmerge.track_ids">track IDs</link>).
</para>
@ -1466,12 +1466,12 @@ $ mkvmerge -o out.mkv '(' file.mkv ')'</screen>
</varlistentry>
<varlistentry>
<term><option>--timecodes</option> <parameter>TID:file-name</parameter></term>
<term><option>--timestamps</option> <parameter>TID:file-name</parameter></term>
<listitem>
<para>
Read the timecodes to be used for the specific track ID from <parameter>file-name</parameter>. These timecodes forcefully override
the timecodes that &mkvmerge; normally calculates. Read the section about <link linkend="mkvmerge.external_timecode_files">external
timecode files</link>.
Read the timestamps to be used for the specific track ID from <parameter>file-name</parameter>. These timestamps forcefully override
the timestamps that &mkvmerge; normally calculates. Read the section about <link linkend="mkvmerge.external_timestamp_files">external
timestamp files</link>.
</para>
</listitem>
</varlistentry>
@ -1480,7 +1480,7 @@ $ mkvmerge -o out.mkv '(' file.mkv ')'</screen>
<term><option>--default-duration</option> <parameter>TID:x</parameter></term>
<listitem>
<para>
Forces the default duration of a given track to the specified value. Also modifies the track's timecodes to match the default
Forces the default duration of a given track to the specified value. Also modifies the track's timestamps to match the default
duration. The argument <parameter>x</parameter> must be postfixed with '<literal>s</literal>', '<literal>ms</literal>',
'<literal>us</literal>', '<literal>ns</literal>', '<literal>fps</literal>', '<literal>p</literal>' or '<literal>i</literal>' to
specify the default duration in seconds, milliseconds, microseconds, nanoseconds, 'frames per second', 'progressive frames per
@ -1494,7 +1494,7 @@ $ mkvmerge -o out.mkv '(' file.mkv ')'</screen>
</para>
<para>
This option can also be used to change the <abbrev>FPS</abbrev> of video tracks without having to use an external timecode file.
This option can also be used to change the <abbrev>FPS</abbrev> of video tracks without having to use an external timestamp file.
</para>
</listitem>
</varlistentry>
@ -2769,9 +2769,9 @@ sound.ogg</programlisting>
</para>
<para>
If a file is split into several smaller ones and linking is used then the timecodes will not start at 0 again but will continue where the
If a file is split into several smaller ones and linking is used then the timestamps will not start at 0 again but will continue where the
last file has left off. This way the absolute time is kept even if the previous files are not available (e.g. when streaming). If no
linking is used then the timecodes should start at 0 for each file. By default &mkvmerge; does not use file linking. If you want that you
linking is used then the timestamps should start at 0 for each file. By default &mkvmerge; does not use file linking. If you want that you
can turn it on with the <option>--link</option> option. This option is only useful if splitting is activated as well.
</para>
@ -2851,7 +2851,7 @@ sound.ogg</programlisting>
<para>
This formmat consists of pairs of lines that start with '<literal>CHAPTERxx=</literal>' and '<literal>CHAPTERxxNAME=</literal>'
respectively. The first one contains the start timecode while the second one contains the title. Here's an example:
respectively. The first one contains the start timestamp while the second one contains the title. Here's an example:
</para>
<screen>CHAPTER01=00:00:00.000
@ -2954,7 +2954,7 @@ CHAPTER03NAME=Baby rocks the house</screen>
<title>General notes</title>
<para>
When splitting files &mkvmerge; will correctly adjust the chapters as well. This means that each file only includes the chapter entries
that apply to it, and that the timecodes will be offset to match the new timecodes of each output file.
that apply to it, and that the timestamps will be offset to match the new timestamps of each output file.
</para>
<para>
@ -3107,7 +3107,7 @@ CHAPTER03NAME=Baby rocks the house</screen>
<para>
Other &quot;segment information&quot; header fields can be set via command line options but not via the XML file. This includes e.g. the
<option><link linkend="mkvmerge.description.title">--title</link></option> and the <option><link
linkend="mkvmerge.description.timecode_scale">--timecode-scale</link></option> options.
linkend="mkvmerge.description.timestamp_scale">--timestamp-scale</link></option> options.
</para>
<para>
@ -3177,21 +3177,21 @@ CHAPTER03NAME=Baby rocks the house</screen>
</para>
</refsect1>
<refsect1 id="mkvmerge.external_timecode_files">
<title>External timecode files</title>
<refsect1 id="mkvmerge.external_timestamp_files">
<title>External timestamp files</title>
<para>
&mkvmerge; allows the user to chose the timecodes for a specific track himself. This can be used in order to create files with variable
&mkvmerge; allows the user to chose the timestamps for a specific track himself. This can be used in order to create files with variable
frame rate video or include gaps in audio. A frame in this case is the unit that &mkvmerge; creates separately per &matroska; block. For
video this is exactly one frame, for audio this is one packet of the specific audio type. E.g. for <abbrev>AC-3</abbrev> this would be a
packet containing <constant>1536</constant> samples.
</para>
<para>
Timecode files that are used when tracks are appended to each other must only be specified for the first part in a chain of tracks. For
example if you append two files, v1.avi and v2.avi, and want to use timecodes then your command line must look something like this:
Timestamp files that are used when tracks are appended to each other must only be specified for the first part in a chain of tracks. For
example if you append two files, v1.avi and v2.avi, and want to use timestamps then your command line must look something like this:
</para>
<screen>$ mkvmerge ... --timecodes 0:my_timecodes.txt v1.avi +v2.avi</screen>
<screen>$ mkvmerge ... --timestamps 0:my_timestamps.txt v1.avi +v2.avi</screen>
<para>
There are four formats that are recognized by &mkvmerge;. The first line always contains the version number. Empty lines, lines
@ -3199,7 +3199,7 @@ CHAPTER03NAME=Baby rocks the house</screen>
</para>
<refsect2>
<title>Timecode file format v1</title>
<title>Timestamp file format v1</title>
<para>
This format starts with the version line. The second line declares the default number of frames per second. All following lines contain
three numbers separated by commas: the start frame (<constant>0</constant> is the first frame), the end frame and the number of frames
@ -3207,37 +3207,37 @@ CHAPTER03NAME=Baby rocks the house</screen>
can contain gaps for which the default <abbrev>FPS</abbrev> is used. An example:
</para>
<screen># timecode format v1
<screen># timestamp format v1
assume 27.930
800,1000,25
1500,1700,30</screen>
</refsect2>
<refsect2>
<title>Timecode file format v2</title>
<title>Timestamp file format v2</title>
<para>
In this format each line contains a timecode for the corresponding frame. This timecode must be given in millisecond precision. It can
be a floating point number, but it doesn't have to be. You <emphasis>have to</emphasis> give at least as many timecode lines as there
are frames in the track. The timecodes in this file must be sorted. Example for 25fps:
In this format each line contains a timestamp for the corresponding frame. This timestamp must be given in millisecond precision. It can
be a floating point number, but it doesn't have to be. You <emphasis>have to</emphasis> give at least as many timestamp lines as there
are frames in the track. The timestamps in this file must be sorted. Example for 25fps:
</para>
<screen># timecode format v2
<screen># timestamp format v2
0
40
80</screen>
</refsect2>
<refsect2>
<title>Timecode file format v3</title>
<title>Timestamp file format v3</title>
<para>
In this format each line contains a duration in seconds followed by an optional number of frames per second. Both can be floating point
numbers. If the number of frames per second is not present the default one is used. For audio you should let the codec calculate the
frame timecodes itself. For that you should be using <constant>0.0</constant> as the number of frames per second. You can also create
frame timestamps itself. For that you should be using <constant>0.0</constant> as the number of frames per second. You can also create
gaps in the stream by using the '<literal>gap</literal>' keyword followed by the duration of the gap. Example for an audio file:
</para>
<screen># timecode format v3
<screen># timestamp format v3
assume 0.0
25.325
7.530,38.236
@ -3246,9 +3246,9 @@ gap, 10.050
</refsect2>
<refsect2>
<title>Timecode file format v4</title>
<title>Timestamp file format v4</title>
<para>
This format is identical to the v2 format. The only difference is that the timecodes do not have to be sorted. This format should
This format is identical to the v2 format. The only difference is that the timestamps do not have to be sorted. This format should
almost never be used.
</para>
</refsect2>