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 and place them in a directory that is in your PATH.

If you have cargo binstall in your system, you can use it to install the latest version of obs-countdown:

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:

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 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

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.

👩‍⚖️ License

Licensed under MIT License. © Luciano Mammino.