Polybench® Reference
Replays signal data files in their original speed

File Replay

Overview

The File Replay can play sampled data files in exact real-time speed, or at higher or lower speed.

Operator ports

Output S: Any sample type. The connection is not limited to one type of signal.

Properties

Find more information about changing properties here: link

Alias (stream name)
type: See description
The alias of the data stream that is to be re-played. Example: 'ECG' (max. 25 characters). The alias may contain variables and/or wildcards.

For more information about stream aliases, please refer to link.
If you select a stream alias here, then AbsolutePath will become empty, because you use either a variable stream alias, or a fixed file path.

AbsolutePath
type: See description
The absolute path to the data file that is to be re-played (press the button to open a file).

This property should contain a valid path to a file, or nothing. If only a directory is specified, '*.*' is added to it.
If you select a file here, then Alias will become empty, because you use either a variable stream alias, or a fixed file path.

FileInformation
type: Undefined [this value cannot be changed]
Shows information about the file itself.


SampleFrequency
type: Real value [this value cannot be changed]
Sample frequency in Hz (samples per second) at which samples are stored in the data file.

LoopPlaying
type: True or False
Set to 'true' if the data stream should be looped or 'false' if playing should stop when the stream has ended.
Select one of those presets:
True or False
True may also be read like 'yes' and false like 'no'

In Loop playing mode, the output signals will continue in time, so it will appear that the signal is longer as it actually is. Only the signals themselves may show a sudden break, because the playing starts over from the beginning.

LoopSignalTime
type: True or False
Set to 'true' if the signal time should be reset after every loop. If set to 'false' (default), the signal will increase continiously.
Select one of those presets:
True or False
True may also be read like 'yes' and false like 'no'

For this option to work, the File Replay should be set in Loop Playing mode (see LoopPlaying property). The signal time is reset only if the File Replay performs a loop rewind.

Notes about usage: for designing and testing measurement configurations it is often useful that a signal has a continuously increasing time, as if it is a real measurement. In that case you would set this property to 'false'.
If the File Replay is used for visual file inspection by an end-user, then the time of the original signal should stay intact. In that case you would set this property to 'true', so that the original time of the looping signal is displayed.

Section Start event code
type: See description
Event marker in the file that is replayed at which the replay will start after the next START action. After every START, the replay will search the next Start Event. Leave empty to start playing from the beginning of the file.


Section End event code
type: See description
Marker or event code of an event in the replay file, at which the replay will stop. Leave empty to replay to the end of the file.

If the LoopPlaying property is set to true, then the Replay operator will re-start at the beginning of the file (or the first StartEvent). The behavior is then equal to that if the file is at the end.

RealTimeOffset
type: True or False
Set to true if the output signal timing should start at the real recording start time. If set to false, the signal starts at t=0.
Select one of those presets:
True or False
True may also be read like 'yes' and false like 'no'

This feature only works for the signals that are re-played and not for data that are visible in a reviewer! So, if you connect a review component (Y-T Reviewer or Marker Viewer) to the Replay, then samples will always be shown on a time line that starts on t=0.

SyncID
type: See description
If this object should react synchronously with other review objects, then they should all have an equal ID. This is a word or number you can think out yourself.

For example, if you require the Replay to start on a special command, you would issue a START action with a Value which is the SyncID of this Replay operator.
If you have specified a SyncID, and a START Action is issued with another SyncID, then replay will not start for this operator.
For more information about the behavior of the START, STOP and RESET actions in relation to the SyncID setting, please read more here: link.

Action Ready Processing
type: Select from the list
The action code that is sent to the system when ready replaying data. Select from the list.
Select one of those presets:


Address for the action
type: Address, starts with '$' sign (see link)
Fill in the address of the object that the Action targets. The address should start with '$'.

You may type or paste the address, or you may press the small button on the right to open the Address Searcher dialog (link)

Value for the action
type: See description
Fill in a parameter value, if one is needed for the Action or to set a value in Address.


Caption
type: Word or phrase
The name of the object in the project. This name must not contain '.' or '$' characters.

Every object has the Caption property. This property is very important, because it is the name by which Polybench recognizes this object.
It is allowed to give multiple objects the same name, as long as the objects are of the same type. In that case, a reference to this caption includes all the objects with the same caption.
In Polybench, every object can be addressed by an Address specifier, which starts with the dollar sign, for example: $My Page.My Object. 'My Page' would be the Caption of a page, and 'My Object' the Caption of an object on that page.

Documentation
type: See description
Optional documentation of this object.

It is good practice to write in short notes why you have used this object, and why its properties are set the way they are set. If this object is an operator, the Documentation text is displayed below the operator symbol.

Variable Parameters

Find more information about Variable Parameters here: link

StreamAlias
type: See description
The alias of the data stream that is to be re-played. Example: 'ECG' (max. 25 characters). This is the same item as the Alias property.

For more information about stream aliases, please refer to link.
If you select a stream alias here, then AbsolutePath will become empty, because you use either a variable stream alias, or a fixed file path.

StreamAliasSelect
type: Parameter list (see link)
The alias of the data stream that is to be re-played. Use this parameter as address in a Drop-Down box.

If you select a stream alias here, then AbsolutePath will become empty, because you use either a variable stream alias, or a fixed file path.

AbsolutePath
type: See description
The absolute path to the data file that is to be re-played.

This property should contain a valid path to a file, or nothing.
If you select a file here, then StreamAlias will become empty, because you use either a variable stream alias, or a fixed file path.

StartEvent
type: See description
Event marker in the file that is replayed at which the replay will start after the next START action. After every START, the replay will search the next Start Event. Leave empty to start playing from the beginning of the file.

This variable is the same one as the Section Start event code property, but this time it can be changed by your program.

StopEvent
type: See description
Marker or event code of an event in the replay file, at which the replay will stop. Leave empty to replay to the end of the file.

This variable is the same one as the Section End event code property, but this time it can be changed by your program.
Note that if the LoopPlaying property is set to true, then the Replay operator will re-start at the beginning of the file (or the first StartEvent). The behavior is then equal to that if the file is at the end.

FileCaption
type: See description
The caption or friendly name of the file. Sometimes this is equal to the path or file name. It depends on the file format if the file has a friendly name at all.


FileDate
type: See description
The date of the recording (or the file).

Some file formats explicitly record the file start date and time. In that case, this date is returned here.
If a file format does not record this information (for example a CSV file does not), then the date and time of the file as known to Windows is taken.

StartTime
type: See description
The time the recording was started, or the time the file was created.

Some file formats explicitly record the file start date and time. In that case, this time is returned here.
If a file format does not record this information (for example a CSV file does not), then the date and time of the file as known to Windows is taken.

SignalStartTime
type: See description
The time stamp of the first sample in the file. This may be useful information if the stored signals did not start on t=0.


FileLength
type: See description
The length of the current file in a time format.


FileLengthSeconds
type: See description
The length of the current file in seconds.


ChannelCount
type: See description
The number of signal channels in the current file.


FileType
type: See description
The type of the current file. Polybench automatically finds the correct file format of the file, which is indicated by this description.


FileName
type: See description
The name of the current file without extensions.


FileExtension
type: See description
The extension of the current file.


FileSecondExtension
type: See description
The second extension of the current file, if the file name has a double extension. Polybench commonly interprets the second extension of a file name as the 'alias', which is a identifier for the same kind of recordings (see link).

Functions

Find more information about Functions here: link

Pause
Pauses play back. If play back is paused and the File Replay is reset (by a RESET action), then play back continues.

Continue
Continues play back after calling the Pause function.

Next
Shuffles the data cursor (link) to the next Start event, if such an event has been defined and if a next Start event exists.

Previous
Shuffles the data cursor to the previous Start event, if such an event has been defined and if a previous Start event exists.

ReleaseStream
Releases the file lock on disk of the currently loaded measurement file. As soon as the File Replay needs data from the file, then the file will be locked again.

Details

The File Replay operator is typically used in applications that do post-processing of measured data. The Replay is able to re-play the signals at their original speed (measured very precisely) or at a higher or lower speed. It is also able to replay blocks of data that are defined by Start Events and Stop Events and jump from one block to the next or previous, using the Next and Previous functions.

The Replay is also able to provide reviewer components with stored data, like the Storage operator (link) can do. This means that you can connect a live data viewer as well as a stored data reviewer at the same output, as is shown in the next figure:



A file can be replayed at another rate as it was originally stored. To change the replay speed (make it play slower or faster), change the Speed setting in the Polybench designer (see the Play/Stop bar on top of the screen) or use the SPEED action (link).

How to specify the file to replay

The File Replay can play signals from a file that is specified with an absolute path to a disk location, or it can play a file by using a Stream Alias (link) that is recognized by the Patient and Measurements program. The first method is more appropriate for demo purposes, the second is the prefered choice for post-processing applications.

Which files the Replay operator is able to replay, depends on the file interpreters that are installed on your Polybench system. The Replay does not suggest any file types. If you select a file, then the Replay tries to interpret the file using all the installed file interpreters. If that fails, the Replay shows nothing at its output or a warning pops up if you try to play the file.

Starting behavior

If a START action is performed in a project, the Replay checks if it should start replaying the selected file. Whether the Replay starts, depends on the SyncID property. If the SyncID has not been set (empty setting), the Replay will start on any general START action that does not specify a SyncID in its Value. If the Replay does define a SyncID, it will only start if a START action is issued with the same SyncID code in its Value (see Actions link for more details).

If a Start Event (see the Section Start event code property and variable parameter) has been defined, the Replay tries to find the next event with the specified event code, and starts on that sample. If the Replay is then stopped, and started again (without RESET), the next event in the signal is sought. If the specified event is not found, the Replay does not start.

Stopping behavior

If a STOP action is performed in a project, the Replay checks if it should stop replaying the sample file. Stopping again depends on the SyncID setting, but in a different way as for starting: the Replay stops if no SyncID has been defined in the STOP action (a so called 'general stop'), or if the SyncID specified for the STOP action equals the SyncID value of the Replay operator.

If a Stop Event (see the Section End event code property and variable parameter) has been defined, the Replay stops if that event marker is found in the signal. In that case, a STOP action is called with the SyncID or the File Replay operator. If the LoopPlaying property is set to true, the Replay will not stop, but re-start at the beginning of the file, or at the first Section Start event.
If a Stop Event has been detected and there is no Start Event further on in the file, then an action is performed that you can define yourself. This enables your application to be notified if replaying is ready.

Loop playing and restarting a replay

If the property LoopPlaying is set to True, the Replay will restart the file replay at the end of the file. The file restarts at the beginning, or if a Section Start event code is specified, at the start event position. There are two modes in which files can be looped, depending on the LoopSignalTime property. One mode is that the signal time is always the time of the file, and the other mode is that the signal time continues.

If you do not have the LoopPlaying property set to True, the File Replay will stop at the end of the file (or at the last Section End event position). If you want to restart the file replay, you have do a RESET action first. It is possible to do a RESET for one Replay separately by specifying its address (see the RESET action link).

Selecting multiple section for replay and shuffling

Using the Section Start event and Section End event you can mark one or more sections in a file to be replayed. You can let the user add Start and End event markers to a signal by displaying the signal in a Y-T Reviewer (link) and by showing a Marker Button Panel (link).

After the you have marker section for replay, you can shuffle to sections just like on an oldfashioned CD-player. Use the functions Next and Previous to go to the next or previous Section Start event marker. If the File Replay is running, then the next section is being replayed immediately. If you perform the Previous function while replaying, then the Start event marker of the current section is shuffled to. If you do Previous again within 1.5 seconds, then the pre-previous Section Start event marker is sought. This is behavior as known from CD players.

Mixing signals from Replay with other signal sources

It is allowed to replay multiple files at once, or to mix replayed files with other data sources (such as a noise generator). If you want to combine multiple streams, these streams must be synchronized first! You can do that by leading all the sources through one Synchronizer operator (link). After the Synchronizer, the sources are synchronized and can be used for calculations.

Load a file at start-up of Polybench

It is possible to load a file into the File Replay immediately after an application is started up. For this functionality, you should specify in AbsolutePath a global variable that is set by an argument of Polybench.exe. Here are the steps to follow:

- make an application that uses a File Replay.
- in the File Replay property 'AbsolutePath' specify a global variable, for example the reserved variable $data$ (see also link).
- Save the project and close Polybench.
- Now open Polybench.exe with at least two arguments: one to open the project and one to specify the file in $data$. You can do this in a batch file, if you like, or you can also do this in the Manager, by specifying the project in the Application Start-up dialog (link). In that case the project is specified automatically.

In a batchfile, the start command could look like this:
Polybench.exe /program:"C:\Apps\My Replay Test App.xmc" /data:"C:\Data\MyRecording1.csv".

Now, the $data$ variable contains the path "C:\Data\MyRecording1.csv". The File Replay replaces the $data$ variable with its value, so that the AbsolutePath property now contains this path - the file is loaded!

Examples

Example: Replay Function Demo
Demonstrates a number of features of the File Replay operator. In the Y-T Reviewer the user can specify blocks in the signals to replay and optionally store to disk (post-processing). By using the Next and Previous functions, the user can step through the selected blocks like on a CD player. If Play is pressed, the next block is played.
Note that the data file used in this example may be stored in a location that Windows forbids files to be changed. Changes to the Begin and End markers may not be allowed to store to disk.
Examples\DF0204028_001_Replay_Functions_Demo.xmc