//----------------------------------------------------------------------------
//
// TSDuck - The MPEG Transport Stream Toolkit
// Copyright (c) 2005-2025, Thierry Lelegard
// BSD-2-Clause license, see LICENSE.txt file or https://tsduck.io/license
//
//----------------------------------------------------------------------------

<<<
=== timeshift

[.cmd-header]
Delay transmission by a fixed amount of packets

This plugin implements the time shift feature, as commonly found on set-top boxes or some TV sets.

The packet transmission is initially suspended for a given duration and packets are buffered in the meantime.
At the end of the initial duration, packets transmission restarts at the point it was suspended.
Packet buffering continues.
All packets are transmitted without loss but with a time delay.

[.usage]
Usage

[source,shell]
----
$ tsp -P timeshift [options]
----

[.usage]
Options

[.opt]
*--directory* _path_

[.optdoc]
Specify a directory where the temporary buffer file is created.

[.optdoc]
By default, the system-specific area for temporary files is used.

[.optdoc]
The temporary file is hidden and automatically deleted on termination.
Specifying another location can be useful to redirect very large buffers on another disk.

[.optdoc]
If the reserved memory area is large enough to hold the buffer, no file is created.

[.opt]
*-d* +
*--drop-initial*

[.optdoc]
Drop output packets during the initial phase, while the time-shift buffer is filling.

[.optdoc]
By default, initial packets are replaced by null packets.

[.opt]
*-m* _value_ +
*--memory-packets* _value_

[.optdoc]
Specify the number of packets which are cached in memory.
Having a larger memory cache improves the performances.

[.optdoc]
By default, the size of the memory cache is 128 packets.

[.opt]
*-p* _value_ +
*--packets* _value_

[.optdoc]
Specify the size of the time-shift buffer in packets.

[.optdoc]
There is no default, the size of the buffer shall be specified either using `--packets` or `--time`.

[.opt]
*-t* _milliseconds_ +
*--time* _milliseconds_

[.optdoc]
Specify the size of the time-shift buffer in milliseconds.

[.optdoc]
The initial bitrate is used to convert this duration in number of packets
and this value is used as fixed-size for the buffer.
This is convenient for constant bitrate (CBR) streams only.

[.optdoc]
There is no default, the size of the buffer shall be specified either using `--packets` or `--time`.

include::{docdir}/opt/group-common-plugins.adoc[tags=!*]
