Multi-Stage Timer (mst)

A terminal-based multi-stage timer built with Rust and Ratatui. Perfect for tracking time during streaming sessions, coding challenges, or any multi-stage activity.

Features

• Multi-Stage Tracking: Define custom stages for your activity and track time for each one.
• TUI Interface: A clean and intuitive terminal user interface powered by Ratatui.
• Backend Server: An integrated backend server on port 3001 provides a REST API for external control (e.g., Stream Deck).
• Auto-Saving: Automatically saves results to a JSON file when the timer is completed.
• Customizable Configuration: Easily configure the timer title and stages using a simple JSON file.

Installation

From Source

1. Clone the repository:

   git clone https://github.com/username/mst.git
   cd mst
   

2. Build the project:

   cargo build --release
   

   The binary will be located at target/release/mst.

Usage

To run the timer, you need to provide a configuration file. See the configs/ directory for examples.

mst configs/advent-of-code.json

Command-Line Options

Usage: mst [OPTIONS] <CONFIG>

Arguments:
  <CONFIG>  Path to the timer configuration file

Options:
  -o, --output-file <OUTPUT_FILE>  File to save results (defaults to results.json)
  -h, --help                         Print help
  -V, --version                      Print version

Configuration

Configuration files are simple JSON files with a title and a list of stages:

{
  "title": "Advent of Code",
  "stages": [
    "Introduction",
    "Problem Statement",
    "Part 1",
    "Part 2",
    "Conclusion"
  ]
}

Keyboard Controls

• Space: Start Timer / Next Stage
• P: Pause Timer
• R: Resume Timer
• S: Stop Timer
• Up/Down Arrows / Scroll Wheel: Manually scroll through the stages. Auto-scrolling is disabled when you scroll manually.
• Esc / Ctrl+C: Quit Application (a confirmation will be shown if the timer is running or has unsaved changes)

Backend Server

The application includes a backend server that runs on port 3001. This server provides a REST API for controlling the timer externally.

API Endpoints

• GET /api/state: Get the current state of the timer.
• POST /api/start: Start the timer.
• POST /api/next: Move to the next stage.
• POST /api/stop: Stop the timer.
• POST /api/pause: Pause the timer.
• POST /api/resume: Resume the timer.
• POST /api/reset: Reset the timer.

Code Structure

• src/main.rs: The entry point of the application. Handles command-line argument parsing and initializes the app.
• src/app.rs: Contains the main application logic, including the TUI event loop and state management.
• src/timer.rs: Defines the Timer struct and its associated logic for managing the timer's state.
• src/ui.rs: Responsible for rendering the terminal user interface using Ratatui.
• src/config.rs: Handles loading and parsing the JSON configuration file.
• src/server.rs: Implements the backend HTTP server using Axum.