master upload

README.md

@@ -1,2 +1,42 @@
-# obs-uptime-to-file
-
+# OBS Uptime to File Lua Script
+
+This OBS Studio Lua script writes your current stream uptime to a text file, with customizable formatting. You can use this file as a source in OBS (e.g., with a Text GDI+ source) to display your live stream duration.
+
+## Features
+- Writes the current stream uptime to a file while streaming.
+- Lets you choose the output file location via the script settings.
+- Lets you customize the output format (e.g., `01:23:45`, `1h 23m`, `83 minutes`).
+- When the stream stops, the file is automatically erased (emptied).
+
+## Installation
+1. Download or copy the `obs_uptime_to_file.lua` script to your computer.
+2. Open OBS Studio.
+3. Go to `Tools` > `Scripts`.
+4. Click the `+` button and select `obs_uptime_to_file.lua`.
+5. Set the `Output File Path` to where you want the uptime to be written.
+6. (Optional) Set the `Format String` to customize how the uptime appears.
+
+## Format String
+You can control how the uptime is displayed using the `Format String` property. Use these placeholders:
+- `{h}`: Hours (zero-padded, e.g., 01)
+- `{m}`: Minutes (zero-padded, e.g., 09)
+- `{s}`: Seconds (zero-padded, e.g., 05)
+- `{H}`: Hours (no padding, e.g., 1, 12)
+- `{M}`: Minutes (no padding, e.g., 9, 23)
+- `{S}`: Seconds (no padding, e.g., 5, 45)
+
+**Examples:**
+ - `{h}:{m}:{s}` → `01:23:45`
+ - `{H}:{M}:{S}` → `1:23:5`
+ - `{H}h {M}m` → `1h 23m` (or just `23m` if under 1 hour)
+ - `{M} minutes` → `83 minutes`
+
+## How It Works
+- When you start streaming, the script begins writing the uptime to your chosen file every second.
+- When you stop streaming, the file is erased (emptied), so nothing will display if you use it as a text source.
+
+## Use Case
+Add the output file as a Text (GDI+) source in OBS to show your stream uptime on your overlay. The file will always be up-to-date while you are live, and will be blank when you are not streaming.
+
+## License
+MIT License. Feel free to use, modify, and share.