OBS Lua - Smart Replay Organizer

Smart Replay Mover
An automatic clip organizer for OBS Studio

Files are automatically organized by game.
Smart Replay Mover is a Lua script for OBS Studio. It works on Windows and Linux with no extra software needed.
It detects your current game and moves files quickly to the correct folder.

DOWNLOAD LATEST VERSION
Full Documentation on GitHub

(I used the DeepL translator. This text was mostly generated by artificial intelligence, but I reviewed most of it and made numerous corrections to ensure it contains more useful information. I wrote the script myself and used artificial intelligence to search for information about libraries and errors, but I made sure the script is safe for users, as well as reliable and useful.)

WHAT DOES IT DO?
Press your Replay Buffer hotkey while playing CS2.
The clip is saved and automatically moved to a "Counter-Strike 2" folder.
A notification confirms the save.

Code:

Without the script:                   With the script:
Videos/                               Videos/
|-- Replay 2025-06-15 14-30.mp4       |-- Counter-Strike 2/
|-- Replay 2025-06-15 14-35.mp4       |   |-- CS2 - 2025-06-15 14-30.mp4
|-- Replay 2025-06-16 20-10.mp4       |   +-- CS2 - 2025-06-15 14-35.mp4
|-- Replay 2025-06-17 09-00.mp4       |-- Valorant/
+-- Replay 2025-06-17 18-45.mp4       |   +-- Valorant - 2025-06-16 20-10.mp4
                                      |-- Desktop/
                                      |   +-- Desktop - 2025-06-17 09-00.mp4
                                      +-- Space Marine 2/
                                          +-- Space Marine 2 - 2025-06-17 18-45.mp4

Works with recordings and screenshots too.

WHY THIS SCRIPT?

Only a single Lua file is needed—no extras.
Accurately detects OS and active game.
If anti-cheat blocks detection, it falls back to window title detection.
1900+ Built-in Games — Massive embedded database. Most games are recognized out of the box.
Cross-Platform — Works on Windows 10/11 and Linux (X11, KDE Plasma, Wayland).
Provides instant visual or audio save notifications.
Configure settings directly within OBS.

KEY FEATURES
1. INTELLIGENT GAME DETECTION
Checks the active app, not just the OBS source.

Works with: CS2, Valorant, Marvel Rivals, Sea of Thieves, Dota 2, Elden Ring, and 1900+ built-in games
Matches folders by process or window name, even with version changes or anti-cheat protection.
An optional background scan detects games when alt-tabbed (Windows only).
Smart Fallback Chain: Custom Names -> Process -> Window Title -> OBS Source -> Background Scan -> Fallback Folder
Result: 99.9% accuracy in sorting files

2. NOTIFICATION SYSTEM

Shows an overlay-style save notification with fade on Windows.
Desktop notifications via notify-send (Linux)
Sound alerts: custom WAV file, works even in exclusive fullscreen
Scaling: 100% to 300% for 4K/HiDPI monitors
Choose the screen edge for notifications.
Quiet Sound: Toggle between normal and silent notification sounds
Smart Save Hotkey: Instant "Saving..." feedback then "Clip Saved" when done. Notifications are designed to avoid interfering with gameplay, maintaining an unobstructed view at all times.

3. ORGANIZATION & FILE MANAGEMENT
Sorts all file types including clips, videos, and screenshots.

Date Subfolders: Optional monthly sorting (2025-06/)
Game Prefix: Adds game name to filename (CS2 - Replay 2025-06-15.mp4)
No-Folder Mode: Map a process to "." or "/" to keep files in output root
FFmpeg Thumbnails: Embed a gameplay frame as video cover art
Auto-Restart Buffer: Restarts Replay Buffer after save (prevents clip overlap)

Includes additional safety and convenience features:

Anti-Spam: Auto-deletes duplicate files from panic pressing the save hotkey
Case-Insensitive: Won't create "Call of Duty" AND "call of duty" folders
230+ Ignored Programs: Discord, Chrome, Steam, launchers are never mistaken for games
Import/Export: Share your custom name rules with one click
Auto Update Check: Notifies when a new version is available
Unicode Support: Full support for non-English characters.

To get started, follow these simple setup steps:
1. Extract the ZIP archive (Right-click -> Extract All)
IMPORTANT: Do not load the .zip file directly into OBS
2. Move "Smart_Replay_Mover.lua" to a safe folder (e.g., Documents)
3. Open OBS -> Tools -> Scripts
4. Click [ + ] and select the .lua file
5. Setup is complete. The script works immediately with no additional configuration required.

Linux

For Linux, follow the same setup steps. The script adapts automatically for Linux.

Install optional dependencies for full functionality:
An easy setup script is included to ensure full functionality:
1. Open a terminal in the extracted release folder.
2. Run the Linux install script:

Code:

cd "For Linux"
chmod +x install_linux_deps.sh
./install_linux_deps.sh

This script detects your package manager (apt, pacman, dnf, zypper, apk) and installs:

xprop — game detection on X11
notify-send — desktop notifications
paplay / pw-play — notification sound
ffmpeg — video thumbnails

On KDE Plasma (Wayland), game detection uses gdbus, which is normally pre-installed.

CUSTOM NAMES
Three matching modes for any situation:

Code:

MODE            FORMAT                          DESCRIPTION
──────────────────────────────────────────────────────────────────────
Exact Match     CS2 > Counter-Strike 2          Matches process identifier directly
Keywords (+)    +Warhammer Marine > SM2         Matches if ALL words found (AND logic)
Contains (*)    *Space Marine 2* > SM2          Matches if text found ANYWHERE
No-Folder       chrome > /                      Keeps files in output root (no subfolder)

Exact Match

Code:

CS2 > Counter-Strike 2

Matches the process identifier directly (without .exe). It is the simplest and fastest method.
Keywords Mode

Code:

+Warhammer Marine > Space Marine 2

Matches if all listed words are found in the process identifier or window title.
Prefix with + to activate.
Contains Mode

Code:

*Space Marine 2* > Space Marine 2

Matches if the text between * is found anywhere in the process identifier or window title.
Perfect for games with version numbers that change with updates!
Example:

Code:

*Space Marine 2*

matches

Code:

Warhammer 40,000 Space Marine 2 CLIENT v11.2.799056

No-Folder Mode

Code:

chrome > /

Map a process to /, \, or . to keep files in the OBS output root without a subfolder.
The game prefix is still added to the filename if enabled.
IMPORTANT
When using

Code:

*pattern*

, you identify the window title, not the .exe name.

Wrong:
Code:
```
cs2
```
— the window is titled "Counter-Strike 2", not "cs2".
Correct:
Code:
```
*Counter-Strike*
```
— matches the actual window title.
Wrong:
Code:
```
FactoryGamesteam
```
— the window is titled "Satisfactory".
Correct:
Code:
```
*Satisfactory*
```
— matches the actual window title.

You can Import and Export your custom names via the Backup section in settings.
Share them with friends; they import with one click.

NOTIFICATION SOUND
Want your own notification sound?
1. Prepare a short WAV file (1-2 seconds recommended)
2. Name it:

Code:

notification_sound.wav

3. Place it next to the script file:

Code:

Your Folder/
├── Smart_Replay_Mover.lua
├── notification_sound.wav            <- Normal sound
└── notification_sound_silent.wav     <- Quiet sound (optional)

4. Reload the script to finish.

Quiet Sound Option
Want a quieter notification?
1. Prepare a quieter WAV file.
2. Name it:

Code:

notification_sound_silent.wav

3. Place it in the same folder.
4. In settings, check "Use Quiet Sound".
Toggle between Normal and Quiet versions anytime. This feature works on both Windows and Linux.

VIDEO THUMBNAILS (FFMPEG)
Display a gameplay frame as the file icon in your file manager instead of a generic media player icon. This works well with Icaros on Windows.

Windows Setup
1. Download FFmpeg from gyan.dev, selecting ffmpeg-release-essentials.zip.
2. Extract it to a permanent folder (e.g.,

Code:

C:\Program Files\ffmpeg

).
3. In script settings, go to FFmpeg Thumbnails and enable it. Browse and select ffmpeg.exe (inside the

Code:

bin

folder).

Linux Setup
We recommend running the

Code:

install_linux_deps.sh

script to automatically install FFmpeg. If setting up manually:
1. Install FFmpeg using

Code:

sudo apt-get install ffmpeg

Code:

sudo pacman -S ffmpeg

.
2. In script settings, set FFmpeg Path to

Code:

ffmpeg

Code:

/usr/bin/ffmpeg

.

How it works:

MKV files — thumbnail attached as Matroska attachment (best for Icaros)
MP4 files — thumbnail embedded as attached picture stream
No re-encoding: video and audio streams are copied; only metadata is added
Completely silent — no command windows or popups

CONFIGURATION
Click on "Smart_Replay_Mover.lua" in the Scripts list to see all settings:
File Naming

Add game name prefix to filename
Fallback folder name (default: Desktop)

Custom Names

Game identifier (process, +keywords, or *pattern*)
Folder name (or . / / for no-folder mode)
Add mapping button
Your mappings list — edit or delete

Backup

Import custom names from file
Export custom names to file
Share with friends!

Buffer Control

Auto-restart Buffer after save (prevents overlap)
Auto-start Buffer on OBS launch
Smart Save Hotkey (set in OBS -> Settings -> Hotkeys)

Organization

Monthly subfolders (YYYY-MM)
Organize screenshots
Organize recordings
Scan all running processes for background games (Windows only)

Spam Protection

Cooldown between saves (0-30 seconds)
Auto-delete duplicate files

Notifications

Visual popup (Win32 overlay / notify-send)
Sound notification (works in Fullscreen too)
Scale: 100% - 300% (Windows)
Position: any corner (Windows)
Quiet Sound toggle
Duration: 1-10 seconds
Test Notification button

Tools & Debug

Debug mode — show detection details in OBS Script Log
OS Mode — Auto-Detect / Windows / Linux

FFmpeg Thumbnails

Enable/Disable thumbnail embedding
FFmpeg path (ffmpeg.exe or /usr/bin/ffmpeg)
Thumbnail offset (seconds from end of video)

TROUBLESHOOTING
Nothing happens when I save a replay?
The script detects the currently focused window.
If you Alt-Tab to OBS before pressing Save, the script sees "OBS Studio", which is in the ignore list.
How to test properly:
1. Set up your settings.
2. Alt-Tab back into the game.
3. Wait 2-3 seconds.
4. Press your save hotkey.
5. Check the output folder.
Clips go to "Desktop" instead of the game folder?
Anti-cheat games block process identifier access. If the game isn't in the built-in database, the script falls back to "Desktop". To fix this and add support for such games, use the custom naming feature (see the 'CUSTOM NAMES' section above for instructions). Creating a custom name rule for your game guarantees clips are sorted correctly, even if the game is not recognized by default.
Solution — use Contains mode:

Code:

Game:   *Sea of Thieves*
Folder: Sea of Thieves

This matches the window title, which works even with anti-cheat.
More examples:

Code:

*New World*       >  New World
*PUBG*            >  PUBG
*Satisfactory*    >  Satisfactory
*Counter-Strike*  >  Counter-Strike 2

Notifications not showing?

Exclusive Fullscreen: Popup can't overlay fullscreen apps — enable Sound as alternative
Linux: Make sure notify-send is installed (
Code:
```
which notify-send
```
)
Sound not playing: Check that notification_sound.wav is in the same folder as the script

FFmpeg not working?

Check the path is correct (browse to ffmpeg.exe on Windows / set "ffmpeg" on Linux)
Enable Debug Mode in Tools & Debug and check OBS Script Log for errors
On Linux: check file permissions for the video files

USE CASE EXAMPLES
PROBLEM: Game shows as "Warhammer 40,000 Space Marine 2 CLIENT v11.2.799056" and changes with every update.
SOLUTION: Add custom name:

Code:

*Space Marine 2* > Space Marine 2

Now all clips will be saved to the "Space Marine 2" folder, regardless of version.
PROBLEM: I want to know when clips are saved without alt-tabbing.
SOLUTION: Enable notifications in script settings!

Visual popup in Borderless/Windowed mode
Sound plays even in Exclusive Fullscreen

PROBLEM: I have many custom rules and want to share them.
SOLUTION: Use the Export button in the Backup section to save rules to a text file. Share with friends — they can Import with one click!
PROBLEM: I don't want Chrome clips in a subfolder.
SOLUTION: Add custom name:

Code:

chrome > /

Chrome clips remain in the OBS output root, with no subfolder created.

COMPATIBILITY

Windows 10 / 11
Linux — X11, KDE Plasma, Wayland via XWayland (tested on CachyOS, Arch, Ubuntu)
OBS Studio 28.x or newer
Anti-Cheat Games: Fully supported (Valorant, Marvel Rivals, Sea of Thieves, Fortnite, etc.)
Tech: Pure Lua + Win32 FFI (Windows) / xprop + gdbus (Linux) — no external DLLs

CHANGELOG
Full changelog and all releases: GitHub Releases

LICENSE & SOURCE
GPL v3 License | Open Source
GitHub: Smart Replay Mover

Made with love by SlonickLab

OBS Lua Smart Replay Organizer 2.9.0

Ratings

Share this resource