https://github.com/lmammino/obs-countdown
A CLI tool to write countdown timer files for OBS Studio
https://github.com/lmammino/obs-countdown
cli command-line command-line-tool countdown countdown-timer obs rust
Last synced: 10 months ago
JSON representation
A CLI tool to write countdown timer files for OBS Studio
- Host: GitHub
- URL: https://github.com/lmammino/obs-countdown
- Owner: lmammino
- License: mit
- Created: 2024-03-03T19:36:26.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-09T11:52:58.000Z (about 2 years ago)
- Last Synced: 2025-05-07T23:45:17.446Z (10 months ago)
- Topics: cli, command-line, command-line-tool, countdown, countdown-timer, obs, rust
- Language: Rust
- Homepage: https://loige.co
- Size: 4.25 MB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# obs-countdown
[](https://github.com/lmammino/obs-countdown/actions/workflows/rust.yml)
[](https://codecov.io/gh/lmammino/obs-countdown)
[](https://crates.io/crates/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:
## 🛠️ 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 `: 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 in milliseconds [default: `500`]
- `--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 `: The message to display when the countdown is over [default: `00:00:00`]
- `-h, --help`: Print help
- `-V, --version`: Print version
## 🤌 Alternatives
I have come across a few alternatives to `obs-countdown` that you might want to consider:
- [Snaz](https://github.com/JimmyAppelt/Snaz): GUI-based countdown streaming tools (including a countdown timer) for Windows.
- [My Stream Timer](https://apps.apple.com/us/app/my-stream-timer/id1460539461?mt=12): GUI-based app for macOS.
If you know of any other alternative, please feel free to contribute to this list!
## 👷 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.