KRoNoLAPSE

kronolapse is a Python tool that manages the display of content, automating the display of images on a monitor according to custom schedules (cronologic time) and times (lapses), ensuring the correct presentation of the content at the precise moment.

Key features!

• Easy planning. Content, schedules, and duration are planned in a plain text file.
• Simple to use. Although kronolapse uses a Command Line Interface (CLI), after installation, simply run the tool from your system's default terminal using the plan saved in the text file.
• Content Display. Initially, kronolapse supports conventional image formats such as JPG, PNG, BMP.

Installation

User mode

1. Python and pip must be installed on your system. Version 3.12 or higher is recommended for Python.

2. Install the latest version from the repository with this line (requires Git):

   pip install git+https://github.com/mikemolina/kronolapse.git
   

Development mode

1. Python, pip and GNU Make must be installed on your system. Version 3.12 or higher is recommended for Python.

2. Clone the repository and navigate to its directory:

   git clone https://github.com/mikemolina/kronolapse.git kronolapse-dev
   cd kronolapse-dev
   

3. Prepare a virtual environment and compile the package. Requires the virtualenv package installed on your system.

   make prepare-venv
   make build
   

4. Install the package in editable mode into the virtual environment:

   make install
   

   Required dependencies such as opencv-python and screeninfo are automatically installed in this step.

Usage

User mode

1. Plan the content, schedule, and duration of your presentation in a plain text file formatted as CSV. The duration of the presentation is determined by the start and end times.

   The CSV file must have three comma-separated fields or columns (,), and the first line must begin with a header similar to:

   Image document,Start time,End time

   Next, list each image with its absolute path (depending on the operating system), the start and end times of the display; the times are entered in ISO 8601 format, that is, in the format YYYY-mm-dd HH:mm:ss. As an example of a scheduling list, here is an example for a Windows system:

   Image document,Start time,End time
   C:\Users\user\Documents\image-1.jpg,2025-12-01 09:00:00,2025-12-01 09:04:59
   C:\Users\user\Documents\image-2.jpg,2025-12-01 09:05:00,2025-12-01 09:07:00
   

   Finally, save the CSV file; for example, as schedule.csv.

2. From the terminal, use:

   kronolapse ruta\a\cronograma.csv
   

Development mode

Presentation files must be in JPG, PNG, or another image format supported by OpenCV.

Recommendation: The start and end times of the schedule for each file should not coincide to avoid overlapping of two simultaneous images.

1. Design a program as indicated above and from the terminal, use:

   python3 -m kronolapse ruta/a/cronograma.csv
   

2. For an automated demonstration, use:

   make run
   

3. A tests sequence is executed with:

   make tests
   

4. For more options, use:

   $ python3 -m kronolapse --help
   

5. The source code documentation is compiled via Sphinx. Using the following command, the respective packages and their dependencies will be installed in the virtual environment,

   make prepare-sphinx
   

   In this way, documentation can be built in HTML, man page (typical documentation for UNIX systems), and PDF formats (requires TeX Live or MiKTeX installed on your system):

   make html
   make man
   make pdf
   

kronolapse flowchart

This flowchart was developed using draw.io.

Bugs

• On Linux operating systems, with 4K monitors using fractional scaling (GNOME desktop environment), the display is not shown in full screen.

License

Kronolapse is open-source software distributed under the terms of the GNU Public License v3 (or later) included with the source code in the LICENSE file.

About versioning

This project follows the guidelines set by Semantic Versioning 2.0.0.

Documentation

See the latest document here (in spanish version).