Bring frame-accurate, customizable timecode to your OBS Studio scenes with a fast Go backend and a simple Python client script.
Note
I built this tool to get better, frame-accurate timecode overlays for videos that will be used with Metahuman Animator and other workflow tools I plan to build for advanced video and animation pipelines in Unreal Engine.
Important
This plugin was inspired by the fantastic RTC Timecode OBS RTC Timecode for text source built by Scott Pessoni
- 🎥 Frame-Accurate Timecode: Get real-time, frame-precise timecode in your OBS scenes—perfect for live production, VOD, or creative overlays.
- ⚡ Go-Powered Speed: The server is written in Go for reliability and low-latency updates.
- 🧩 Separation of Concerns: The Go server handles all time logic; the Python script just fetches and displays it.
- 🖥️ Cross-Platform: Works on Windows, macOS, and Linux (with minor tweaks if needed).
- 🛠️ Customizable: Supports 12/24hr, frames, date, UTC, prefix/suffix, and more.
- 🐍 Easy OBS Integration: The Python script provides a familiar UI in OBS and updates your text source automatically.
- Get the latest
obs-timecode-server.exe(Go server) andobs-timecode-generator.py(OBS Python script) from the Releases page.
- Double-click or run in terminal:
.\obs-timecode-server.exe [--port 8080] [--fps 30] [--debug]
- By default, it listens on
127.0.0.1:8080with 30 FPS.
- Add a new Text (GDI+) source named TimecodeDisplay to your scene.
- In OBS, go to Tools > Scripts, add
obs-timecode-generator.py, and configure settings (host, port, format, etc.). - The script will connect to the Go server and update your text source in real time.
- HH:MM:SS and HH:MM:SS:FF (frames) formats
- 12/24hr, AM/PM, date, UTC/GMT
- Custom prefix/suffix
- Error/status messages in the text source
- All settings configurable in OBS
This tool generates timecode (HH:MM:SS:FF) for a text source in OBS based on your computer's Real-Time Clock (RTC). Why does this matter?
- Precision: By leveraging Go's time package, which uses monotonic clocks under the hood, the server delivers highly accurate, drift-resistant timecode. This is a big step up from traditional Lua or Python scripts that rely on less precise timing.
- Frame-Accurate: The Go backend calculates frames using elapsed nanoseconds, not just function call frequency, so your timecode stays in sync even if polling is irregular.
- SMPTE-Style: The timecode is perfect for slates, live video, latency checks, and workflows like Unreal Engine's Metahuman Animator, where frame-accurate overlays are essential.
- RTC Tips:
- Synchronize your computer's clock with an internet time server for best results.
- A monospaced font is recommended to prevent the timecode from "jumping" as it updates.
- Showing frames (FF) increases CPU usage, as the text source must update every frame—use only if needed.
- Text Source: The OBS source to which the timecode is applied.
- Mode: 24 Hour, 12 Hour, or 12 Hour + AM/PM.
- Show Frames: Adds :FF to the timecode. More CPU usage, but essential for frame-accurate workflows.
- Show Date: Prepends YYYY-MM-DD.
- Show UTC(GMT): Displays time in Coordinated Universal Time.
- Prefix/Suffix Text: Add custom text before or after the timecode.
- Update when not in program: ("Keep Updated") Updates timecode even when the source isn't visible in Program. Useful for logging, multiview, or NDI feeds, but increases CPU load.
SMPTE timecode is a standard for labeling video frames, used in TV and film for sync and logging. This tool uses your computer's RTC for non-drop frame (NDF) timecode. Drop-frame is not implemented (yet), but the Go backend makes it possible to extend in the future.
Older scripts (like Lua) only had access to second-level precision and incremented frames by counting calls. This Go version uses monotonic time for true elapsed nanosecond accuracy, so your timecode is as close to real-world as your hardware allows.
You can now "jam" (synchronize) the server to an external timecode using the /jam endpoint. This is useful for aligning the server's timecode with an external source (e.g., LTC, MIDI, or another system).
Send a POST request to http://localhost:8080/jam with a JSON body. Supported formats:
- SMPTE timecode string:
{ "timecode": "12:34:56:12", "fps": 30 } - ISO datetime:
{ "datetime": "2025-05-15T12:34:56.400Z" } - Unix timestamp (milliseconds):
{ "timestamp": 1747312496400 }
After jamming, all /timecode responses will reflect the new reference time.
- Keep your system clock synced for best accuracy.
- Only enable "Show Frames" or "Keep Updated" if you need them—these options increase CPU usage.
- Use a fixed-width font for the text source.
- If the timecode doesn't update, check that the source is visible or enable "Keep Updated".
Want to build the Go server yourself? No problem!
- Install Go: (https://go.dev/dl/)
- Clone the Repository:
git clone https://github.com/yourusername/obs-timecode-generator.git cd obs-timecode-generator - Build the Server:
This will create
go mod tidy go build -o obs-timecode-server.exe .obs-timecode-server.exein the project directory. - (Optional) Edit or Extend:
- The Go server code is in
main.goand theserver/directory. - The OBS Python script is
obs-timecode-generator.py—edit as needed for your workflow.
- The Go server code is in
- Developed and tested on Windows 10/11 with OBS Studio 30.x
- Should work on macOS/Linux (feedback welcome!)
- Both the Go server and Python script are designed to be cross-platform, but minor tweaks may be needed for non-Windows setups.
- "SERVER OFFLINE?" in OBS: Make sure the Go server is running and the host/port match.
- No timecode, no error: Check your text source name and OBS script log for Python errors.
- Go server crashes: See the terminal for error messages.
Pull requests, issues, and feedback are welcome—especially for cross-platform improvements and advanced workflow integrations!
Made with ❤️, and golang , and some Python