mytimer 2.5
A Geeky Timer for Terminal Enthusiasts
License: MIT
Requires Python: >=3.7
Keywords: timer time clock terminal stopwatch cli geek


<div align="center">
<img src="https://github.com/sepandhaghighi/mytimer/raw/main/otherfiles/logo.png" width="500">
<h1>MyTimer: A Geeky Timer for Terminal Enthusiasts</h1>
<br/>
<a href="https://badge.fury.io/py/mytimer"><img src="https://badge.fury.io/py/mytimer.svg" alt="PyPI version"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
<a href="https://github.com/sepandhaghighi/mytimer"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/sepandhaghighi/mytimer"></a>
</div>			
				
## Overview	

<p align="justify">					
<strong>MyTimer</strong> is a Python project that aims to provide a simple yet efficient timer for terminal users, particularly targeting the geek community. This project allows users to set timers directly from their command line interface, making it convenient for those who spend a significant amount of time working in the terminal!

The main objective of <strong>MyTimer</strong> is to offer a minimalistic and distraction-free timer experience. It provides a clean and straightforward interface, ensuring that users can focus solely on tracking time without any unnecessary clutter or distractions.
</p>

<table>
	<tr>
		<td align="center">PyPI Counter</td>
		<td align="center"><a href="http://pepy.tech/project/mytimer"><img src="http://pepy.tech/badge/mytimer"></a></td>
	</tr>
	<tr>
		<td align="center">Github Stars</td>
		<td align="center"><a href="https://github.com/sepandhaghighi/mytimer"><img src="https://img.shields.io/github/stars/sepandhaghighi/mytimer.svg?style=social&label=Stars"></a></td>
	</tr>
</table>



<table>
	<tr> 
		<td align="center">Branch</td>
		<td align="center">main</td>	
		<td align="center">dev</td>	
	</tr>
	<tr>
		<td align="center">CI</td>
		<td align="center"><img src="https://github.com/sepandhaghighi/mytimer/actions/workflows/test.yml/badge.svg?branch=main"></td>
		<td align="center"><img src="https://github.com/sepandhaghighi/mytimer/actions/workflows/test.yml/badge.svg?branch=dev"></td>
	</tr>
</table>


<table>
	<tr> 
		<td align="center">Code Quality</td>
		<td align="center"><a href="https://www.codefactor.io/repository/github/sepandhaghighi/mytimer"><img src="https://www.codefactor.io/repository/github/sepandhaghighi/mytimer/badge" alt="CodeFactor"></a></td>
		<td><a href="https://app.codacy.com/gh/sepandhaghighi/mytimer/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/1bf28500431a498998ac79891cd79cda"></a></td>
	</tr>
</table>


## Installation		

### Source Code
- Download [Version 2.5](https://github.com/sepandhaghighi/mytimer/archive/v2.5.zip) or [Latest Source](https://github.com/sepandhaghighi/mytimer/archive/dev.zip)
- `pip install .`				

### PyPI

- Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
- `pip install mytimer==2.5`						


## Usage

ℹ️ You can use `mytimer` or `python -m mytimer` to run this program

### Version

```console
mytimer --version
```

### Info

```console
mytimer --info
```

### Basic

ℹ️ Press `Ctrl + C` to exit

```console
mytimer
```

### Time Limit

```console
mytimer --minute=7 --second=30
```

```console
mytimer --hour=2 --minute=20
```

### Timer Mode

ℹ️ The default mode is `countdown`

```console
mytimer --minute=7 --second=30 --countdown
```	

```console
mytimer --minute=7 --second=30 --countup
```	

### Repeat

ℹ️ The default value is `1`

```console
mytimer --repeat=3 --second=4
```
* Use `--repeat=-1` for infinite loop

### Alarm

⚠️ This mode may not be supported on all systems

```console
mytimer --minute=7 --second=30 --alarm
```

### Alarm Repeat

ℹ️ The default value is `1`

```console
mytimer --minute=7 --second=30 --alarm --alarm-repeat=5
```

### Tone

ℹ️ The default tone is `1`

```console
mytimer --minute=7 --second=30 --alarm --tone=2
```
* Use `--tone=-1` for random mode
* Use `--test-tone` for test
* [Tones List](https://github.com/sepandhaghighi/mytimer/blob/main/TONES.md)

### Face


```console
mytimer --minute=7 --second=30 --face=3
```
* Use `--face=-1` for random mode
* [Faces List](https://github.com/sepandhaghighi/mytimer/blob/main/FACES.md)
* `mytimer --faces-list`


### Vertical/Horizontal Shift

ℹ️ The vertical and horizontal shift both have default values of `0`

```console
mytimer --v-shift=20 --h-shift=30
```

### Timer Sign

ℹ️ Valid choices: [`""`, `"+"`, `"-"`]

```console
mytimer --sign="+"
```

### Keep on

In this mode, the timer will continue running after it times out

```console
mytimer --minute=5 --keep-on
```

### Hide Second

In this mode, the timer seconds counter will not be shown

```console
mytimer --minute=6 --hide-second
```

### Hide Date/Time

In this mode, the date/time will not be shown

```console
mytimer --minute=20 --hide-datetime
```

### Date System

ℹ️ Valid choices: [`gregorian`, `jalali`]

ℹ️ The default date system is `gregorian`

```console
mytimer --minute=20 --date-system=jalali
```

### Vertical Mode

```console
mytimer --minute=5 --vertical
```

### Set on

⚠️ Local time

In this mode, the timer sets on the given time. For example, here we set a timer for `15:05`:

```console
mytimer --hour=15 --minute=5 --set-on
```

### Program

```console
mytimer --program=black-tea
```
* [Programs List](https://github.com/sepandhaghighi/mytimer/blob/main/PROGRAMS.md)
* `mytimer --programs-list`

### Message


```console
mytimer --minute=7 --second=30 --message="Test message"
```

### Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `lightblack`, `lightred`, `lightgreen`, `lightyellow`, `lightblue`, `lightmagenta`, `lightcyan`, `lightwhite`]

ℹ️ The default color is `white`

```console
mytimer --minute=7 --second=30 --color="red"
```

### Background Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `lightblack`, `lightred`, `lightgreen`, `lightyellow`, `lightblue`, `lightmagenta`, `lightcyan`, `lightwhite`]

ℹ️ The default background color is `black`

```console
mytimer --minute=7 --second=30 --bg-color="blue"
```

### Intensity

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [`normal`, `bright`, `dim`]

ℹ️ The default intensity is `normal`

```console
mytimer --minute=7 --second=30 --intensity="bright"
```

## Screen Record

<div align="center">

<img src="https://github.com/sepandhaghighi/mytimer/raw/main/otherfiles/help.gif">

</div>


## Issues & Bug Reports			

Just fill an issue and describe it. We'll check it ASAP!

- Please complete the issue template
 			

## References

<blockquote>1- <a href="https://mixkit.co/free-sound-effects/alarm/">Mixkit Free Alarm Sound Effects</a></blockquote>

<blockquote>2- <a href="https://www.online-timers.com/">Online Timer</a></blockquote>

<blockquote>3- <a href="https://www.mediacollege.com/">Media College</a></blockquote>

<blockquote>4- <a href="https://en.wikipedia.org/wiki/Pomodoro_Technique">Pomodoro Technique</a></blockquote>

<blockquote>5- <a href="https://www.themuse.com/advice/the-rule-of-52-and-17-its-random-but-it-ups-your-productivity">The Rule of 52 and 17: It's Random, But it Ups Your Productivity</a></blockquote>

<blockquote>6- <a href="https://desktime.com/blog/productivity-research">Desktime’s Productivity Research: An Overview of Our Finds Throughout the Years</a></blockquote>

<blockquote>7- <a href="https://ankushkun.github.io/animedoro-timer/Animedoro/">AnimeDoro Timer</a></blockquote>

<blockquote>8- <a href="https://worldteadirectory.com/know-tea-guide-tea-steeping-time/">Know Your Tea: Your Guide to Tea Steeping Time</a></blockquote>

<blockquote>9- <a href="https://artfultea.com/blogs/101/loose-leaf-tea-steep-time">How Long to Steep Tea: A Complete Guide</a></blockquote>

<blockquote>10- <a href="https://majestycoffee.com/blogs/posts/how-long-to-steep">How Long to Steep French Press: Mastering the Perfect Brew</a></blockquote>

<blockquote>11- <a href="https://freesound.org">Freesound</a></blockquote>

<blockquote>12- <a href="https://www.online-timer.net/">Online Timer with Alarm and Sound</a></blockquote>


## Show Your Support
								
<h3>Star This Repo</h3>					

Give a ⭐️ if this project helped you!

<h3>Donate to Our Project</h3>	

<h4>Bitcoin</h4>
1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy
<h4>Ethereum</h4>
0xcD4Db18B6664A9662123D4307B074aE968535388
<h4>Litecoin</h4>
Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ
<h4>Doge</h4>
DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh
<h4>Tron</h4>
TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7
<h4>Ripple</h4>
rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq
<h4>Binance Coin</h4>
bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef
<h4>Tether</h4>
0xcD4Db18B6664A9662123D4307B074aE968535388
<h4>Dash</h4>
Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s
<h4>Stellar</h4>		
GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL
<h4>Zilliqa</h4>
zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5
<h4>Coffeete</h4>
<a href="http://www.coffeete.ir/opensource">
<img src="http://www.coffeete.ir/images/buttons/lemonchiffon.png" style="width:260px;">
</a>


# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [Unreleased]
## [2.5] - 2026-02-10
### Added
- `--intensity` argument
- Light colors
### Changed
- `README.md` updated
- Test system modified
- Background color bug fixed
- `set_color` function modified
- `set_bg_color` function modified
- `run_timer` function modified
- Arguments moved to `handle_args` function
- `main` function moved to `functions.py`
- `--set-on` flag bug fixed
- Screen record updated
## [2.4] - 2025-12-04
### Added
- `--color` argument
- `--bg-color` argument
### Changed
- `load_program_params` function modified
- `pomodoro_timer` function modified
- `two_step_timer` function modified
- `select_timer_func` function renamed to `select_timer_function`
- `mytimer_info` function renamed to `print_mytimer_info`
- `run_timer` function modified
- `Python 3.14` added to `test.yml`
- `README.md` updated
- Test system modified
## [2.3] - 2025-07-17
### Added
- 2 new programs
	1. `eye-break`
	2. `power-nap`
- Start time
### Changed
- `README.md` updated
- Python typing features added to all modules
- `print_date_time` function modified
- Test system modified
- `Python 3.6` support dropped
## [2.2] - 2025-03-13
### Added
- `--date-system` argument
### Changed
- `README.md` updated
- Test system modified
- `countdown_timer` and `countup_timer` functions updated
- String templates modified
- Input case sensitivity bug fixed
## [2.1] - 2025-02-28
### Added
- 4 new tones
- `--vertical` argument
- `--test-tone` argument
### Changed
- `README.md` updated
- Test system modified
- `countdown_timer` and `countup_timer` functions updated
## [2.0] - 2025-01-30
### Added
- 2 new programs
	1. `coffee-break`
	2. `meditation`
- Clock and date
- `--hide-datetime` argument
### Changed
- `README.md` updated
- Test system modified
- `countdown_timer` and `countup_timer` functions updated
## [1.9] - 2024-12-18
### Added
- 5 new tones
- `--info` argument
- `--hide-second` argument
### Changed
- GitHub actions are limited to the `dev` and `main` branches
- `countdown_timer` and `countup_timer` functions updated
- `README.md` updated
- `TONES.md` updated
## [1.8] - 2024-10-23
### Added
- 5 new tones
- Face random mode
- Tone random mode
- `get_face` function
- `get_tone` function
### Changed
- `show_faces_list` function updated
- `README.md` updated
- Test system modified
- `Python 3.13` added to `test.yml`
## [1.7] - 2024-10-09
### Added
- 2 new programs
	1. `mate`
	2. `french-press`
- 9 new tones
### Changed
- `README.md` updated
## [1.6] - 2024-08-30
### Added
- 2 new programs
	1. `puer-tea`
	2. `purple-tea`
- `--set-on` argument
### Changed
- Default mode changed from `count-up` to `countdown`
- `white-tea` program duration changed from `10` minutes to `3` minutes
## [1.5] - 2024-08-12
### Added
- 2 new programs
	1. `rooibos-tea`
	2. `yellow-tea`
- `--keep-on` argument
### Changed
- `README.md` updated
- Programs message updated
## [1.4] - 2024-07-15
### Added
- 1 new program
	1. `mid-break`
- `--repeat` argument
- `--sign` argument
### Changed
- `long-break` program duration changed from `15` minutes to `30` minutes
- `README.md` updated
## [1.3] - 2024-05-23
### Added
- 1 new program
	1. `animedoro`
- `two_step_timer` function
- `print_message` function
- `SECURITY.md`
### Changed
- Test system modified
- `nava` added to `requirements.txt`
- Sound playing system updated
- Python 3.5 dropped
- `short-break` program duration changed from `10` minutes to `5` minutes
- `long-break` program duration changed from `30` minutes to `15` minutes
- `pomodoro` program updated
- `pomodoro_timer` function modified
- `load_params` function modified
- `README.md` updated
### Removed
- `animedoro_timer` function
- `_112_26_timer` function
- `_52_17_timer` function
## [1.2] - 2024-02-05
### Added
- `feature_request.yml` template
- `config.yml` for issue template
- 2 new programs
	1. `52-17`
	2. `112-26`
### Changed
- Bug report template modified
- `run_timer` function modified
## [1.1] - 2023-12-20
### Added
- 1 new program
	1. `pomodoro`
### Changed
- `TIME_PRINT_TEMPLATE` changed
- `KeyboardInterrupt` exit handling updated
- `ADDITIONAL_INFO` added to argparser epilog
- `Python 3.12` added to `test.yml`
## [1.0] - 2023-11-08
### Added
- `--programs-list` argument
- `--faces-list` argument
- `--v-shift` argument
- `--h-shift` argument
- `DEFAULT_PARAMS` parameter
- `PROGRAMS_DEFAULTS` parameter
- `load_program_params` function
### Changed
- `japanese-green-tea` program bug fixed
- `README.md` updated
## [0.9] - 2023-10-04
### Added
- 4 new faces
- 4 new programs
	1. `work`
	2. `short-break`
	3. `long-break`
	4. `noodle`
### Changed
- `PROGRAMS.md` updated
## [0.8] - 2023-08-07
### Added
- Logo
- `--alarm-repeat` argument
### Changed
- Tones length modified
- `README.md` updated
## [0.7] - 2023-07-23
### Added
- `--tone` argument
- `TONES.md`
- 9 new tones
### Changed
- Test system modified
- `input_check` decorator renamed to `input_handler`
- `countup_timer` function inputs modified
- `countdown_timer` function inputs modified
- `PROGRAMS.md` updated
- `FACES.md` updated
## [0.6] - 2023-07-04
### Added
- `--program` argument
- `PROGRAMS.md`
- `run_timer` function
### Changed
- Inputs type changed to `int`
- `README.md` updated
- `WRONG_INPUT_ERROR` renamed to `INPUT_ERROR_MESSAGE`
- Alarm tone changed
## [0.5] - 2023-05-25
### Added
- 5 new faces
- `--message` argument
### Changed
- `play_sound` function modified
- `playsound` removed from `requirements.txt`
- `README.md` updated
## [0.4] - 2023-02-10
### Added
- 4 new faces
- Infinite timer mode
### Changed
- `README.md` updated
- Parameters moved to `params.py`
## [0.3] - 2022-11-25
### Added
- `--face` argument
- `FACES.md`
### Changed
- `README.md` updated
- Minimum `art` library version changed from `1.8` to `2.9`
## [0.2] - 2022-11-03
### Added
- `--version` flag
### Changed
- Test system modified
- `countdown_timer` function modified
- `countup_timer` function modified
## [0.1] - 2022-10-18
### Added
- Countdown mode
- Count-up mode
- Alarm

[Unreleased]: https://github.com/sepandhaghighi/mytimer/compare/v2.5...dev
[2.5]: https://github.com/sepandhaghighi/mytimer/compare/v2.4...v2.5
[2.4]: https://github.com/sepandhaghighi/mytimer/compare/v2.3...v2.4
[2.3]: https://github.com/sepandhaghighi/mytimer/compare/v2.2...v2.3
[2.2]: https://github.com/sepandhaghighi/mytimer/compare/v2.1...v2.2
[2.1]: https://github.com/sepandhaghighi/mytimer/compare/v2.0...v2.1
[2.0]: https://github.com/sepandhaghighi/mytimer/compare/v1.9...v2.0
[1.9]: https://github.com/sepandhaghighi/mytimer/compare/v1.8...v1.9
[1.8]: https://github.com/sepandhaghighi/mytimer/compare/v1.7...v1.8
[1.7]: https://github.com/sepandhaghighi/mytimer/compare/v1.6...v1.7
[1.6]: https://github.com/sepandhaghighi/mytimer/compare/v1.5...v1.6
[1.5]: https://github.com/sepandhaghighi/mytimer/compare/v1.4...v1.5
[1.4]: https://github.com/sepandhaghighi/mytimer/compare/v1.3...v1.4
[1.3]: https://github.com/sepandhaghighi/mytimer/compare/v1.2...v1.3
[1.2]: https://github.com/sepandhaghighi/mytimer/compare/v1.1...v1.2
[1.1]: https://github.com/sepandhaghighi/mytimer/compare/v1.0...v1.1
[1.0]: https://github.com/sepandhaghighi/mytimer/compare/v0.9...v1.0
[0.9]: https://github.com/sepandhaghighi/mytimer/compare/v0.8...v0.9
[0.8]: https://github.com/sepandhaghighi/mytimer/compare/v0.7...v0.8
[0.7]: https://github.com/sepandhaghighi/mytimer/compare/v0.6...v0.7
[0.6]: https://github.com/sepandhaghighi/mytimer/compare/v0.5...v0.6
[0.5]: https://github.com/sepandhaghighi/mytimer/compare/v0.4...v0.5
[0.4]: https://github.com/sepandhaghighi/mytimer/compare/v0.3...v0.4
[0.3]: https://github.com/sepandhaghighi/mytimer/compare/v0.2...v0.3
[0.2]: https://github.com/sepandhaghighi/mytimer/compare/v0.1...v0.2
[0.1]: https://github.com/sepandhaghighi/mytimer/compare/daa2be6...v0.1