.. _bag-play:

==========
 bag-play
==========

.. program:: bag-play

Synopsis
========

:samp:`bag-play {[OPTIONS]} {LOGFILE} {[URI]}`

Description
===========

The :program:`bag-play` program can be used to publish :ref:`RSB
<rsb>` :term:`events` from a :term:`log file` of recorded
:term:`events`. Replaying :term:`event` flows as closely to the
original as possible or with certain modifications can be very useful
when debugging components, doing performance or regressions tests or
testing the influence of parameters.

The :ref:`usual RSB-related commandline options <rsb:common-options>`
and :ref:`replay-related options <common-options>` are
accepted.

Playback of All Recorded Channels
=================================

To play all recorded events of a :term:`log file` on their original
:term:`channels`, two commandline arguments have to be specified:

1. The :term:`log file` from which :term:`events` should be read
2. The "base" :term:`scope` to which :term:`events` should be
   published

For details regarding the URI syntax involved in :term:`transport` and
:term:`channel` specifications, see :ref:`uri-schema`.

Selective Playback and Timing
=============================

The default behavior of :program:`bag-play` is to play back all
:term:`channels` found in the given file. However, when only a subset
of the recorded :term:`channels` should be played back, the
:option:`--channel` commandline option can be used to select
:term:`channels` for playback.

The default behavior of :program:`bag-play` is to play back all
:term:`events` of the selected channels ordered by timestamp, from
earliest to latest. However, it is possible to select a subset of
these :term:`events` by specifying temporal or index-based intervals.
The :option:`--start-index`, :option:`--end-index`,
:option:`--start-time` and :option:`--end-time` commandline options
allow specifying these restrictions.

Different strategies for controlling the replay timing can be
used. Strategies and their parameters are specified using the
:option:`--replay-strategy` commandline option. The default replay
strategy tries to mimic the original timing.

Other strategies include

* Replay events as fast as possible
* Replay events at a fixed rate

In addition, some strategies permit modification of their behavior via
parameters. For example

.. code-block:: sh

   -r 'fixed-rate :rate 20'
   -r 'recorded-timing :speed 1.5'

.. tip::

   Available strategies and their parameters are described in the
   output of ``bag-play --help``.

.. _interactive-playback:

Interactive Playback
====================

TODO

.. code-block:: sh

   -r 'interactive'

.. _remote-controlled-playback:

Remote-controlled Playback
==========================

:program:`bag-play` can expose an `RPC
<http://en.wikipedia.org/wiki/Remote_procedure_call>`_ interface that
allows navigating the :term:`bag` file being played back and
controlling emission of :term:`events`. An URI has to be supplied as
the ``:uri`` argument of the :option:`--replay-strategy` option to
configure the :term:`scope` and :term:`transport` through which the
RPC interface should be exposed. The full syntax of the commandline
option therefore is

.. code-block:: sh

   -r 'remote-controlled :uri "URI"'

The interface consists of the following methods:

.. js:function:: length()

   Return the length of the replayed sequence as ``uint64``.

.. js:function:: index()

   Return the current position in the replayed sequence as ``uint64``.

.. js:function:: next()

   Move the replay cursor to the next entry, return new index as
   ``uint64``.

.. js:function:: previous()

   Move the replay cursor to the previous entry, return new index as
   ``uint64``.

.. js:function:: seek(position: uint64)

   Position the replay cursor at the supplied entry index.

.. js:function:: emit()

   Publish the entry at which the replay cursor is currently
   positioned.

.. js:function:: emitandnext()

   Publish the entry at which the replay cursor is currently
   positioned, advance to the next entry, return new index as
   ``uint64``.

.. js:function:: quit()

   Terminate the replay.

Examples
========

* .. code-block:: sh

     $ bag-play /tmp/nao.tide 'spread://remote:4803'

  In the above example, the specified :term:`scope` is ``/`` which
  causes all :term:`events` to be played on their original
  :term:`scopes` since recorded :term:`event` :term:`scopes` are
  appended to the specified base :term:`scope`.
* .. code-block:: sh

     $ bag-play -c 'vision' -c 'audio' /tmp/nao.tide 'spread:?name=5555'

  The above command plays all :term:`channels` of the :term:`log file`
  ``/tmp/nao.tide`` whose names match one of the regular expressions
  ``vision`` and ``audio``.
* .. code-block:: sh

     $ bag-play --start-index 1000 /tmp/nao.tide 'spread:?name=5555'

  The above command replays the events of the :term:`log file`
  ``/tmp/nao.tide`` starting with the 1000-th :term:`event`.