reprostim.qr.timesync_stimuli

PsychoPy-based script to produce time calibration session with embedded video QR-codes and audiocodes integrated with MRI/BIRCH/Magewell USB capture devices.

API to parse (*.mkv) video files recorded by reprostim-videocapture utility and extract embedded video media info, QR-codes and audiocodes into JSONL format.

Functions

do_init(logfn)

Initializes a log file.

do_main(mode, logfn, is_fullscreen, ...[, ...])

Main function to run the timesync-stimuli PsychoPy-based script.

get_output_file_name(prefix, start_ts[, end_ts])

Generates an output file name based on the given prefix and timestamps.

get_ts_str(ts)

Get a formatted string representation of a timestamp.

safe_remove(file_name)

Safely remove a file if it exists.

store_audiocode(audio_file, audio_data, logfn)

Store the audio code data in to the standalone *.wav file.

Classes

Mode(value)

Enum for the mode of the script operation.

SeriesData(num[, tr_count, tr_last_time, ...])

Class to hold series data for trigger events.
class reprostim.qr.timesync_stimuli.Mode(value)[source]

Enum for the mode of the script operation.

BEEP = 'beep'

Play a beep sound for audio test purposes.

DEVICES = 'devices'

List available audio devices to the console output.

EVENT = 'event'

Listen for keyboard events or MRI pulse and generate QR/audio codes.

INTERVAL = 'interval'

Produce QR/audio codes at regular intervals.

class reprostim.qr.timesync_stimuli.SeriesData(num: int, tr_count: int = 0, tr_last_time: float | None = None, tr_timeout: float = 4.0)[source]

Class to hold series data for trigger events.

num: int

Series number.

tr_count: int = 0

Trigger events count in the series.

tr_last_time: float = None

Last trigger event time.

tr_timeout: float = 4.0

Trigger event max interval/timeout in seconds.

reprostim.qr.timesync_stimuli.do_init(logfn: str) → bool[source]

Initializes a log file.

Parameters:

logfn (str) – The path to the log file to be checked.

Returns:

True if the log file does not exist and can be initialized, False otherwise.

Return type:

bool

reprostim.qr.timesync_stimuli.do_main(mode: ~reprostim.qr.timesync_stimuli.Mode, logfn: str, is_fullscreen: bool, win_size: tuple[int, int], display: int, qr_scale: float, qr_duration: float, qr_async: bool, audio_codec: str, mute: bool, ntrials: int, duration: float, interval: float, keep_audiocode: bool, out_func=<built-in function print>) → int[source]

Main function to run the timesync-stimuli PsychoPy-based script.

This function initializes the PsychoPy environment, sets up the window, and handles the main loop for displaying QR codes and audio codes. It also handles keyboard events and manages the series of trigger events. The function takes various parameters to configure the behavior of the script.

Parameters:

  • mode (Mode) – The mode of operation (e.g., EVENT, INTERVAL, BEEP, DEVICES).

  • logfn (str) – The name of the log file to write to.

  • is_fullscreen (bool) – Whether to run the window in fullscreen mode.

  • win_size (tuple[int, int]) – The size of the window (width, height) in pixels.

  • display (int) – The display number to use.

  • qr_scale (float) – The scale factor for the QR code size.

  • qr_duration (float) – The duration of the QR code display in seconds.

  • qr_async (bool) – Whether to display the QR code asynchronously.

  • audio_codec (str) – The audio codec to use for the audio code.

  • mute (bool) – Whether to mute the audio output.

  • ntrials (int) – The number of trials to run.

  • duration (float) – The duration of the experiment in seconds.

  • interval (float) – The interval between trials in seconds.

  • keep_audiocode (bool) – Whether to keep the audio code file after use.

  • out_func (callable) – The function to use for output (default is print).

Returns:

0 on success, -1 on error.

Return type:

int

reprostim.qr.timesync_stimuli.get_output_file_name(prefix: str, start_ts: datetime, end_ts: datetime | None = None) → str[source]

Generates an output file name based on the given prefix and timestamps.

This function creates a file name by formatting the provided start and optional end timestamps into a string and appending them to the provided prefix. The timestamps are converted to strings using the get_ts_str function.

Parameters:

  • prefix (str) – The prefix to use for the file name.

  • start_ts (datetime) – The start timestamp to be included in the file name.

  • end_ts (datetime, optional) – The optional end timestamp to be included in the file name.

Returns:

The generated file name.

Return type:

str

reprostim.qr.timesync_stimuli.get_ts_str(ts: datetime) → str[source]

Get a formatted string representation of a timestamp.

This function formats the provided timestamp into a string using the specified format (%Y.%m.%d-%H.%M.%S.%f). The format includes year, month, day, hour, minute, second, and microsecond.

Parameters:

ts (datetime) – The timestamp to be formatted.

Returns:

The formatted string representation of the timestamp.

Return type:

str

reprostim.qr.timesync_stimuli.safe_remove(file_name: str)[source]

Safely remove a file if it exists.

This function checks if the specified file exists and is a valid file. If it is, it attempts to remove the file. If the removal fails, it logs an error message.

Parameters:

file_name (str) – The name of the file to be removed.

reprostim.qr.timesync_stimuli.store_audiocode(audio_file: str, audio_data: int, logfn: str)[source]

Store the audio code data in to the standalone *.wav file.

Parameters:

  • audio_file (str) – The path to the audio file to be copied.

  • audio_data (int) – The audio data used in audio code.

  • logfn (str) – The current log file name.