.. _bag-play: .. _tool-play: ========== bag play ========== .. program:: bag play Synopsis ======== :samp:`bag play {[OPTIONS]} {LOGFILE1} [{LOGFILE2} ...] {[URI]}` Description =========== The :program:`bag play` program can be used to publish :ref:`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. .. seealso:: :ref:`rsb:common-options` The usual RSB-related commandline options are accepted. :ref:`replay-related-options` The usual replay-related commandline 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`. .. _bag-play-selective-replace: Selective Playback ================== 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 :term:`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. .. _bag-play-playback-timing: Playback Timing =============== 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``. .. _bag-play-event-id: Handling of Event IDs during Replay =================================== The :ref:`replay strategies ` ``as-fast-as-possible``, ``fixed-rate`` and ``recorded-timing`` accept an :samp:`:event-id {MODE}` argument where :samp:`{MODE}` is either ``:keep`` Send :term:`events ` with the :term:`event ids ` stored in the respective :term:`log file`. * :term:`cause vectors ` remain meaningful among the replayed :term:`events ` * :term:`sequence numbers ` may repeat and start at arbitrary values * :term:`events ` appear to originate from :term:`participants ` that cannot be found in the current system ``:replace`` Send :term:`events ` with new :term:`event ids ` replacing the ones stored in the respective :term:`log file`. The new :term:`event ids ` correspond to the :term:`participants ` actually sending the :term:`events `. * :term:`cause vectors ` become meaningless among the replayed :term:`events ` * :term:`sequence numbers ` generally do not repeat and start at 0 * :term:`events ` originate from :term:`participants ` that are part of the current system The default behavior is ``:replace``. .. _bag-play-adjusting-timestamps: Adjusting Timestamps during Replay ================================== The :ref:`replay strategies ` ``as-fast-as-possible``, ``fixed-rate`` and ``recorded-timing`` accept an :samp:`:adjustments {LIST-OF-ADJUSTMENTS}` argument where :samp:`{LIST-OF-ADJUSTMENTS}` is of the form :samp:`(({TIMESTAMP} {EXPRESSION}) ...)`. Examples: .. code-block:: sh -r 'recorded-timing :adjustments ((:create :now))' -r 'recorded-timing :adjustments ((:create (:delta 120)))' -r 'recorded-timing :adjustments ((:my-timestamp (:copy :create)) (:create (:delta 120)))' The first example will replace the recorded ``create`` timestamp with the time at which the :term:`event` is replayed. The second example will add 120 seconds to the recorded ``create`` timestamp. The third example copies the recorded ``create`` timestamp into a new timestamp named ``my-timestamp`` and then adjusts the ``create`` timestamp as in the second example. .. _interactive-playback: Interactive Playback ==================== TODO .. code-block:: sh -r 'interactive' .. _remote-controlled-playback: Remote-controlled Playback ========================== :program:`bag play` can expose an `RPC `_ interface that allows navigating the :term:`log 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"' An example for :samp:`{URI}` could be the :ref:`RSB URI ` ``socket:/remotecontrol``. The interface consists of the following methods: .. js:function:: length() :returns uint64: length of the sequence of all events Return the length of the sequence of all events. .. js:function:: relativelength() :returns uint64: length of the replayed (sub-)sequence of all events Return the length of the replayed (sub-)sequence of all events. .. js:function:: index() :returns uint64: current position in the replayed sequence Return the current position in the replayed sequence. .. js:function:: relativeindex() :returns uint64: current position relative to the start of the replayed (sub-)sequence Return the current position relative to the start of the replayed (sub-)sequence. .. js:function:: next() :returns uint64: new index Move the replay cursor to the next entry. .. js:function:: previous() :returns uint64: new index Move the replay cursor to the previous entry. .. js:function:: seek() :param uint64 position: new replay cursor position. Position the replay cursor at :samp:`{position}`. .. js:function:: emit() Publish the entry at which the replay cursor is currently positioned. .. js:function:: emitandnext() :returns uint64: new index Publish the entry at which the replay cursor is currently positioned, advance to the next entry. .. js:function:: get() :returns bytes: the serialized entry Return the entry at which the replay cursor is currently positioned. Do not emit or change anything. .. 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` :file:`/tmp/nao.tide` whose names match one of the regular expressions :regexp:`vision` and :regexp:`audio`. * .. code-block:: sh $ bag play --start-index 1000 /tmp/nao.tide 'spread:?name=5555' The above command replays the :term:`events ` of the :term:`log file` :file:`/tmp/nao.tide` starting with the 1000-th :term:`event`.