app-timer/readme.md

# App Timer (Parental Control)

Control apps usage time with a command line application.

The python daemon will watch for the apps executable and store usage time for them. It can block an app if the usage is off limits.

I'm using this at a raspberry pi gaming station (retropie) to enforce usage limits. Other use cases are very plausible, like any other gaming platform or even enforcing a pomodoro timer for your coding time. Be creative and let me know.

## Config

```yaml
# how often should the script check for apps runtime?
check-interval: 1
# timers: list of apps that will be watched
timers:
  # the app name (list key)
  gaming:
    # list of the app executables
    apps:
      - retroarch
      - minecraft
    # how many minutes of usage
    time-limit: 60
    # within how many hours of interval
    limit-interval: 12
    # optional: warn N minutes before the limit is reached
    warn-threshold: 5
    # run on every loop inside the warning window (anything executable)
    warn-command: "notify-send 'App Timer' 'Only {time_left_int} minutes left'"
    # run only on the final loop before apps are blocked
    final-warn-command: "notify-send 'App Timer' 'Last minute before shutdown'"
```

`warn-threshold` is measured in minutes and triggers the `warn-command` every loop while there is still time remaining. `final-warn-command` fires once on the last loop before the timer exceeds its limit (based on `check-interval`). All commands are executed through the shell, so they can show desktop notifications, play sounds, etc. You can interpolate values in the command string using `{timer_name}`, `{time_left}`, `{time_left_int}`, `{time_left_floor}`, and `{time_left_seconds}` (any Python format specifiers are supported, e.g. `{time_left:.1f}`).

If the systemd service runs as `root`, wrap desktop commands so they execute inside your session:

```yaml
warn-command: >
  runuser -l randogoth -c 'DISPLAY=:0 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus notify-send "App Timer" "{timer_name}: {time_left_int} minutes left"'
```

## Installation

There's a systemd service file ready for use.

```bash
  # download the sources
  cd /opt/
  git clone https://github.com/thiagof/app-timer
  cd app-timer
  # yaml dependency
  sudo -H pip3 install -r requirements.txt
  # setup the daemon
  sudo cp ./app-timer.service /etc/systemd/system/app-timer.service
  sudo systemctl enable app-timer
  # check the service
  sudo systemctl status app-timer
```

You must edit the file `config.yaml` for your timers setup.

In the code there is some python 3 so this is required. For testing the timer and check it's outputs/configs, run `python3 timer.py`.