Polybench® for biosignals / reference 1.34.1
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: "Properties Viewer"

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 "Stream Alias - concept for naming of data files".
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'


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'


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.


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 "Address - how to address objects and variable parameters")
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 Constructor ("Address Constructor")

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 '.', '$' nor '@' characters.

For more information about the rules and usage of the Caption property, please refer to "Caption property - background and usage".

Documentation
type: See description
Optional documentation of this object. If this object is an operator, the Documentation text is displayed below the operator symbol.

Variable Parameters

Find more information about Variable Parameters here: "Variable Parameters"

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 "Stream Alias - concept for naming of data files".
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 "Parameter List")
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.


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.


SignalStartTimeSeconds
type: See description
The time stamp of the first sample in the file, expressed in seconds from t=0. 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 "Stream Alias - concept for naming of data files").

Functions

Find more information about Functions here: "Operator Functions"

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 ("Data Cursor and the use of SyncID") 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.
Parameter:
If you fill in STAY in the Value for this function, then Previous will never jump the cursor before the Start event of the current section, so that Previous actually works like a Rewind of the current section.

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.

Jump
Jumps the Replay to another moment in time, or to a moment before or after the current time.
Parameter:
Specify an absolute time, or write a time with + or - before it, to indicate a relative time jump. Variables are also accepted. Example: '3:15.4', or '+10' (jump 10 sec forwards), or '-3:00' (3 minutes backwards)

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 ("Storage") 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 ("SPEED").

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 ("Stream Alias - concept for naming of data files") 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 "Actions - Overview" 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 "RESET").

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 ("Y-T Reviewer") and by showing a Marker Button Panel ("Marker Button Panel").

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 ("Synchronizer"). 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 "Polybench Designer").
- 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 ("Application Start Buttons"). 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