Timeline-kun 1.0.0

Timeline-kun is an integrated graphical interface tool for planning and executing experimental protocols.

Screen shot

Key Features

Timeline-kun integrates four primary functionalities:

1. Simplifying the planning of complex experimental schedules

   • Visually represents experimental schedules
   • Stores schedule data in CSV format (time values formatted as 'H:MM:SS' for Excel compatibility)
   • Allows intuitive insertion, deletion, and reordering of events using Excel
   • Supports UTF-8 encoded CSV files, enabling editing in plain text editors

2. Integrating schedule planning and execution in a single tool

   • Experimental schedules created with this tool can be directly used as timers
   • Timer interface displays the current event, upcoming event, and remaining time in a clear layout
   • Timer can be started from any point, allowing test executions or real-time schedule modifications
   • Supports custom alarm sounds using 3-second WAV files

3. Controlling GoPro devices

   • Start and stop recording based on schedules via BLE
   • Simultaneous control of multiple devices
   • Support for long standby times through keep-alive signals sent every 10 seconds

4. Improving methodological transparency and reproducibility

   • TSV log records in BIDS compliant events.tsv format
   • Deviations due to interruptions or running ahead can be reviewed later
   • Provides SVG export function suitable for experimental planning discussions and record-keeping

Installation and Execution

Windows

1. Download and extract the ZIP file from the latest release
2. Double-click "TimelineKun.exe" to run the application

Running from development environment

1. Clone the repository: git clone https://github.com/nishimura5/timeline_kun.git
2. Set up the environment using uv (simply run "uv sync" in the directory containing pyproject.toml)
3. Run "uv run python -m timeline_kun" in the directory containing pyproject.toml to launch

Note: macOS users will need to install tcl-tk and configure appropriate environment variables before installation as this tool relies on tkinter.

Timeline CSV File Format

The timeline CSV file uses the following columns:

• title: The name of the event displayed on the timer screen (duplicate names are allowed)
• member: The participant or team responsible for the event
• start: The start time of the event (formatted as H:MM:SS)
• duration: The duration of the event (formatted as H:MM:SS)
• fixed: Specifies whether the start time or duration is fixed (values: "duration" or "start")
• instruction: Additional instructions or comments
• end: Optional. End time of the event (formatted as H:MM:SS)

CSV File Example (Timeline CSV)

title,member,start,duration,fixed,instruction
TASK A,MEMBER1,0:00:00,,start,Prepare for TASK B (recording)
TASK B,MEMBER1,0:04:00,0:05:00,start,Prepare for TASK C
TASK C,MEMBER1,,0:05:00,duration,

title	member	start	duration	fixed	instruction
TASK A	MEMBER1	0:00:00		start	Prepare for TASK B (recording)
TASK B	MEMBER1	0:04:00	0:05:00	start	Prepare for TASK C
TASK C	MEMBER1		0:05:00	duration
...	...	...	...	...	...

日本語のExcelとの互換のため、CSVはShift-JISにも対応しています。

Scheduling Methods

There are two primary methods for determining event timing in Timeline-kun, which can be used exclusively or in combination:

1. Duration-fixed scheduling: When an event has a fixed duration but its start time depends on when the previous event ends. With this approach, the 'start' field is left empty, and events flow sequentially based on their durations. Set the value "duration" in the "fixed" column.

2. Start-time-fixed scheduling: When events must begin at specific elapsed times from the experiment start. In this approach, the 'duration' field can be left empty for events where only the start time matters (except in the last row). Set the value "start" in the "fixed" column.

Usage Procedure

Timeline creation and visualization:

1. Press the "Create CSV" button to create timeline data
2. Press the "Send to Excel" button to edit the timeline data in Excel
3. Press the "Reload" button to visualize the timeline data and check for any input errors
4. If you wish to start timing from the middle of the timeline, select the desired event from the table, right-click, and select the "Set start point" menu
5. Press the "Send to Timer" button to launch the timer

Timer operation:

1. Press the "Sound test" button to check the speaker volume
2. Press the "Start" button to begin the timer
3. Press the "Skip" button to skip the current event
4. To end the timer, simply close the window

Tips

• Time display format can be selected between "MM:SS" (like 90:00) and "H:MM:SS" (like 1:30:00)
• Custom WAV files can be used by replacing the file in the "sound" folder
• Users can select timer text colors from orange, cyan, and light green. Up to three timers can be operated simultaneously on a single PC
• SVG diagrams are editable using vector graphics tools such as Affinity Designer or Adobe Illustrator

GoPro Control

For GoPro models starting from HERO11 that support BLE communication, recording can be automatically started 4 seconds before a specified event (for the first event, recording starts simultaneously with the event). By entering "(recording)" in the event instruction, that event will be marked for recording. It is possible to send commands to start and stop recording on multiple GoPro devices. The target GoPro devices for control are specified in ble_devices.toml. Below is an example configuration where each of the three timers is assigned to a different GoPro. The parameter stop_delay_sec specifies the delay time (in seconds) between the end of an event and stopping the recording.

[orange]
ble_names = ["GoPro 2700", "GoPro 4256"]
stop_delay_sec = 2

[cyan]
ble_names = ["GoPro 1320"]
stop_delay_sec = 2

[lightgreen]
ble_names = []
stop_delay_sec = 2

Log File Format

Timer execution logs conform to the BIDS (Brain Imaging Data Structure) events.tsv format. The log files are stored in the same directory as the Timeline CSV file, with file names in the format:

<timeline_csv_name>_00_events.tsv.

Each time the timer is started, the number (00) is incremented and saved.

A sample log is shown below:

onset	duration	trial_type
0.0	60.0	TASK A
66.2	0.0	video_record_start
60.0	10.1	Intermission
70.0	89.9	TASK B
179.6	0.0	task_skip
160.0	22.7	TASK C
182.6	60.0	TASK D
242.6	20.0	Intermission
262.7	60.0	TASK E
322.7	0.0	session_end

Sound File

The timer application will load a 3-second wav file and play it as an alarm. The wav file will be stored in the "sound" folder with the following file names:

• countdown3_orange.wav
• countdown3_cyan.wav
• countdown3_lightgreen.wav

MMCV: ずんだもん