(1) Overview
Introduction
Managing experimental sessions often requires precise coordination of many tasks, such as giving instructions, running task blocks, scheduling breaks, and operating equipment, as well as coordinating across multiple roles.
In many laboratories, schedules are maintained manually using printed checklists, spreadsheets, and ad hoc timers. This increases cognitive load during execution and makes it difficult to retrospectively reconstruct deviations from the original plan.
Several widely used tools support the construction and execution of experiments, notably experiment builders such as PsychoPy [1] and OpenSesame [2].
These tools focus on stimulus presentation and response collection, whereas many applied protocols also require shared schedule views for teams, flexible rehearsal and mid-run adjustments, device actions synchronized to the protocol such as starting and stopping cameras, and machine-readable logs aligned with common research data standards such as Brain Imaging Data Structure (BIDS) [3].
Related articles in the Journal of Open Research Software (JORS) highlight adjacent needs in protocol execution and documentation. ExpTimer provides a dedicated timer interface for complex, multi-step procedures [5], while CowLog focuses on post hoc behavioral coding from video recordings [6]. Timeline-kun complements these tools by targeting the end-to-end workflow of time-managed protocols: CSV-based schedule authoring that can be edited in spreadsheet software, a text editor, or the built-in table editor, immediate timeline visualization with SVG export, execution via a timer that can start from an arbitrary stage for rehearsal or mid-run adjustments, and generation of machine-readable logs aligned with BIDS conventions. In addition, optional Bluetooth Low Energy (BLE)-based GoPro control enables schedule-synchronized recording triggers, supporting methodological transparency and reproducibility in team-run sessions.
Timeline-kun has been developed to support time-managed protocols in human-subject experiments.
Its core schedule representation is a CSV file with explicit semantics for start times, durations, and fixed-time constraints, allowing both spreadsheet-based planning and deterministic timer execution.
This paper describes Timeline-kun version 1.0.2. The source code is available at https://github.com/nishimura5/timeline_kun, online documentation is available at https://www.design.kyushu-u.ac.jp/~eigo/timeline_kun.html, and an archived release is deposited at Kyushu University Institutional Repository (DOI: 10.48708/7325764). The software is released under the GNU General Public License v3.0 (GPL-3.0).
Bug reports and feature requests are welcomed via the GitHub issue tracker.
A detailed methodological description of the integrated scheduling/execution approach implemented in Timeline-kun is provided in a companion SSRN preprint [7]. The present JORS paper focuses on the software contribution: implementation and architecture, quality control, availability, and reuse.
Implementation and architecture
Timeline-kun consists of two GUI applications that share a common CSV parsing and validation layer.
Schedule definition and validation
Schedules are stored as a CSV file with the required columns title, member, start, duration, fixed, instruction, and an optional end column.
The parser normalizes flexible time strings (seconds, mm:ss, h:mm:ss) into canonical time values and derives missing start/end values according to the fixed mode (start or duration).
Validation checks for missing required fields, unsupported fixed codes, and temporal inconsistencies, including overlaps and start times that go backwards. Detected issues are shown in the Previewer before execution.
Previewer (planning interface)
The Previewer is implemented with Python’s Tkinter/ttk widgets and ttkthemes.
Figure 1 shows the Previewer planning interface.
Figure 1
Previewer planning interface for CSV editing and timeline visualization.
It loads a CSV file, displays the schedule in a table editor, and renders a timeline visualization on a canvas with rectangles representing stages.
Users can insert, edit, and delete rows within the GUI. The editing dialog can be opened from the context menu or by double-clicking a row, making the schedule view not merely read-only but directly editable within the application. The same CSV file can also be edited with a text editor or any spreadsheet program, including but not limited to Microsoft Excel. Timeline-kun supports UTF-8 and UTF-8 with BOM as fallback encodings to accommodate common Windows workflows.
The Previewer can export the visualization to SVG for protocol review and record keeping, and it can launch the Timer with a chosen visual theme—orange, cyan, or light green—and an optional custom starting row to support rehearsal from the middle of a protocol. It also provides Help menu links to the online documentation and repository so that users of the standalone executable can access instructions without first visiting GitHub.
Timer (execution interface)
The Timer presents the current stage, next stage, a count-up clock, a progress bar, and an instruction panel.
It supports a start/reset lifecycle, stage skipping, and automatic insertion of Intermission stages to cover gaps in the schedule.
Audio alarms are handled by sounddevice and soundfile, playing a short WAV countdown signal before stage boundaries.
Figure 2 shows the Timer execution interface, including an optional GoPro recording control workflow.
Figure 2
Timer execution interface with optional GoPro recording control via BLE. Image frame from an archived test video. DOI: 10.48708/7325764.
Standardized logging
During execution, Timeline-kun writes protocol logs to events.tsv using the BIDS event specification [3].
Each executed stage is logged with its onset time and duration relative to the start of the session. Operational events, such as skipping a stage, ending the session, or triggering video recording, are recorded as events with zero duration.
An optional JSON sidecar describing the events.tsv fields can also be produced to support downstream data processing.
Optional GoPro control via Bluetooth Low Energy
If enabled via config.toml, the Timer can connect to one or more GoPro cameras, such as HERO11 and later models, over BLE, using the bleak library.
Recording control is defined declaratively: if a stage’s instruction contains the literal substring (recording), Timeline-kun triggers a recording start shortly before the stage begins and triggers a stop after leaving the last recording-marked stage. The stop timing uses a configurable delay.
A keep-alive loop maintains long-duration standby connections and attempts reconnection on failure, supporting long-run protocols.
Quality control
Timeline-kun includes automated tests and continuous integration.
Automated tests focus on data handling, configuration parsing, and log generation.
Automated tests and CI
The repository contains pytest-based unit and functional tests covering CSV loading, header validation, time parsing, encoding behavior, Timer CLI parsing without launching the GUI, and utility functions for time-format normalization. In total, the suite comprises multiple pytest modules together with fixture-based CSV validation files under tests/fixtures/.
The test suite can be reproduced locally from the repository root via uv sync --group dev and uv run pytest.
GitHub Actions runs the test suite on Ubuntu-latest under Python 3.11 and 3.12, installing system packages for Tk and audio backends and executing pytest under Xvfb to support Tkinter in headless CI. However, these automated tests do not comprehensively exercise full end-to-end GUI interactions such as menu operations, mouse-driven editing flows, or live timer use on real laboratory desktops. GUI usability and workflow correctness are therefore also assessed through practical use, manual verification, and feedback from actual deployments.
Practical validation of BLE control
Hardware-dependent behaviors are evaluated on real devices. The results are documented using archived full-session videos that are distributed as part of the software archive; the behaviors include audio playback latency, BLE communication stability, and GoPro camera response timing.
One video demonstrates recovery from unexpected camera power loss during standby: the connection status transitions from Connected to Disconnected about eight seconds after power loss, and recovers to Connected about 15 seconds after power restoration, including camera boot time. After recovery, a subsequent scheduled recording start succeeds.
A second video documents a three-hour continuous run controlling two cameras; recordings begin at about 4 seconds for HERO11 and at about 3 seconds for HERO12 before each event starts, and stop about 2 seconds after each event ends across the run.
These materials are available from the software archive [4].
Because these behaviors depend on external hardware, wireless conditions, and the host operating system, perfect repeatability cannot be guaranteed. Users should verify timing and reliability in their own experimental environments, especially when strict timing constraints are required.
Quick verification for users
A minimal end-to-end check is:
(1) Install from PyPI (pip install timeline-kun);
(2) Launch (python -m timeline_kun);
(3) Create a new CSV using “Create CSV”;
(4) Press “Send to timer” to launch Timer;
(5) Press “Start” to execute the timer.
The Timer will generate a log/ directory next to the CSV containing _events.tsv logs after a run.
Limitations
Timeline-kun is intended as a practical support tool for human-operated experimental sessions. As a GUI-based application, it is not suitable for fully automated or headless execution. Timing accuracy depends on the host operating system’s system clock and its synchronization, such as via Network Time Protocol (NTP). Sub-millisecond precision is not guaranteed.
BLE device support is limited to specific GoPro models tested by the author, and compatibility with other BLE devices cannot be assumed. Similarly, GoPro integration relies on the vendor’s Open GoPro API and may break with future firmware updates.
The generated BIDS-compatible events.tsv files include onset and duration fields, but users are responsible for verifying compliance with the specific requirements of their BIDS dataset and analysis pipeline.
(2) Availability
A Windows executable is archived with a DOI and is runnable on Windows 11 by double-clicking without additional downloads. Audio assets are bundled. A sample timeline CSV can be created by pressing the “Create CSV” button in the Previewer.
Operating system
Windows 10/11 (standalone executable). Linux and macOS are supported when installed as a Python package. The package is tested on Ubuntu in continuous integration. BLE control has been tested on Windows 11 and Raspberry Pi Desktop Linux.
macOS and Linux can also be installed via pip and have been smoke-tested; detailed instructions are provided in the online documentation.
Programming language
Python ≥ 3.11.
Additional system requirements
For basic use: a graphical desktop environment and an audio output device (speaker/headphones).
For CSV editing outside the application: any text editor or spreadsheet application that can read and write CSV files; Microsoft Excel is optional rather than required.
For GoPro control: a Bluetooth adapter and compatible GoPro devices, such as HERO11 and later models, within BLE range.
Dependencies
Timeline-kun requires the following Python packages.
soundfile version 0.13.1 or later for audio file loading.
sounddevice version 0.5.1 or later for audio playback.
ttkthemes version 3.2.2 or later for themed Tk user interface components.
bleak version 0.22.3 or later for BLE communication.
For development and packaging, the project additionally uses pytest version 8.3 or later for automated testing and pyinstaller version 6.11.0 or later together with pyinstaller-versionfile version 2.1 or later to build the standalone Windows executable.
List of contributors
Eigo Nishimura, Kyushu University: original author and maintainer.
Software location
Archive (required)
Name: Kyushu University Institutional Repository, QIR, software deposit
Persistent identifier: DOI: 10.48708/7325764
Licence: GNU General Public License v3.0, GPL-3.0
Publisher: Eigo Nishimura
Version published: 1.0.2
Date published: 2026 (2026-03-17 for v1.0.2 release)
GitHub Release v1.0.2 and the archived artifact contain the same v1.0.2 Windows binary. Although the archive metadata shows “v1.0”, the downloadable ZIP file is named TimelineKun102.zip, and the executable reports version 1.0.2 at runtime.
Code repository (required)
Name: GitHub
Identifier: https://github.com/nishimura5/timeline_kun (release tag v1.0.2)
Licence: GNU General Public License v3.0, GPL-3.0
Date published: 2026 (2026-03-16 for v1.0.2 release)
Online documentation is available at https://www.design.kyushu-u.ac.jp/~eigo/timeline_kun.html and can also be opened from the application’s Help menu.
Emulation environment (if appropriate)
Not applicable.
Language
English (repository, documentation, and software interface).
(3) Reuse Potential
Timeline-kun can be reused as a lightweight scheduling and logging tool in experiments where full-featured experimental frameworks (e.g., PsychoPy or OpenSesame) are unnecessary or impractical.
Typical reuse scenarios include: (i) behavioral experiments requiring simple time-based cues, (ii) field or applied experiments without dedicated synchronization hardware, and (iii) pilot studies where rapid prototyping is preferred.
Outside of laboratory experiments, Timeline-kun is applicable to workshops, usability studies, training sessions, and any facilitated activity with structured segments and role assignments.
Because the schedule is CSV-based and parsing/validation is separated from the GUI, users can generate schedules programmatically or with language models using the published schema documentation.
The BLE trigger mechanism is keyword-based and can be generalized to other device actions by adding new trigger keywords and command backends.
Similarly, export can be extended beyond SVG (e.g., PDF or PNG) by building on the canvas abstraction.
Timeline-kun is maintained openly on GitHub; users can report issues and request enhancements via the issue tracker, and contributions can be proposed as pull requests.
Support is provided through the public documentation site, which is also linked from the application’s Help menu, and through the GitHub repository and issue tracker. As an academic open-source project, support is provided on a best-effort basis through these public channels.
Acknowledgements
The author is grateful to the instructors and organizers who enabled the deployment of Timeline-kun in their classes and experimental setups, as well as to the staff and students who provided operational feedback. No participant-level data were collected or analyzed for this paper.
Competing Interests
The author has no competing interests to declare.