# obs-countdown

[![Build Status](https://github.com/lmammino/obs-countdown/actions/workflows/rust.yml/badge.svg)](https://github.com/lmammino/obs-countdown/actions/workflows/rust.yml)
[![codecov](https://codecov.io/gh/lmammino/obs-countdown/graph/badge.svg?token=2a5OOr6Um4)](https://codecov.io/gh/lmammino/obs-countdown)

A CLI tool to write countdown timer files for OBS Studio (written in Rust 🦀).

---

## 💁‍♂️ Use case

If you do live streams on platforms like Twitch or YouTube, you might want to have a countdown timer to show to your audience before the stream starts.

In OBS Studio, this is generally achieved by adding a text source linked to a file that contains the countdown timer. If you update the content of the file, OBS Studio will automatically update the text source and show the new content.

`obs-countdown` is a CLI tool that allows you to generate countdown timer files that can be used in OBS Studio. It allows you to specify the countdown duration in a natural format (e.g. `3 minutes and 22 seconds`) and it generates a file that contains a countdown timer in the format `HH:MM:SS` (which you can customise!). The file content is kept in sync with the countdown, so OBS Studio can display the current value automatically.

Here's a quick demo animation showing how `obs-countdown` can be used in conjunction with OBS Studio:

![A demo gif showing how obs-countdown works in conjunction with OBS](./docs/demo.gif)


## 🛠️ Installation

You can install `obs-countdown` using precompiled binaries (if available for your operative system and architecture) or by compiling it from source.

### Using precompiled binaries

You can download precompiled binaries from the [releases page](https://github.com/lmammino/obs-countdown/releases) and place them in a directory that is in your `PATH`.

If you have [`cargo binstall`](https://github.com/cargo-bins/cargo-binstall) in your system, you can use it to install the latest version of `obs-countdown`:

```bash
cargo binstall obs-countdown
```

This method has the advantage of automatically placing the binary in a directory that is in your `PATH`. Also, if a binary is not available for your operative system and architecture, `cargo binstall` will compile it for you (assuming you have all the necessary Rust build toolchain in your system).

### Compiling from source

If you have the Rust toolchain installed in your system, you can compile `obs-countdown` from source using `cargo`:

```bash
cargo install obs-countdown
```

### Configuring OBS Studio

To configure OBS Studio to use the countdown timer generated by `obs-countdown`, you can follow these steps:

1. Decide a location where you want to store the countdown timer file (e.g. `~/countdown.txt`).
2. In OBS Studio, add a new [text source](https://obsproject.com/kb/text-sources) to your "starting soon" scene and link it to the file you have chosen (by ticking the option `From file` under `Text input mode`).
3. Set the font, size, color, and position of the text source as you prefer.
4. Before going live, run `obs-countdown` to generate the countdown timer file and keep it running in the background (e.g. `obs-countdown --file ~/countdown.txt 5 minutes`).


## 👩‍🏫 Usage

```bash
obs-countdown [OPTIONS] [COUNTDOWN...]
```

### Arguments

- `[COUNTDOWN]...`: Countdown duration expression (e.g. "1h 30m 10s"). The countdown expression system is very flexible, here are some examples of what is supported:
  - `1h30m10s`: 1 hour, 30 minutes and 10 seconds
  - `1h and 30mins`: 1 hour and 30 minutes
  - `1h`: 1 hour
  - `2h,10s`: 2 hours and 10 seconds
  - `30m and 22secs`: 30 minutes and 22 seconds
  - `1 hour, 30 minutes, and 10 seconds`: 1 hour, 30 minutes, and 10 seconds!

### Options

-  `-f, --file <FILE>`: Path to the file where to store the countdown. If the file does not exist, it will be created. If no file is provided, it will create a file called `obs-countdown.txt` in the current directory.
- `-r, --refresh-rate <REFRESH_RATE>`: Refresh rate in milliseconds [default: `500`]
- `--format <FORMAT>`: The format string to use to render the remaining time. [default: `%H:%M:%S`]. The format string is a string that can contain the following placeholders:
  - `%h`: hours
  - `%H`: hours, zero-padded
  - `%m`: minutes
  - `%M`: minutes, zero-padded
  - `%s`: seconds
  - `%S`: seconds, zero-padded 
- `--final-message <FINAL_MESSAGE>`:  The message to display when the countdown is over [default: `00:00:00`]
- `-h, --help`: Print help
- `-V, --version`: Print version


## 👷 Contributing

Everyone is very welcome to contribute to this project.
You can contribute just by submitting bugs or suggesting improvements by
[opening an issue on GitHub](https://github.com/lmammino/obs-countdown/issues).


## 👩‍⚖️ License

Licensed under [MIT License](LICENSE). © Luciano Mammino.